Comment afficher les métriques de performance des agents dans Zoho Desk

Les métriques de performance des agents dans Zoho Desk sont accessibles via des endpoints API dédiés qui exposent les données de productivité, la surveillance du statut en temps réel et les affectations de compétences pour chaque agent de votre organisation de support.

Pourquoi c'est important

Les responsables du support ont besoin d'une vision claire et en temps réel des performances de leur équipe — des taux de résolution des tickets à la disponibilité actuelle. Que vous construisiez un tableau de bord personnalisé, réalisiez une revue périodique ou intégriez les données Zoho Desk dans un outil BI plus large, savoir quels endpoints appeler et quelles permissions configurer est essentiel. Ce guide (proposé par Beam Help — support expert indépendant pour Zoho, et non le support officiel de Zoho) vous accompagne tout au long du processus.

---

Étape par étape

Étape 1. Vérifiez que vos scopes OAuth sont en place.

Avant qu'un appel de métriques puisse aboutir, votre application connectée doit être autorisée avec les scopes OAuth Zoho Desk appropriés. Vous avez au minimum besoin de Desk.basic.READ (couvre les agents, les départements et les organisations), ainsi que des scopes de tickets ou de paramètres pertinents pour votre cas d'usage. ^[5] Assurez-vous que ces scopes sont présents dans votre configuration OAuth et que le token a été actualisé après tout changement de scope. ^[5]

Étape 2. Récupérez les métriques de performance des agents.

Envoyez une requête GET vers l'endpoint /api/v1/doc/agentperformancemetrics, en passant les paramètres de filtre ou de pagination sous forme de dictionnaire de paramètres de requête. ^[1] Cette opération — identifiée en interne sous le nom getagentperformancemetrics — retourne des données axées sur la productivité de vos agents. ^[1] Un appel Python minimal ressemble à ceci :

result = client.get_agent_performance_metrics(p={"department": "Support"})

Remplacez le dictionnaire de paramètres par les filtres correspondant à votre fenêtre de reporting. ^[1]

Étape 3. Récupérez les données de statut des agents en temps réel.

Pour obtenir des informations de disponibilité et de charge de travail en temps réel, appelez GET /api/v1/doc/agentstatusmonitoring via l'opération getagentstatusmonitoring. ^[2] Cet endpoint est conçu spécifiquement pour la surveillance continue du statut — utile pour les tableaux d'affichage ou les vues superviseur en direct. ^[2] Passez le même dictionnaire de paramètres optionnel p pour restreindre les résultats par département ou équipe si nécessaire. ^[2]

Étape 4. Récupérez les mappings de compétences des agents (optionnel mais recommandé).

Si votre configuration Desk utilise le routage basé sur les compétences, vous souhaiterez également interroger GET /api/v1/doc/agentskillmapping via l'opération getagentskillmapping. ^[4] Cela vous permet de croiser les données de performance avec l'ensemble des compétences assignées à chaque agent, apportant ainsi du contexte aux temps de résolution et aux volumes de tickets. ^[4]

Étape 5. Formatez et présentez les données retournées.

Une fois les résultats reçus, mettez en avant les champs de données clés dans un format lisible pour les parties prenantes. Un modèle recommandé consiste à afficher chaque champ sur sa propre ligne (Nom, Statut, Propriétaire/Agent, etc.), en ignorant les valeurs vides et les identifiants internes. ^[3] Évitez d'insérer du JSON brut directement dans les rapports — analysez et étiquetez chaque champ explicitement. ^[3]

Étape 6. Automatisez avec une tâche planifiée (optionnel).

Pour les revues de performance récurrentes, encapsulez les appels des étapes 2 à 4 dans un script planifié. Stockez les réponses dans votre entrepôt de données ou votre couche BI, indexées par horodatage et identifiant d'agent, afin de suivre les tendances dans le temps. Les endpoints acceptant un dictionnaire de paramètres, vous pouvez faire varier la plage de dates ou le filtre de département à chaque exécution sans modifier la logique principale. ^[1][2]

---

Erreurs courantes

• Scope Desk.basic.READ manquant. C'est la cause la plus fréquente des erreurs 401/403 lors de l'interrogation des endpoints agents. Même si votre token dispose de permissions étendues sur les tickets, les données des agents et des départements relèvent de la famille de scopes basic. Vérifiez votre liste de scopes avant de déboguer l'endpoint lui-même. ^[5]
• Tokens d'accès périmés. Les tokens OAuth Zoho expirent (généralement après 3 600 secondes). Si votre intégration n'actualise pas automatiquement le token, les appels vers les trois endpoints échoueront silencieusement ou retourneront des erreurs d'authentification. Implémentez un flux d'actualisation qui vérifie tokenexpiresat avant chaque requête. ^[8]
• Dictionnaire de paramètres vide vs. None. Les trois endpoints acceptent p comme dictionnaire optionnel. Passer None est valide et retourne des résultats non filtrés, mais si vous souhaitez filtrer par département ou plage de dates, assurez-vous que le dictionnaire est correctement formé — un dictionnaire mal formé sera ignoré plutôt que de générer une erreur explicite. ^[1][2][4]
• Les changements de scope nécessitent une réémission du token. Ajouter Desk.basic.READ à votre configuration après l'autorisation initiale ne met pas automatiquement à jour les tokens existants. Les utilisateurs ou comptes de service doivent se ré-authentifier pour recevoir un token incluant le nouveau scope. ^[5]

---

Ce qu'il faut vérifier

• Les scopes sont actifs sur le token actuel — vérifiez que Desk.basic.READ (et tout autre scope requis) apparaît dans la liste des scopes accordés au token avant d'effectuer votre premier appel de métriques. ^[5]
• Les trois endpoints retournent des données — confirmez que getagentperformancemetrics, getagentstatusmonitoring et getagentskill_mapping répondent chacun avec un payload non vide, car une réponse manquante de l'un d'eux indique généralement un problème de permission ou de paramètre. ^[1][2][4]
• La logique d'actualisation du token fonctionne — vérifiez que votre intégration lit correctement tokenexpiresat et récupère les identifiants avant leur expiration, afin que les collectes de métriques planifiées n'échouent pas pendant la nuit. ^[8]