Come accedere alle analisi di sessione in Zoho Desk

Le analisi di sessione in Zoho Desk possono essere recuperate in modo programmatico tramite un endpoint GET dedicato che restituisce dati di coinvolgimento e interazione per le tue sessioni di supporto. Ecco tutto ciò che devi sapere per chiamarlo correttamente.

Perché è importante

Se stai costruendo dashboard, verificando le prestazioni degli agenti o integrando i dati di Zoho Desk in strumenti di reportistica esterni, recuperare le analisi di sessione tramite API è l'approccio più affidabile. Questo è particolarmente utile quando hai bisogno di automatizzare esportazioni periodiche di dati o di visualizzare metriche all'interno di un portale personalizzato. In qualità di supporto esperto indipendente per Zoho (non supporto ufficiale Zoho), Beam Help ti guida attraverso i passaggi esatti qui di seguito.

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 scope come Desk.basic.READ e Desk.settings.READ autorizzati per la tua integrazione. Verifica la tua configurazione OAuth per confermare che siano presenti insieme a eventuali scope per ticket o contatti già utilizzati dalla tua applicazione. ^[8]

Passaggio 2. Costruisci una richiesta GET rivolta all'endpoint delle analisi di sessione. Il percorso necessario è:

GET /api/v1/_doc/__session_analytics

Questo endpoint è dedicato al recupero dei dati delle analisi di sessione da Zoho Desk. ^[1]

Passaggio 3. Passa eventuali parametri di query utilizzando il dizionario p (o la stringa di query equivalente nel tuo client HTTP). L'endpoint accetta un oggetto parametro p, che ti consente di filtrare o paginare i risultati delle analisi restituiti. [^1, ^2]

Passaggio 4. In Python, la chiamata segue questo schema:

result = client.get_session_analytics(p={"your_filter_key": "value"})

Esiste anche una seconda operazione registrata (getsessionanalytics2) che punta allo stesso percorso — entrambe le operazioni inviano una GET a /api/v1/doc/_sessionanalytics e accettano la stessa struttura del parametro p. ^[2]

Passaggio 5. Gestisci l'oggetto risposta restituito dalla richiesta. La risposta API conterrà il payload delle analisi di sessione. Se la tua integrazione costruisce anche link di navigazione per il portale Zoho Desk, i dati della risposta possono essere arricchiti con URL diretti al portale passando il risultato attraverso la tua logica di costruzione dei link insieme agli identificatori deskorgid e desk_portal. [^3, ^4]

Passaggio 6. Se stai lavorando in un contesto di chat o assistente, il risultato delle analisi di sessione può essere memorizzato insieme a un sessionid per un recupero successivo. Il campo toolresult nell'envelope della risposta è dove i dati grezzi delle analisi emergono quando viene chiamato come parte di un flusso di orchestrazione più ampio. [^4, ^6]

Errori comuni

• Scope OAuth mancanti. L'elenco degli scope OAuth di Zoho Desk è esteso. Se il tuo token è stato generato senza Desk.basic.READ o Desk.settings.READ, l'endpoint delle analisi potrebbe restituire un errore di autorizzazione. Verifica la tua configurazione ZOHODESKSCOPES e rigenera il token se necessario. ^[8]

• Nomi di operazioni duplicati. Due operazioni (getsessionanalytics e getsessionanalytics2) sono registrate contro lo stesso percorso endpoint. Se stai generando automaticamente un client da una specifica, tieni presente che entrambe si risolvono in GET /api/v1/doc/_sessionanalytics — chiamare l'una o l'altra produrrà lo stesso risultato, ma le collisioni di nomi nel codice generato possono causare confusione. [^1, ^2]

• Parametro p vuoto. Il parametro p ha come valore predefinito None, il che è valido — l'endpoint restituirà risultati non filtrati. Tuttavia, se ti aspetti dati paginati o con scope temporale, omettere i filtri potrebbe restituire un payload più grande del previsto. Passa chiavi di filtro esplicite all'interno di p per delimitare i tuoi risultati. ^[1]

• Sessione browser vs. sessione API. Zoho Desk mantiene anche un concetto di sessione basato su browser (tracciato tramite zoho_tld e una sessione browser salvata). Questo è separato dai dati della sessione API delle analisi — non confondere i due durante il debug. ^[7]

Cosa verificare

• Copertura degli scope: Verifica che il tuo token OAuth attivo includa almeno Desk.basic.READ e Desk.settings.READ, e che il token non sia scaduto. ^[8]
• Struttura della risposta dell'endpoint: Conferma che il corpo della risposta contenga i campi delle analisi che ti aspetti; se tool_result è null o il payload è vuoto, controlla se i parametri di filtro p sono formati correttamente. ^[4]
• Identificatori dell'organizzazione: Assicurati che i valori deskorgid e desk_portal siano impostati correttamente nella configurazione del tuo client, poiché sono necessari affinché le risposte collegate al portale si risolvano correttamente. ^[3]