Comment accéder aux icônes disponibles dans Zoho Desk

Zoho Desk expose un endpoint API dédié qui retourne le catalogue complet des icônes disponibles sur la plateforme — utile lors de la création de widgets personnalisés, d'extensions ou de composants d'interface thématiques.

Pourquoi c'est important

Lorsque vous développez une extension Zoho Desk ou personnalisez l'interface du portail, vous devez connaître les identifiants d'icônes valides avant de les référencer dans votre code. Interroger l'endpoint des icônes disponibles de manière programmatique vous évite de deviner les noms d'icônes et prévient les erreurs de rendu en production. Cela est particulièrement pertinent pour les équipes qui créent des widgets Desk ou des automatisations affichant des éléments visuels aux agents.

Étape par étape

Étape 1. Assurez-vous que votre intégration dispose d'une connexion active et authentifiée à Zoho Desk. La connexion nécessite un jeton d'accès OAuth valide obtenu en utilisant les scopes Desk appropriés — au minimum Desk.basic.READ est requis pour les requêtes de métadonnées générales, et votre jeton doit être maintenu à jour via un flux de jeton de rafraîchissement. ^[2][3]

Étape 2. Confirmez que votre org_id (l'identifiant d'organisation Zoho Desk) est disponible dans le contexte de votre connexion. S'il n'a pas encore été enregistré, le client API peut le découvrir automatiquement en appelant l'endpoint des organisations et en conservant la première valeur id retournée pour les requêtes ultérieures. ^[3][5]

Étape 3. Envoyez une requête GET vers le chemin d'API Zoho Desk suivant :

GET /api/v1/_doc/__available_icons

Cet endpoint est documenté en interne comme l'opération "Available Icons" (getavailableicons) et accepte un dictionnaire de paramètres de requête optionnel (p) pour les options de filtrage ou de pagination que vous souhaitez transmettre. ^[7]

Étape 4. En Python, en utilisant le wrapper client ZohoDeskApi, l'appel se présente comme suit :

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

Passez p={} (un dictionnaire vide) si vous n'avez pas de paramètres de requête supplémentaires, ou renseignez-le avec les clés de filtre prises en charge. ^[7]

Étape 5. Analysez la charge utile de la réponse. Les données retournées contiendront les identifiants d'icônes que vous pouvez référencer lors de la création de composants d'interface dans Zoho Desk. Stockez ou mettez en cache cette liste localement si votre extension doit valider les noms d'icônes au moment de la compilation plutôt qu'à l'exécution.

---

Erreurs courantes

• Jeton d'accès manquant ou expiré. Si le jeton a expiré, la requête sera rejetée. Assurez-vous que la logique de rafraîchissement du jeton de votre intégration s'exécute avant d'appeler l'endpoint — le flux de rafraîchissement doit mettre à jour les champs accesstoken et tokenexpires_at stockés dans votre enregistrement de connexion. ^[3]
• orgid manquant. Les appels à l'API Zoho Desk nécessitent que l'identifiant d'organisation soit présent dans les en-têtes de la requête ou dans la configuration du client. Si orgid est vide, le client peut échouer silencieusement ou retourner une erreur de permissions. Vérifiez toujours que la valeur est renseignée avant d'effectuer un appel à l'API Desk. ^[3][5]
• Passer None plutôt qu'un dictionnaire vide pour p. La signature de la méthode accepte p: dict = None, donc si vous l'appelez sans arguments, le paramètre prend la valeur par défaut None. Selon la façon dont le client HTTP sous-jacent gère None, cela peut omettre entièrement les paramètres de requête — ce qui convient pour cet endpoint, mais soyez délibéré à ce sujet. ^[7]

---

Points à vérifier

• Validité du jeton : Confirmez que votre jeton d'accès OAuth est à jour et que le mécanisme de rafraîchissement du jeton est correctement configuré avant d'effectuer l'appel. ^[3]
• Présence de l'ID d'organisation : Vérifiez que deskorgid est renseigné dans votre enregistrement de connexion ; s'il est vide, déclenchez d'abord le flux de découverte automatique. ^[5]
• Couverture des scopes : Vérifiez que Desk.basic.READ (au minimum) est inclus dans vos scopes OAuth autorisés, car les endpoints de métadonnées le requièrent généralement. ^[2]

---

*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Référencez-vous toujours à la dernière documentation de l'API Zoho Desk pour votre région de centre de données.*