Comment afficher les analyses d'épingles dans Zoho Desk

Les analyses d'épingles dans Zoho Desk peuvent être récupérées par programmation via un endpoint API dédié qui renvoie des données d'engagement pour les éléments épinglés. Ce guide vous explique comment appeler cet endpoint en utilisant le client API Zoho Desk.

Pourquoi c'est important

Si vous gérez une base de connaissances Zoho Desk ou un portail d'assistance, comprendre les performances du contenu épinglé vous aide à prioriser ce qui reste visible pour vos clients. Les équipes qui suivent l'engagement des articles ou la productivité des agents ont souvent besoin des analyses d'épingles dans le cadre de workflows de reporting plus larges. Cela est particulièrement utile lors de la création de tableaux de bord ou de l'automatisation des rapports en dehors de l'interface native Zoho Desk.

Étape par étape

Étape 1. Assurez-vous que votre connexion OAuth Zoho Desk est active et que votre jeton d'accès est valide. Le client API gère automatiquement le renouvellement des jetons, mais votre connexion initiale doit être établie et enregistrée. Si vous utilisez le moteur Zpilot, l'assistant getzohoapi récupérera et renouvellera les identifiants en votre nom. ^[7]

Étape 2. Vérifiez que vos scopes OAuth incluent les autorisations Zoho Desk nécessaires. Au minimum, votre environnement doit avoir Desk.tickets.READ, Desk.basic.READ et Desk.search.READ configurés — ceux-ci font partie du bloc standard ZOHODESKSCOPES. Sans les scopes corrects, l'API rejettera votre requête. ^[2]

Étape 3. Instanciez le client ZohoDeskApi avec un ZohoDeskClient valide. Vous aurez besoin de votre domaine API, d'un jeton d'accès actuel et de votre identifiant d'organisation (orgid). Si votre orgid n'est pas encore enregistré, le client peut le découvrir automatiquement en appelant getallorganizations et en lisant le premier résultat de la liste retournée. ^[7]

Étape 4. Appelez l'endpoint des analyses d'épingles en utilisant la méthode suivante sur votre instance ZohoDeskApi :

result = api.get_pin_analytics(p={})

Cela envoie une requête GET vers /api/v1/doc/pinanalytics. Le paramètre p accepte un dictionnaire optionnel de paramètres de requête — passez un dict vide si vous n'avez aucun filtre à appliquer. ^[1]

Étape 5. Analysez la réponse. La méthode retourne la réponse brute de l'API sous forme d'objet Python. Parcourez les données retournées pour extraire les métriques pertinentes pour vos besoins de reporting. Si vous utilisez l'interface de chat Zpilot, l'assistant formatera automatiquement les champs clés en texte brut. ^[5]

Étape 6. Si vous exécutez ceci dans la suite de tests du moteur Zpilot, vous pouvez tester l'endpoint via la classe DeskTestRunner. Initialisez le runner avec votre org_id et un niveau de risque "SAFE", appelez setup() pour établir la connexion, puis invoquez directement la méthode d'analyse. ^[8]

Erreurs courantes

• Identifiant d'organisation manquant : Si org_id est vide ou non persisté dans votre enregistrement de connexion, le client Desk peut échouer silencieusement ou retourner une erreur d'autorisation. Vérifiez toujours que l'identifiant d'organisation est renseigné avant d'effectuer des appels. ^[7]
• Jetons expirés : Le renouvelleur de jetons interroge la base de données pour obtenir le dernier refreshtoken et met à jour l'accesstoken stocké en cas de succès. Si le renouvellement échoue — par exemple en raison d'un secret client révoqué — le renouvelleur retourne None et les appels API suivants échoueront. ^[7]
• Scopes manquants : La configuration ZOHODESKSCOPES n'inclut pas de scope analytique dédié par nom. Si Zoho ajoute une application des scopes pour les analyses d'épingles dans une future version de l'API, vous devrez peut-être l'ajouter à votre configuration .env. ^[2]
• Conflits de port : Si vous exécutez le serveur Zpilot localement, il doit fonctionner sur le port 8080. L'utilisation de tout autre port brise l'URI de redirection OAuth et empêche entièrement l'acquisition des jetons. ^[6]

Ce qu'il faut vérifier

• Vérifiez que votre orgid est enregistré dans l'enregistrement de base de données zohoconnections avant d'appeler l'endpoint — un identifiant d'organisation manquant est la cause la plus fréquente des échecs silencieux. ^[7]
• Confirmez les scopes OAuth dans votre fichier .env incluent au minimum Desk.basic.READ et Desk.search.READ pour vous assurer que l'API Desk accepte vos requêtes. ^[2]
• Inspectez la réponse brute de getpinanalytics pour une clé data attendue ou une structure de liste avant de construire toute logique de reporting en aval. ^[1]

---

*Beam Help est un support expert indépendant pour Zoho — nous ne sommes pas le support officiel de Zoho, et ces conseils sont basés sur le comportement de l'API observé dans la documentation de l'API REST Zoho Desk et les implémentations client.*