Comment récupérer les profils d'agents légers dans Zoho Desk

La récupération du profil d'agent léger dans Zoho Desk nécessite une seule requête GET authentifiée vers un endpoint de profils dédié, renvoyant la configuration de profil associée aux agents légers de votre organisation.

Pourquoi c'est important

Les agents légers dans Zoho Desk disposent d'un profil de permissions restreint par rapport aux agents complets — ils peuvent consulter les tickets mais ont des droits d'action limités. Récupérer ce profil par programmation vous permet d'auditer les permissions, de comparer des profils ou de créer des automatisations qui orientent conditionnellement le travail en fonction du type d'agent. Si vous intégrez Zoho Desk dans un tableau de bord personnalisé ou des outils internes, connaître la structure exacte du profil est indispensable avant d'assigner ou de filtrer des agents.

Étape par étape

Étape 1. Assurez-vous que votre connexion OAuth Zoho Desk est initialisée avec l'identifiant d'organisation correct. Le client nécessite un orgid pour acheminer les requêtes vers le bon portail Desk. Si le deskorg_id n'est pas encore enregistré, le système peut le découvrir automatiquement en appelant d'abord l'endpoint des organisations et en persistant la première valeur id retournée dans l'enregistrement utilisateur. ^[2][5]

Étape 2. Vérifiez que votre token OAuth inclut le scope Desk.basic.READ (au minimum). Les données de profil et d'agent relèvent du groupe de permissions de lecture de base ; les tokens ne disposant pas de ce scope seront rejetés avant que la requête n'atteigne la ressource des profils. ^[8]

Étape 3. Assurez-vous que votre token d'accès est valide et non expiré. Le mécanisme de rafraîchissement du token vérifie le refreshtoken stocké, appelle l'endpoint de token OAuth Zoho et réécrit le nouveau accesstoken ainsi que tokenexpiresat dans l'enregistrement de connexion avant que l'appel API ne soit effectué. ^[2][7]

Étape 4. Émettez la requête HTTP suivante à l'aide de votre client Zoho Desk authentifié :

GET /api/v1/profiles/light

Passez les paramètres de requête optionnels sous forme de dictionnaire via l'argument p (par exemple, la pagination ou les filtres de champs si pris en charge). L'endpoint est identifié par le nom d'opération getlightagent_profile. ^[1]

En Python, en utilisant le wrapper ZohoDeskApi, l'appel se présente comme suit :

result = api.get_light_agent_profile(p={})

L'argument p={} transmet un dictionnaire de paramètres vide ; remplacez-le par les paramètres de requête requis par votre cas d'usage. ^[1]

Étape 5. Analysez la réponse. L'objet retourné contiendra la définition du profil d'agent léger. Affichez ou traitez les champs clés — tels que le nom du profil, les permissions et l'identifiant — selon les besoins de votre intégration. Si vous construisez un assistant conversationnel par-dessus, présentez les données dans un format lisible par un humain plutôt qu'en JSON brut. ^[3]

Étape 6. Si vous avez également besoin de voir quels agents sont actuellement assignés au profil d'agent léger, utilisez l'endpoint complémentaire :

GET /api/v1/profiles/{profile_id}/agents

Remplacez {profileid} par la valeur id retournée lors de l'appel précédent. Cette opération est gérée par l'opération listagentsbyprofile et accepte le même dictionnaire de paramètres optionnel p. ^[4]

---

Erreurs courantes

• orgid manquant : Les requêtes échoueront ou retourneront des résultats inattendus si le client Desk est initialisé sans identifiant d'organisation valide. Vérifiez toujours que deskorg_id est renseigné avant d'effectuer des appels de profil ; le flux de découverte automatique gère cela lors de la première connexion, mais une valeur obsolète ou vide dans la base de données cassera les requêtes ultérieures. ^[2][5]
• Scopes OAuth insuffisants : Si Desk.basic.READ est absent des scopes accordés, l'endpoint des profils retournera une erreur d'autorisation. Vérifiez la liste complète des scopes dans votre configuration et ré-autorisez si nécessaire. ^[8]
• Tokens expirés ne se rafraîchissant pas : Si la fonction tokenrefresher ne peut pas localiser un refreshtoken valide dans la base de données, elle retourne None et l'appel API échouera avec une erreur d'authentification plutôt qu'une réponse de profil. Assurez-vous que l'enregistrement de connexion est intact. ^[2][7]

---

Ce qu'il faut vérifier

• Confirmez que la réponse contient un champ id de profil non vide — vous aurez besoin de cette valeur pour appeler listagentsby_profile à l'étape suivante. ^[1][4]
• Vérifiez que le scope Desk.basic.READ apparaît dans les permissions accordées du token actif avant de passer en production. ^[8]
• Vérifiez que deskorgid est correctement enregistré dans l'enregistrement de connexion afin que tous les appels API Desk ultérieurs soient acheminés vers le bon portail. ^[2][5]

---

*Beam Help fournit une assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Référez-vous toujours à la documentation officielle de Zoho pour les dernières modifications de l'API.*