Come accedere alle icone disponibili in Zoho Desk

Zoho Desk espone un endpoint API dedicato che restituisce il catalogo completo delle icone disponibili all'interno della piattaforma — utile quando si creano widget personalizzati, estensioni o componenti UI con tema specifico.

Perché è importante

Quando sviluppi un'estensione per Zoho Desk o personalizzi l'interfaccia del portale, devi sapere quali identificatori di icone sono validi prima di referenziarli nel tuo codice. Interrogare l'endpoint delle icone disponibili in modo programmatico ti evita di dover indovinare i nomi delle icone e previene errori di rendering in produzione. Questo è particolarmente rilevante per i team che creano widget o automazioni per Desk che mostrano elementi visivi agli agenti.

Procedura passo dopo passo

Passaggio 1. Assicurati che la tua integrazione disponga di una connessione attiva e autenticata a Zoho Desk. La connessione richiede un token di accesso OAuth valido ottenuto utilizzando gli scope appropriati di Desk — è necessario almeno Desk.basic.READ per le query di metadati generali, e il token deve essere mantenuto aggiornato tramite un flusso di refresh token. ^[2][3]

Passaggio 2. Verifica che il tuo org_id (l'identificatore dell'organizzazione Zoho Desk) sia disponibile nel contesto della tua connessione. Se non è ancora stato memorizzato, il client API può individuarlo automaticamente chiamando l'endpoint delle organizzazioni e salvando il primo valore id restituito per le richieste successive. ^[3][5]

Passaggio 3. Invia una richiesta GET al seguente percorso dell'API Zoho Desk:

GET /api/v1/_doc/__available_icons

Questo endpoint è documentato internamente come l'operazione "Available Icons" (getavailableicons) e accetta un dizionario di parametri di query opzionale (p) per eventuali opzioni di filtraggio o paginazione che desideri passare. ^[7]

Passaggio 4. In Python, utilizzando il wrapper client ZohoDeskApi, la chiamata si presenta così:

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

Passa p={} (un dizionario vuoto) se non hai parametri di query aggiuntivi, oppure popolalo con le chiavi di filtro supportate. ^[7]

Passaggio 5. Analizza il payload della risposta. I dati restituiti conterranno gli identificatori delle icone che puoi referenziare quando crei componenti UI all'interno di Zoho Desk. Salva o memorizza nella cache questo elenco localmente se la tua estensione deve validare i nomi delle icone in fase di build anziché in fase di esecuzione.

---

Errori comuni

• Token di accesso mancante o scaduto. Se il token è scaduto, la richiesta verrà rifiutata. Assicurati che la logica di refresh del token della tua integrazione venga eseguita prima di chiamare l'endpoint — il flusso di refresh deve aggiornare i campi accesstoken e tokenexpires_at memorizzati nel record della tua connessione. ^[3]
• orgid mancante. Le chiamate all'API di Zoho Desk richiedono che l'ID organizzazione sia presente negli header della richiesta o nella configurazione del client. Se orgid è vuoto, il client potrebbe fallire silenziosamente o restituire un errore di autorizzazione. Verifica sempre che il valore sia popolato prima di effettuare qualsiasi chiamata all'API di Desk. ^[3][5]
• Passare None invece di un dizionario vuoto per p. La firma del metodo accetta p: dict = None, quindi se lo chiami senza argomenti il parametro assume il valore predefinito None. A seconda di come il client HTTP sottostante gestisce None, questo potrebbe omettere completamente i parametri di query — il che va bene per questo endpoint, ma sii consapevole di questa scelta. ^[7]

---

Cosa verificare

• Validità del token: Conferma che il tuo token di accesso OAuth sia aggiornato e che il meccanismo di refresh token sia configurato correttamente prima di effettuare la chiamata. ^[3]
• Presenza dell'Org ID: Verifica che deskorgid sia popolato nel record della tua connessione; se è vuoto, avvia prima il flusso di auto-discovery. ^[5]
• Copertura degli scope: Controlla che Desk.basic.READ (come minimo) sia incluso negli scope OAuth autorizzati, poiché gli endpoint di metadati in genere lo richiedono. ^[2]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non rappresenta il supporto ufficiale Zoho. Fai sempre riferimento alla documentazione più recente dell'API Zoho Desk per la tua area geografica del data center.*