Comment lister les commentaires d'un ticket dans Zoho Desk

Lister les commentaires d'un ticket dans Zoho Desk est simple via l'API REST : envoyez une requête GET vers l'endpoint des commentaires pour un ticket donné, et Zoho Desk retourne tous les commentaires associés à cet identifiant de ticket. Chez Beam Help — support expert indépendant pour Zoho, et non le support officiel de Zoho — nous vous expliquons exactement comment procéder.

Pourquoi c'est important

Lors de la création d'intégrations, d'automatisations ou de tableaux de bord de support, vous avez souvent besoin de récupérer par programmation le fil de conversation complet d'un ticket. L'endpoint des commentaires vous offre un accès structuré à chaque note interne et réponse publique d'un ticket, ce qui le rend indispensable pour les rapports, la synchronisation de données vers des systèmes externes, ou l'alimentation en contexte de workflows assistés par IA.

Étape par étape

Étape 1. Assurez-vous que votre token OAuth inclut les scopes Zoho Desk appropriés avant d'effectuer tout appel API. Vous avez au minimum besoin de Desk.tickets.READ dans votre liste de scopes, bien que des configurations plus larges incluent également Desk.tickets.ALL et Desk.tickets.WRITE pour une gestion complète des tickets.^[3]

Étape 2. Identifiez le ticket_id du ticket dont vous souhaitez récupérer les commentaires. Il s'agit de l'identifiant numérique unique que Zoho Desk attribue à chaque ticket — vous pouvez le trouver dans l'URL du ticket dans le portail agent Desk, qui suit le modèle https://desk.zoho.com/agent/{portal}/tickets/details/{TicketId}.^[7]

Étape 3. Effectuez une requête GET vers l'endpoint suivant, en remplaçant l'identifiant de ticket par le vôtre :

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

Cette opération est identifiée en interne sous le nom listticketcomments et accepte le ticket_id comme paramètre de chemin obligatoire. Vous pouvez également transmettre des paramètres de requête optionnels via le dictionnaire p (par exemple, des options de pagination ou de filtrage).^[4]

Étape 4. En Python, l'appel ressemble à ceci :

def list_ticket_comments(self, ticket_id: str, p: dict = None):
    """List ticket comments"""
    return self.c.request("GET", f"/api/v1/tickets/{ticket_id}/comments", p, None)

Passez votre identifiant de ticket sous forme de chaîne de caractères, et fournissez les éventuels paramètres de requête sous forme de dictionnaire dans l'argument p. Si vous n'avez pas de paramètres supplémentaires, passez None.^[4]

Étape 5. Analysez le corps de la réponse, qui contiendra la liste des commentaires pour ce ticket. Chaque objet commentaire inclura le contenu du commentaire, les détails de l'auteur et les horodatages — utilisez ces champs pour afficher ou traiter le fil de conversation selon vos besoins.^[4]

Étape 6. Si vous devez agir sur un commentaire spécifique après le listage — par exemple, modifier son contenu — notez qu'un endpoint PATCH distinct existe à /api/v1/tickets/{ticketid}/comments/{commentid}, qui accepte à la fois l'identifiant du ticket et celui du commentaire comme paramètres de chemin.^[5] De même, l'ajout d'un tout nouveau commentaire utilise un POST vers /api/v1/tickets/{ticket_id}/comments avec un payload de données.^[2]

Erreurs courantes

• Scopes manquants ou insuffisants. Si votre token OAuth a été généré sans Desk.tickets.READ (ou Desk.tickets.ALL), l'API retournera une erreur d'autorisation. Vérifiez votre configuration de scopes et régénérez le token si nécessaire.^[3]

• Format d'identifiant de ticket incorrect. Le ticket_id doit être transmis sous forme de chaîne de caractères dans le chemin. Passer un entier ou une valeur malformée entraînera l'échec de la requête ou des résultats inattendus.^[4]

• Confusion entre commentaires et réponses. Zoho Desk distingue les réponses publiques (visibles par le client) et les commentaires internes (visibles uniquement par les agents). L'endpoint /comments cible spécifiquement la ressource des commentaires — assurez-vous que c'est bien la donnée dont vous avez besoin plutôt que l'endpoint des réponses.^[2]

• Pagination non gérée. Si un ticket comporte un grand nombre de commentaires, l'API peut paginer les résultats. Vérifiez toujours si la réponse inclut des métadonnées de pagination et utilisez le paramètre p pour demander les pages suivantes.^[4]

Points à vérifier

• Vérification des scopes : Confirmez que Desk.tickets.READ ou Desk.tickets.ALL est présent dans la liste des scopes de votre token OAuth actif avant d'appeler l'endpoint.^[3]
• Endpoint et méthode corrects : Vérifiez que vous émettez bien un GET vers /api/v1/tickets/{ticket_id}/comments — et non un POST (qui ajoute un commentaire) ou un PATCH (qui en met un à jour).^[2][4][5]
• Complétude de la réponse : Après réception de la réponse, vérifiez si tous les commentaires attendus sont présents ou si des paramètres de pagination doivent être fournis pour récupérer l'ensemble complet.^[4]