Comment lister les conversations dans les tickets Zoho Desk

Lister toutes les conversations d'un ticket Zoho Desk est simple dès lors que vous connaissez le bon endpoint API et les scopes OAuth requis. Cet article vous guide à travers l'appel exact et ce qu'il convient de vérifier ensuite.

Pourquoi c'est important

Les workflows de support nécessitent souvent un accès programmatique au fil complet des réponses, notes et transferts associés à un ticket — à des fins de reporting, d'automatisation ou d'intégration avec d'autres outils. Savoir comment récupérer cette liste de conversations via l'API Zoho Desk vous permet de construire des pipelines fiables sans exporter manuellement les données depuis l'interface. En tant que support expert indépendant (et non support officiel Zoho), Beam Help documente ce modèle afin que votre équipe puisse l'implémenter en toute confiance.

Étape par étape

Étape 1. Vérifiez que votre token OAuth inclut les bons scopes Desk avant tout appel API. Vous avez au minimum besoin de Desk.tickets.READ dans votre liste de scopes ; les intégrations plus larges incluent généralement aussi Desk.tickets.ALL pour couvrir les opérations de lecture, écriture, création, mise à jour et suppression en une seule autorisation. ^[2]

Étape 2. Identifiez le ticket_id du ticket dont vous souhaitez récupérer les conversations. Il s'agit de l'identifiant numérique interne Zoho Desk pour l'enregistrement du ticket — et non du numéro de ticket affiché aux clients. Vous pouvez l'obtenir via une recherche de ticket préalable ou depuis l'URL de détail du ticket dans le portail agent Desk. ^[7]

Étape 3. Envoyez une requête GET vers l'endpoint des conversations, en substituant l'ID de votre ticket dans le chemin :

GET /api/v1/tickets/{ticket_id}/conversations

Inclure votre token bearer OAuth dans l'en-tête Authorization comme d'habitude. Le paramètre optionnel p peut être passé en tant que dictionnaire de chaîne de requête pour contrôler la pagination ou le filtrage de la liste de conversations retournée. ^[8]

Étape 4. Analysez la réponse. L'endpoint retourne la liste des entrées de conversation associées à ce ticket — les réponses, commentaires publics, notes privées et messages transférés sont tous accessibles via cet unique appel. Parcourez le tableau retourné pour accéder aux corps de messages individuels, horodatages, détails des auteurs et informations de canal. ^[8]

Étape 5. Si vous construisez une interface ou un assistant par-dessus ces données, associez chaque entrée de conversation à l'URL du portail agent du ticket afin que les agents puissent accéder directement à l'enregistrement. Le modèle de lien profond Desk suit le format https://desk.zoho.{dc}/agent/{portal}/tickets/details/{ticket_id}, où dc est votre suffixe de centre de données (par ex. com, eu, in) et portal est le nom de votre portail Desk. ^[7]

Erreurs courantes

• Scopes manquants ou insuffisants. Si votre client OAuth n'a reçu que Desk.search.READ ou des scopes au niveau des contacts, l'endpoint des conversations retournera une erreur d'autorisation. Vérifiez que Desk.tickets.READ (ou Desk.tickets.ALL) est bien présent dans la chaîne de scopes du token. ^[2]

• Mauvais format d'ID de ticket. Passer le numéro de ticket visible par le client au lieu du ticket_id interne entraînera une réponse 404 ou vide. Résolvez toujours l'ID interne en premier via une recherche ou un appel de consultation de ticket avant d'appeler l'endpoint des conversations. ^[8]

• Incompatibilité de centre de données. Zoho Desk est hébergé sur plusieurs centres de données régionaux. Assurez-vous que l'URL de base que vous utilisez (desk.zoho.com, desk.zoho.eu, etc.) correspond à la région où le compte Desk de votre organisation est provisionné ; les requêtes acheminées vers la mauvaise région échoueront à l'authentification. ^[7]

• Pagination non gérée. Pour les tickets avec de longs historiques de conversations, l'API retourne les résultats par pages. Utilisez le paramètre p pour parcourir les pages et éviter de tronquer silencieusement la liste des conversations. ^[8]

Ce qu'il faut vérifier

• Couverture des scopes : Vérifiez que votre token OAuth actif contient Desk.tickets.READ ou Desk.tickets.ALL en inspectant les scopes accordés dans votre console API Zoho. ^[2]
• Chemin d'endpoint correct : Confirmez que l'URL de la requête pointe vers /api/v1/tickets/{ticketid}/conversations avec un ticketid numérique valide substitué. ^[8]
• Pagination complète : Si la réponse inclut un indicateur nextPage ou un nombre total supérieur à la taille de page par défaut, assurez-vous que votre intégration parcourt toutes les pages avant de traiter les résultats. ^[8]