Come elencare le conversazioni nei ticket di Zoho Desk

Elencare tutte le conversazioni su un ticket di Zoho Desk è semplice una volta che conosci il corretto endpoint API e gli scope OAuth richiesti. Questo articolo ti guida attraverso la chiamata esatta e cosa verificare in seguito.

Perché è importante

I flussi di lavoro del supporto richiedono spesso accesso programmatico all'intero thread di risposte, note e inoltri associati a un ticket — per reportistica, automazione o integrazione con altri strumenti. Sapere come recuperare l'elenco delle conversazioni tramite l'API di Zoho Desk ti consente di costruire pipeline affidabili senza esportare manualmente i dati dall'interfaccia utente. In qualità di supporto esperto indipendente (non supporto ufficiale Zoho), Beam Help documenta questo schema affinché il tuo team possa implementarlo con sicurezza.

Procedura passo dopo passo

Passaggio 1. Verifica che il tuo token OAuth includa gli scope Desk corretti prima di effettuare qualsiasi chiamata API. Come minimo hai bisogno di Desk.tickets.READ nel tuo elenco di scope; le integrazioni più ampie includono tipicamente anche Desk.tickets.ALL per coprire le operazioni di lettura, scrittura, creazione, aggiornamento ed eliminazione in un'unica concessione. ^[2]

Passaggio 2. Identifica il ticket_id del ticket di cui vuoi recuperare le conversazioni. Questo è l'identificatore numerico interno di Zoho Desk per il record del ticket — non il numero di ticket visualizzato ai clienti. Puoi ottenerlo da una precedente ricerca di ticket o dall'URL del dettaglio del ticket nel portale agenti di Desk. ^[7]

Passaggio 3. Invia una richiesta GET all'endpoint delle conversazioni, sostituendo l'ID del tuo ticket nel percorso:

GET /api/v1/tickets/{ticket_id}/conversations

Includi il tuo token bearer OAuth nell'intestazione Authorization come di consueto. Il parametro opzionale p può essere passato come dizionario nella query string per controllare la paginazione o il filtraggio dell'elenco di conversazioni restituito. ^[8]

Passaggio 4. Analizza la risposta. L'endpoint restituisce l'elenco delle voci di conversazione associate a quel ticket — risposte, commenti pubblici, note private e messaggi inoltrati sono tutti accessibili tramite questa singola chiamata. Itera sull'array restituito per accedere ai singoli corpi dei messaggi, ai timestamp, ai dettagli dell'autore e alle informazioni sul canale. ^[8]

Passaggio 5. Se stai costruendo un'interfaccia utente o un assistente su questi dati, associa ogni voce di conversazione all'URL del portale agenti del ticket in modo che gli agenti possano accedere direttamente al record. Il pattern di deep-link di Desk segue il formato https://desk.zoho.{dc}/agent/{portal}/tickets/details/{ticket_id}, dove dc è il suffisso del tuo data center (ad es. com, eu, in) e portal è il nome del tuo portale Desk. ^[7]

Errori comuni

• Scope mancanti o insufficienti. Se al tuo client OAuth è stato concesso solo Desk.search.READ o scope a livello di contatto, l'endpoint delle conversazioni restituirà un errore di autorizzazione. Verifica che Desk.tickets.READ (o Desk.tickets.ALL) sia presente nella stringa degli scope del token. ^[2]

• Formato ID ticket errato. Passare il numero di ticket visibile al cliente invece del ticket_id interno risulterà in una risposta 404 o vuota. Risolvi sempre prima l'ID interno tramite una ricerca o una chiamata di lookup del ticket prima di chiamare l'endpoint delle conversazioni. ^[8]

• Mancata corrispondenza del data center. Zoho Desk è ospitato su più data center regionali. Assicurati che l'URL base che utilizzi (desk.zoho.com, desk.zoho.eu, ecc.) corrisponda alla regione in cui è stato eseguito il provisioning dell'account Desk della tua organizzazione; le richieste indirizzate alla regione sbagliata non supereranno l'autenticazione. ^[7]

• Paginazione non gestita. Per i ticket con lunghe cronologie di conversazioni, l'API restituisce i risultati in pagine. Usa il parametro p per scorrere le pagine ed evitare di troncare silenziosamente l'elenco delle conversazioni. ^[8]

Cosa verificare

• Copertura degli scope: Verifica che il tuo token OAuth attivo contenga Desk.tickets.READ o Desk.tickets.ALL ispezionando gli scope concessi nella tua console API di Zoho. ^[2]
• Percorso endpoint corretto: Conferma che l'URL della richiesta si risolva in /api/v1/tickets/{ticketid}/conversations con un ticketid numerico valido sostituito. ^[8]
• Paginazione completa: Se la risposta include un indicatore nextPage o un conteggio totale superiore alla dimensione di pagina predefinita, assicurati che la tua integrazione scorra tutte le pagine prima di elaborare i risultati. ^[8]