Comment mapper les compétences des agents dans Zoho Desk

Le mappage des compétences des agents dans Zoho Desk vous permet d'associer des compétences spécifiques à des agents individuels afin que les tickets puissent être acheminés vers la personne la plus qualifiée. Cet article explique comment récupérer et utiliser les données de mappage des compétences des agents via l'API Zoho Desk.

Pourquoi c'est important

Lorsque votre service d'assistance dépasse une poignée d'agents, l'acheminement des tickets par compétence devient essentiel pour une résolution au premier contact. Comprendre la structure des mappages de compétences — et comment les interroger — vous permet de créer des automatisations, d'auditer les affectations et de maintenir vos règles d'acheminement à jour. Cela est particulièrement pertinent si vous intégrez Zoho Desk avec des outils externes de gestion des effectifs ou de reporting. Comme toujours, Beam Help est un support expert indépendant pour Zoho et ne constitue pas le support officiel de Zoho.

Étape par étape

Étape 1. Vérifiez que votre jeton OAuth inclut les scopes Zoho Desk appropriés avant d'effectuer tout appel API. Vous aurez au minimum besoin de Desk.basic.READ et Desk.settings.READ dans votre liste de scopes autorisés, car les données des agents et de l'organisation relèvent de ces catégories de permissions. ^[5]

Étape 2. Pour récupérer le document de mappage des compétences des agents, envoyez une requête GET à l'endpoint /api/v1/doc/agentskill_mapping. Cet endpoint retourne la structure complète du mappage des compétences pour votre organisation Desk. Passez les paramètres de requête optionnels sous forme de dictionnaire dans l'argument p si vous avez besoin de filtrer ou de paginer les résultats. ^[1]

Étape 3. Si votre couche d'intégration est basée sur Python, l'appel se présente ainsi en pratique :

result = client.get_agent_skill_mapping(p={"param_key": "param_value"})

La méthode envoie un GET vers /api/v1/doc/agentskillmapping et retourne la réponse analysée. Utilisez le même endpoint que vous l'appeliez via getagentskillmapping ou l'alias d'opération alternatif getagentskillmapping2 — les deux résolvent vers le même chemin. ^[1][2]

Étape 4. Une fois que vous disposez des données de mappage des compétences, croisez les agents individuels en interrogeant les agents filtrés par leur profil assigné. Envoyez une requête GET à /api/v1/profiles/{profile_id}/agents, en substituant l'identifiant de profil approprié, pour lister tous les agents associés à ce profil. ^[6]

Étape 5. De même, si vos regroupements de compétences correspondent à des définitions de rôles, vous pouvez récupérer les agents par rôle en utilisant GET /api/v1/roles/{role_id}/agents. Fournissez l'identifiant de rôle dans le chemin pour obtenir la liste des agents correspondants. ^[7]

Étape 6. Lors de la création d'une interface utilisateur ou d'une couche de reporting basée sur ces résultats, construisez vos liens vers les enregistrements Zoho Desk en utilisant le modèle https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}, où dc est le suffixe de votre centre de données (par ex. com, eu) et portal est le nom de votre portail Desk. Cela vous permet d'afficher des liens cliquables en profondeur aux côtés des données de mappage des compétences. ^[4]

Erreurs courantes

• Les scopes manquants provoquent des échecs silencieux. Si Desk.basic.READ ou Desk.settings.READ est absent de votre autorisation OAuth, l'endpoint de mappage des compétences retournera une erreur d'autorisation plutôt que des données. Vérifiez votre chaîne de scopes dans la configuration de l'environnement avant de déboguer l'appel API lui-même. ^[5]
• Noms d'opérations en double. L'endpoint de mappage des compétences est enregistré sous deux identifiants d'opération (getagentskillmapping et getagentskillmapping_2). Les deux pointent vers le même chemin, donc appeler l'un ou l'autre est fonctionnellement équivalent — mais si vous générez automatiquement du code client à partir d'une spécification OpenAPI, sachez que vous pourrez voir les deux et devrez les dédupliquer. ^[1][2]
• Confusion entre ID de profil et ID de rôle. Les agents peuvent être interrogés par profil (/api/v1/profiles/{profileid}/agents) ou par rôle (/api/v1/roles/{roleid}/agents). Ces identifiants sont distincts et ne sont pas interchangeables — utiliser un ID de rôle dans l'endpoint des profils retournera une erreur ou un résultat vide. ^[6][7]

Ce qu'il faut vérifier

• Vérifiez que votre jeton OAuth actif contient à la fois Desk.basic.READ et Desk.settings.READ avant d'exécuter toute requête de mappage des compétences. ^[5]
• Confirmez que la réponse de /api/v1/doc/agentskill_mapping contient les champs d'agent et de compétence attendus, et que le nombre d'enregistrements correspond à ce que vous voyez dans le panneau d'administration de Zoho Desk. ^[1]
• Après le croisement avec les endpoints de profil ou de rôle, assurez-vous que chaque ID d'agent retourné apparaît de manière cohérente dans les trois réponses afin d'écarter tout mappage obsolète ou mal configuré. ^[6][7]