Come accedere alle analisi dei canali in Zoho Desk

Le analisi dei canali in Zoho Desk possono essere recuperate in modo programmatico tramite un endpoint API dedicato che restituisce dati sulle performance dei tuoi canali di supporto.

Perché è importante

Se hai bisogno di misurare le performance dei diversi canali di supporto (email, chat, social, ecc.), estrarre i dati delle analisi dei canali ti consente di creare dashboard personalizzate, pianificare report o inviare metriche a strumenti BI di terze parti. Questo è particolarmente utile per i responsabili del supporto che necessitano di visibilità oltre ciò che l'interfaccia standard di Zoho Desk offre, o per i team che integrano i dati di Desk in flussi di reporting operativo più ampi.

Procedura passo dopo passo

Passaggio 1. Assicurati che il tuo token OAuth includa gli scope corretti di Zoho Desk prima di effettuare qualsiasi chiamata API. Come minimo avrai bisogno di accesso in lettura — scope come Desk.basic.READ e Desk.settings.READ sono richiesti per gli endpoint relativi alle analisi, e la configurazione del tuo token dovrebbe includerli insieme a eventuali scope per ticket o contatti già utilizzati dalla tua integrazione. ^[3]

Passaggio 2. Autentica il tuo client API utilizzando il flusso OAuth 2.0 per Zoho Desk. Una volta ottenuto un access token valido, sei pronto per chiamare l'endpoint delle analisi dei canali. Assicurati che il token non sia scaduto e che il data centre corretto (.com, .eu, .in, ecc.) sia riflesso nel tuo URL base. ^[3]

Passaggio 3. Invia una richiesta GET all'endpoint delle analisi dei canali:

GET /api/v1/_doc/__channel_analytics

Questa operazione è identificata internamente come getchannelanalytics e accetta un dizionario di parametri di query opzionale (p) che puoi utilizzare per filtrare o paginare i risultati. ^[1]

Passaggio 4. In Python, la chiamata si presenta così:

def get_channel_analytics(self, p: dict = None):
    return self.c.request("GET", "/api/v1/_doc/__channel_analytics", p, None)

Passa eventuali parametri di filtro come coppie chiave-valore all'interno del dizionario p. Se desideri risultati non filtrati, chiama semplicemente il metodo senza argomenti. ^[1]

Passaggio 5. Analizza la risposta JSON restituita dall'endpoint. L'oggetto risultato può essere passato direttamente a qualsiasi logica di costruzione di link o di reporting a valle. Se stai utilizzando il livello assistente di Beam Help, il risultato dello strumento viene automaticamente mappato ai link contestuali di Zoho Desk, così puoi navigare direttamente alla sezione pertinente del tuo portale. ^{[2] [5]}

Passaggio 6. Se hai bisogno di un link diretto al browser per il tuo portale Desk insieme ai dati API, costruisci l'URL base utilizzando il pattern:

https://desk.zoho.{dc}/agent/{portal}

dove {dc} è il suffisso del tuo data centre e {portal} è il nome del tuo portale Desk. Per il data centre predefinito .com questo diventa https://desk.zoho.com/agent/{portal}. ^[7]

Errori comuni

• Scope OAuth mancanti. La causa più frequente di errori 401 o 403 è un access token generato senza gli scope necessari Desk.basic.READ o Desk.settings.READ. Verifica sempre l'elenco degli scope nella configurazione OAuth prima di eseguire il debug dell'endpoint. ^[3]
• Data centre errato. Zoho Desk è specifico per regione. Se la tua organizzazione è ospitata sul data centre EU o IN, il tuo URL base deve riflettere ciò (ad es. desk.zoho.eu). Utilizzare l'endpoint .com per un'organizzazione non statunitense restituirà errori di autenticazione. ^[7]
• Parametro p vuoto vs. None. Il parametro p è opzionale, ma passare un dizionario vuoto {} rispetto a None può comportarsi diversamente a seconda di come il tuo client HTTP serializza le query string. Se ricevi risultati vuoti inaspettati, prova a passare None esplicitamente. ^[1]

Cosa verificare

• Conferma che il tuo token OAuth contenga Desk.basic.READ e qualsiasi altro scope Desk richiesto, e che non sia scaduto prima di effettuare la richiesta. ^[3]
• Verifica che il suffisso del data centre nel tuo URL base corrisponda alla regione in cui è stata eseguita la provisioning della tua organizzazione Zoho Desk. ^[7]
• Valida che il corpo della risposta sia non vuoto e JSON ben formato; se i parametri di filtro p sono troppo restrittivi, l'endpoint potrebbe restituire un insieme di risultati valido ma vuoto. ^[1]

---

*Beam Help fornisce supporto esperto indipendente per i prodotti Zoho e non è il supporto ufficiale Zoho. Fai sempre riferimento alla documentazione API più recente di Zoho Desk per eventuali modifiche al comportamento degli endpoint o ai requisiti degli scope.*