Come visualizzare le metriche di performance degli agenti in Zoho Desk

Le metriche di performance degli agenti in Zoho Desk sono accessibili tramite endpoint API dedicati che espongono dati di produttività, monitoraggio dello stato in tempo reale e assegnazioni di competenze per ogni agente della tua organizzazione di supporto.

Perché è importante

I responsabili del supporto hanno bisogno di un quadro chiaro e in tempo reale delle prestazioni del proprio team — dai tassi di risoluzione dei ticket alla disponibilità attuale. Che tu stia costruendo una dashboard personalizzata, conducendo una revisione periodica o integrando i dati di Zoho Desk in uno strumento BI più ampio, sapere quali endpoint chiamare e quali permessi configurare è essenziale. Questa guida (di Beam Help — supporto esperto indipendente per Zoho, non supporto ufficiale Zoho) ti accompagna attraverso l'intero processo.

---

Procedura passo dopo passo

Passaggio 1. Verifica che gli scope OAuth siano configurati.

Prima che qualsiasi chiamata alle metriche abbia successo, l'applicazione connessa deve essere autorizzata con gli scope OAuth corretti di Zoho Desk. Come minimo hai bisogno di Desk.basic.READ (copre agenti, reparti e organizzazioni) insieme a eventuali scope per ticket o impostazioni pertinenti al tuo caso d'uso. ^[5] Assicurati che questi scope siano presenti nella tua configurazione OAuth e che il token sia stato aggiornato dopo eventuali modifiche agli scope. ^[5]

Passaggio 2. Recupera le metriche di performance degli agenti.

Invia una richiesta GET all'endpoint /api/v1/doc/agentperformancemetrics, passando eventuali parametri di filtro o paginazione come dizionario di query parameter. ^[1] Questa operazione — identificata internamente come getagentperformancemetrics — restituisce dati orientati alla produttività per i tuoi agenti. ^[1] Una chiamata Python minimale si presenta così:

result = client.get_agent_performance_metrics(p={"department": "Support"})

Sostituisci il dizionario dei parametri con i filtri richiesti dalla tua finestra di reporting. ^[1]

Passaggio 3. Recupera i dati sullo stato in tempo reale degli agenti.

Per informazioni sulla disponibilità e il carico di lavoro in tempo reale, chiama GET /api/v1/doc/agentstatusmonitoring utilizzando l'operazione getagentstatusmonitoring. ^[2] Questo endpoint è progettato specificamente per il monitoraggio continuo dello stato — utile per wallboard o visualizzazioni live dei supervisori. ^[2] Passa lo stesso dizionario di parametri opzionale p per circoscrivere i risultati per reparto o team, se necessario. ^[2]

Passaggio 4. Recupera le mappature delle competenze degli agenti (opzionale ma consigliato).

Se la tua configurazione di Desk utilizza il routing basato sulle competenze, ti converrà anche interrogare GET /api/v1/doc/agentskillmapping tramite l'operazione getagentskillmapping. ^[4] Questo ti permette di incrociare i dati di performance con il set di competenze assegnato a ciascun agente, fornendo contesto ai tempi di risoluzione e ai volumi di ticket. ^[4]

Passaggio 5. Formatta e presenta i dati restituiti.

Una volta ricevuti i risultati, esponi i campi dati principali in un formato leggibile per gli stakeholder. Un pattern consigliato è visualizzare ogni campo su una riga separata (Nome, Stato, Proprietario/Agente, ecc.), omettendo i valori vuoti e gli ID interni. ^[3] Evita di inserire JSON grezzo direttamente nei report — analizza ed etichetta ogni campo in modo esplicito. ^[3]

Passaggio 6. Automatizza con un job pianificato (opzionale).

Per revisioni periodiche delle performance, racchiudi le chiamate dei Passaggi 2–4 in uno script pianificato. Archivia le risposte nel tuo data warehouse o livello BI, indicizzate per timestamp e ID agente, in modo da poter monitorare i trend nel tempo. Poiché gli endpoint accettano un dizionario di parametri, puoi variare l'intervallo di date o il filtro per reparto a ogni esecuzione senza modificare la logica principale. ^[1][2]

---

Errori comuni

• Scope Desk.basic.READ mancante. Questa è la causa più frequente di errori 401/403 quando si interrogano gli endpoint degli agenti. Anche se il tuo token dispone di ampie autorizzazioni per i ticket, i dati di agenti e reparti rientrano nella famiglia di scope basic. Controlla attentamente la tua lista di scope prima di eseguire il debug dell'endpoint stesso. ^[5]
• Token di accesso scaduti. I token OAuth di Zoho scadono (tipicamente dopo 3600 secondi). Se la tua integrazione non aggiorna automaticamente il token, le chiamate a tutti e tre gli endpoint falliranno silenziosamente o restituiranno errori di autenticazione. Implementa un flusso di aggiornamento che verifichi tokenexpiresat prima di ogni richiesta. ^[8]
• Dizionario di parametri vuoto vs. None. Tutti e tre gli endpoint accettano p come dizionario opzionale. Passare None è valido e restituisce risultati non filtrati, ma se intendi filtrare per reparto o intervallo di date, assicurati che il dizionario sia formato correttamente — un dizionario malformato verrà ignorato anziché generare un errore evidente. ^[1][2][4]
• Le modifiche agli scope richiedono la riemissione del token. Aggiungere Desk.basic.READ alla configurazione dopo l'autorizzazione iniziale non aggiorna automaticamente i token esistenti. Gli utenti o gli account di servizio devono ri-autenticarsi per ricevere un token che includa il nuovo scope. ^[5]

---

Cosa verificare

• Gli scope sono attivi sul token corrente — verifica che Desk.basic.READ (e qualsiasi altro scope richiesto) compaia nell'elenco degli scope concessi al token prima di effettuare la prima chiamata alle metriche. ^[5]
• Tutti e tre gli endpoint restituiscono dati — conferma che getagentperformancemetrics, getagentstatusmonitoring e getagentskill_mapping rispondano ciascuno con un payload non vuoto, poiché una risposta mancante da uno qualsiasi di essi indica solitamente un problema di permessi o parametri. ^[1][2][4]
• La logica di aggiornamento del token funziona correttamente — verifica che la tua integrazione legga correttamente tokenexpiresat e recuperi le credenziali prima della loro scadenza, in modo che i pull pianificati delle metriche non falliscano durante la notte. ^[8]