Comment lister les équipes associées à un rôle dans Zoho Desk

Lister les équipes associées à un rôle spécifique dans Zoho Desk est simple via l'API REST Desk — une seule requête GET retourne toutes les équipes liées au rôle que vous spécifiez.

Pourquoi c'est important

Lors de la gestion des permissions des agents et des workflows dans Zoho Desk, les rôles et les équipes sont étroitement liés : un rôle définit ce qu'un agent peut faire, tandis que les équipes regroupent les agents pour le routage et la collaboration. Savoir quelles équipes sont associées à un rôle donné aide les administrateurs à auditer les accès, à résoudre les problèmes de routage des tickets et à maintenir une structure organisationnelle claire. Vous aurez besoin de cette consultation lors de l'intégration de nouveaux agents ou de la restructuration de votre hiérarchie de support.

Étape par étape

Étape 1. Vérifiez que votre token OAuth inclut les scopes Zoho Desk appropriés avant d'effectuer tout appel API. Vous aurez besoin au minimum de Desk.basic.READ dans votre ensemble de scopes autorisés, qui couvre les organisations, les agents et les départements — la catégorie dans laquelle se trouvent les rôles et les équipes. ^[3]

Étape 2. Identifiez le role_id du rôle que vous souhaitez inspecter. Vous pouvez le récupérer depuis votre panneau d'administration Zoho Desk sous Configuration → Rôles des agents, ou en appelant d'abord l'endpoint de liste des rôles. Gardez cet identifiant à portée de main — il fait partie du chemin de la requête.

Étape 3. Effectuez une requête GET vers l'endpoint suivant, en remplaçant votre identifiant de rôle réel :

GET /api/v1/roles/{role_id}/teams

Cette opération — désignée en interne par listassociatedteamsfora — retourne les équipes qui ont été associées au rôle spécifié. ^[2]

Étape 4. Si vous devez paginer un grand ensemble de résultats, passez le paramètre de requête optionnel p pour naviguer entre les pages de résultats. La signature de l'endpoint accepte à la fois role_id (paramètre de chemin) et p (paramètre de pagination optionnel). ^[2]

Étape 5. Un appel Python minimal utilisant le wrapper client Desk ressemble à ceci :

response = desk_client.list_associated_teams_for_a(
    role_id="your_role_id_here",
    p={"page": 1}   # optional pagination
)

Le client envoie une requête GET vers /api/v1/roles/{role_id}/teams et retourne le corps de la réponse analysé. ^[2]

Étape 6. Analysez le contenu de la réponse. L'objet retourné contiendra les enregistrements des équipes liées à ce rôle. Parcourez la liste pour extraire les noms des équipes, les identifiants ou tout autre attribut requis par votre workflow.

Erreurs courantes

• Scope manquant : Si votre token OAuth a été généré sans Desk.basic.READ, l'API rejettera la requête avec une erreur d'autorisation. Vérifiez vos scopes configurés et régénérez le token si nécessaire. ^[3]
• Mauvais contexte d'organisation : Zoho Desk gère plusieurs organisations. Si votre intégration gère plus d'une organisation, assurez-vous que le org_id de votre client API est défini sur la bonne organisation Desk avant d'appeler l'endpoint — sinon vous risquez d'interroger des rôles appartenant à un portail différent. ^[4]
• Oubli de pagination : Si un rôle est lié à de nombreuses équipes, la première page peut ne pas toutes les retourner. Vérifiez toujours si la réponse indique des pages supplémentaires et utilisez le paramètre p pour récupérer l'ensemble complet. ^[2]

Points à vérifier

• Couverture des scopes : Vérifiez que Desk.basic.READ (et tout autre scope requis) est présent dans votre token OAuth actif avant d'exécuter la requête. ^[3]
• role_id correct : Confirmez que l'identifiant de rôle que vous transmettez existe bien dans l'organisation Zoho Desk cible — un identifiant incorrect retournera une réponse vide ou une erreur. ^[2]
• Alignement de l'ID d'organisation : Après l'appel, validez que les équipes retournées appartiennent au portail/à l'organisation attendu(e), en particulier dans les configurations multi-organisations. ^[4]

---

*Beam Help fournit un support expert indépendant pour les produits Zoho et ne constitue pas le support officiel de Zoho. Pour les problèmes au niveau de la plateforme, consultez toujours directement la documentation de l'API Zoho Desk.*