Comment accéder aux analyses de session dans Zoho Desk

Les analyses de session dans Zoho Desk peuvent être récupérées par programmation via un endpoint GET dédié qui retourne les données d'engagement et d'interaction pour vos sessions de support. Voici ce que vous devez savoir pour l'appeler correctement.

Pourquoi c'est important

Si vous créez des tableaux de bord, auditez les performances des agents ou intégrez des données Zoho Desk dans des outils de reporting externes, la récupération des analyses de session via l'API est l'approche la plus fiable. C'est particulièrement utile lorsque vous devez automatiser des exports de données périodiques ou afficher des métriques dans un portail personnalisé. En tant que support expert indépendant pour Zoho (et non le support officiel de Zoho), Beam Help vous guide à travers les étapes exactes ci-dessous.

Étape par étape

Étape 1. Assurez-vous que votre token OAuth inclut les scopes Zoho Desk corrects avant d'effectuer tout appel API. Vous aurez au minimum besoin de scopes tels que Desk.basic.READ et Desk.settings.READ autorisés pour votre intégration. Vérifiez votre configuration OAuth pour confirmer qu'ils sont présents aux côtés des scopes de tickets ou de contacts que votre application utilise déjà. ^[8]

Étape 2. Construisez une requête GET ciblant l'endpoint des analyses de session. Le chemin dont vous avez besoin est :

GET /api/v1/_doc/__session_analytics

Cet endpoint est dédié à la récupération des données d'analyses de session depuis Zoho Desk. ^[1]

Étape 3. Transmettez les paramètres de requête en utilisant le dictionnaire p (ou la chaîne de requête équivalente dans votre client HTTP). L'endpoint accepte un objet paramètre p, qui vous permet de filtrer ou de paginer les résultats d'analyse retournés. [^1, ^2]

Étape 4. En Python, l'appel suit ce modèle :

result = client.get_session_analytics(p={"your_filter_key": "value"})

Il existe également une deuxième opération enregistrée (getsessionanalytics2) pointant vers le même chemin — les deux opérations émettent un GET vers /api/v1/doc/_sessionanalytics et acceptent la même structure de paramètre p. ^[2]

Étape 5. Gérez l'objet de réponse retourné par la requête. La réponse de l'API contiendra votre charge utile d'analyses de session. Si votre intégration construit également des liens de navigation pour le portail Zoho Desk, les données de réponse peuvent être enrichies avec des URL directes vers le portail en faisant passer le résultat par votre logique de construction de liens, accompagné des identifiants deskorgid et desk_portal. [^3, ^4]

Étape 6. Si vous travaillez dans un contexte de chat ou d'assistant, le résultat des analyses de session peut être stocké avec un sessionid pour une récupération ultérieure. Le champ toolresult dans l'enveloppe de réponse est l'endroit où les données d'analyse brutes apparaissent lorsqu'elles sont appelées dans le cadre d'un flux d'orchestration plus large. [^4, ^6]

Erreurs courantes

• Scopes OAuth manquants. La liste des scopes OAuth de Zoho Desk est étendue. Si votre token a été généré sans Desk.basic.READ ou Desk.settings.READ, l'endpoint d'analyse peut retourner une erreur d'autorisation. Vérifiez votre configuration ZOHODESKSCOPES et régénérez le token si nécessaire. ^[8]

• Noms d'opérations en double. Deux opérations (getsessionanalytics et getsessionanalytics2) sont enregistrées contre le même chemin d'endpoint. Si vous générez automatiquement un client à partir d'une spécification, sachez que les deux résolvent vers GET /api/v1/doc/_sessionanalytics — appeler l'une ou l'autre produira le même résultat, mais les collisions de noms dans le code généré peuvent prêter à confusion. [^1, ^2]

• Paramètre p vide. Le paramètre p est par défaut à None, ce qui est valide — l'endpoint retournera des résultats non filtrés. Cependant, si vous attendez des données paginées ou limitées à une plage de dates, omettre les filtres peut retourner une charge utile plus importante que prévu. Transmettez des clés de filtre explicites dans p pour délimiter vos résultats. ^[1]

• Session navigateur vs. session API. Zoho Desk maintient également un concept de session basé sur le navigateur (suivi via zoho_tld et une session navigateur sauvegardée). Ceci est distinct des données de session de l'API d'analyse — ne confondez pas les deux lors du débogage. ^[7]

Ce qu'il faut vérifier

• Couverture des scopes : Vérifiez que votre token OAuth actif inclut au minimum Desk.basic.READ et Desk.settings.READ, et que le token n'a pas expiré. ^[8]
• Structure de la réponse de l'endpoint : Confirmez que le corps de la réponse contient les champs d'analyse que vous attendez ; si tool_result est null ou que la charge utile est vide, vérifiez si les paramètres de filtre p sont correctement formés. ^[4]
• Identifiants d'organisation : Assurez-vous que les valeurs deskorgid et desk_portal sont correctement définies dans la configuration de votre client, car elles sont nécessaires pour que les réponses liées au portail se résolvent correctement. ^[3]