Come elencare i ticket per contatto in Zoho Desk

Elencare tutti i ticket di supporto associati a un contatto specifico in Zoho Desk è semplice una volta ottenuto l'ID del contatto — una singola chiamata API restituisce l'elenco completo dei ticket per quella persona.

Perché è importante

Quando un cliente contatta il tuo team di supporto più volte, hai bisogno di una visione consolidata di ogni ticket che ha mai aperto. Questo è essenziale per comprendere la cronologia di un contatto prima di rispondere, per le revisioni di escalation e per i report sui contatti ad alto volume. Senza questa ricerca, gli agenti devono cercare o filtrare manualmente, il che è lento e soggetto a errori.

Procedura passo dopo passo

Passaggio 1. Identifica il contact_id della persona di cui vuoi recuperare i ticket. Puoi trovarlo navigando su Contatti all'interno del tuo portale Zoho Desk (il pattern dell'URL segue desk.zoho.com/agent/{portal}/contacts) oppure interrogando prima l'endpoint dei contatti. L'ID è l'identificatore numerico univoco mostrato nell'URL del record del contatto. ^[1]

Passaggio 2. Verifica che il tuo token OAuth includa gli scope corretti di Zoho Desk. Come minimo hai bisogno di Desk.tickets.READ e Desk.contacts.READ per risolvere il contatto e leggere i suoi ticket. Se stai utilizzando un'integrazione più ampia, scope come Desk.tickets.ALL copriranno anch'essi questa operazione. ^[5]

Passaggio 3. Effettua una richiesta GET al seguente endpoint dell'API Zoho Desk, sostituendo l'identificatore reale del contatto nel percorso: ^[2]

GET /api/v1/contacts/{contact_id}/tickets

L'operazione è identificata internamente come listticketsbycontact. Il parametro di percorso contactid è obbligatorio; il parametro di query opzionale p può essere utilizzato per gestire la paginazione. ^[2]

Passaggio 4. In Python, la chiamata si presenta così: ^[2]

def list_tickets_by_contact(self, contact_id: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/contacts/{contact_id}/tickets", p, None)

Passa l'ID del contatto come stringa. Se hai bisogno di una pagina specifica di risultati, fornisci un dizionario di paginazione come secondo argomento; altrimenti lascialo come None. ^[2]

Passaggio 5. Analizza la risposta. L'API Zoho Desk restituisce record di ticket contenenti campi chiave come oggetto, stato, agente assegnato e reparto. Il nostro team consiglia di visualizzare come minimo: oggetto del ticket, stato attuale e agente responsabile, in modo che il chiamante ottenga un riepilogo immediatamente utilizzabile. ^[6]

Passaggio 6. Se desideri un link diretto nel browser a qualsiasi ticket restituito nella risposta, il pattern URL da costruire è: ^[3]

https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}

Sostituisci {dc} con il suffisso del tuo data center (ad es. com, eu, in), {portal} con il nome del tuo portale Desk e {TicketId} con l'ID dalla risposta API. ^[3]

---

*Beam Help è una risorsa di supporto esperto indipendente — non è il supporto ufficiale di Zoho.*

Errori comuni

• orgId mancante o errato: Zoho Desk richiede che l'ID organizzazione venga inviato con ogni richiesta API. Se è assente, il sistema tenterà di rilevarlo automaticamente chiamando prima l'endpoint delle organizzazioni, quindi persisterà il valore per le chiamate future. Se riscontri errori di autenticazione o "org not found", verifica che deskorgid sia correttamente memorizzato e passato al client. ^{[7] [8]}
• Scope OAuth insufficienti: La richiesta di ticket relativi a un contatto richiede sia i permessi di lettura del contatto che quelli del ticket. Se il tuo token è stato emesso senza Desk.contacts.READ o Desk.tickets.READ, l'API restituirà un errore di permesso. Ri-autorizza con il set completo di scope. ^[5]
• Paginazione non gestita: Il parametro p controlla quale pagina di risultati viene restituita. Se un contatto ha molti ticket e ometti la gestione della paginazione, vedrai solo la prima pagina. Scorri le pagine finché la risposta non restituisce un numero di record inferiore alla dimensione della pagina. ^[2]
• Data center errato: L'URL base deve corrispondere al data center in cui è ospitato il tuo account Desk. Utilizzare desk.zoho.com per un account ospitato nell'UE fallirà; usa invece desk.zoho.eu. ^[3]

Cosa verificare

• Verifica che il contact_id che stai passando esista effettivamente in Zoho Desk aprendo il record del contatto nel portale agente prima di effettuare la chiamata API. ^[1]
• Conferma che il tuo token OAuth attivo contenga almeno Desk.tickets.READ e Desk.contacts.READ nel suo elenco di scope. ^[5]
• Controlla che l'orgId (ID organizzazione) sia correttamente configurato nel tuo client API, specialmente se questa è la prima chiamata dopo una nuova autorizzazione OAuth. ^{[7] [8]}