Come ottenere i dettagli del tuo profilo in Zoho Desk

Recuperare i dettagli del tuo profilo in Zoho Desk è semplice grazie all'endpoint dedicato ai profili, che restituisce le informazioni relative all'agente attualmente autenticato. Ecco tutto ciò che devi sapere per chiamarlo correttamente e interpretare la risposta.

Perché è importante

Quando si costruiscono integrazioni o automazioni su Zoho Desk, spesso è necessario identificare l'agente attualmente connesso — ad esempio, per precompilare i campi di assegnazione, verificare le azioni o personalizzare una dashboard di supporto. Sapere quale endpoint API chiamare e quali scope OAuth abilitare consente di risparmiare molto tempo in fase di debug. In qualità di supporto esperto indipendente per Zoho (non supporto ufficiale Zoho), Beam Help ti guida attraverso i passaggi esatti descritti di seguito.

---

Passo dopo passo

Passaggio 1. Assicurati che la tua connessione OAuth abbia gli scope corretti configurati prima di effettuare qualsiasi chiamata API. Come minimo, la tua integrazione con Zoho Desk richiede Desk.basic.READ per leggere i dati relativi agli agenti e all'organizzazione. ^[4]

Passaggio 2. Autentica il tuo client API utilizzando un access token valido. Se il token è scaduto, il client deve utilizzare un refresh token per ottenere un nuovo access token prima di procedere. Il flusso di aggiornamento scambia il refresh token memorizzato con un nuovo access_token e aggiorna di conseguenza il timestamp di scadenza. ^[2]

Passaggio 3. Assicurati che il tuo client API di Desk abbia un org_id valido impostato. Zoho Desk circoscrive tutte le chiamate API a un'organizzazione specifica. Se l'ID organizzazione non è ancora memorizzato, il client può scoprirlo automaticamente chiamando prima l'endpoint dell'elenco delle organizzazioni e salvando l'id della prima organizzazione restituita per le richieste future. [^2, ^6]

Passaggio 4. Chiama l'endpoint dei dettagli del profilo:

GET /api/v1/profiles/mine

Questa operazione, identificata come getmyprofile_details, accetta un dizionario di parametri di query opzionale (p) e restituisce il record del profilo per l'agente attualmente autenticato. ^[7]

Passaggio 5. Analizza la risposta e visualizza i campi principali. Un formato di output chiaro per i dati del profilo presenterebbe campi come nome, email e stato su righe separate, omettendo eventuali valori vuoti o ID interni. ^[5]

Passaggio 6. Se hai bisogno di incrociare i dettagli dell'account Zoho dell'utente autenticato (come il suo ZUID, indirizzo email o nome dell'organizzazione), puoi integrare la chiamata al profilo di Desk con una richiesta all'endpoint user-info di Zoho Accounts:

GET https://accounts.zoho.<DC>/oauth/user/info

Passa l'intestazione Authorization: Bearer <accesstoken>. La risposta può includere campi come ZUID, Email, orgid, organizationid, ZGID, companyname e organization_name — tieni presente che i nomi esatti dei campi possono variare a seconda della regione del data center. ^[3]

---

Errori comuni

• Org ID mancante: Se deskorgid è vuoto quando il client API viene inizializzato, le chiamate a /api/v1/profiles/mine potrebbero fallire o restituire risultati inattesi. Verifica sempre che l'org ID sia risolto prima di effettuare richieste al profilo. [^2, ^6]
• Scope insufficienti: Omettere Desk.basic.READ dall'elenco degli scope OAuth impedirà all'endpoint dei profili di restituire dati. Verifica che questo scope sia incluso insieme a eventuali scope per ticket o contatti che hai configurato. ^[4]
• Mancata corrispondenza del data center: Il valore ZOHO_DC utilizzato nella configurazione OAuth deve corrispondere al data center in cui è ospitato il tuo account Zoho (ad es. com, eu, in, com.au). Una mancata corrispondenza causa il fallimento silenzioso delle chiamate di aggiornamento del token e di user-info. ^[3]
• Varianza nei nomi dei campi: Quando si leggono le informazioni utente dall'endpoint di Zoho Accounts, non dare per scontato un unico nome di campo per l'org ID o il nome dell'organizzazione — lo schema della risposta differisce tra i data center, quindi il codice dovrebbe verificare più chiavi possibili prima di ricorrere a un valore predefinito. ^[3]

---

Cosa verificare

• Elenco degli scope: Conferma che Desk.basic.READ (e idealmente Desk.basic.CREATE) compaiano negli scope OAuth configurati prima di avviare il flusso di autenticazione. ^[4]
• Risoluzione dell'org ID: Dopo l'autenticazione, verifica che un deskorgid non vuoto sia memorizzato nel record della connessione; se manca, avvia il flusso di auto-discovery sull'endpoint dell'elenco delle organizzazioni. [^2, ^6]
• Validità del token: Prima di chiamare /api/v1/profiles/mine, verifica che l'accesstoken memorizzato non abbia superato il timestamp tokenexpires_at e, se necessario, aggiornalo in modo proattivo. ^[2]