Comment lister les commentaires d'une tâche dans Zoho Desk

Lister tous les commentaires d'une tâche Zoho Desk est simple dès lors que vous connaissez le bon endpoint API et les scopes OAuth requis. Cet article vous guide pas à pas — proposé par Beam Help, support expert indépendant pour Zoho (et non le support officiel Zoho).

Pourquoi c'est important

Les commentaires de tâches dans Zoho Desk capturent le contexte, les décisions et les mises à jour importants liés à une tâche spécifique. Si vous construisez une intégration, réalisez un audit, ou avez simplement besoin d'accéder à l'historique des commentaires par programmation, vous devrez appeler l'endpoint de listage des commentaires de tâche. Comprendre les paramètres requis et les scopes en amont vous évitera des erreurs d'authentification frustrantes par la suite.

Étape par étape

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

Avant d'effectuer tout appel API, vérifiez que votre application connectée ou votre client OAuth dispose du scope Desk.tasks.READ (au minimum). Un scope plus large Desk.tasks.ALL couvre également cette opération. Sans l'un de ces scopes, la requête sera rejetée au niveau de la couche d'authentification. ^[4]

Étape 2. Identifiez le taskId que vous souhaitez interroger.

Chaque tâche dans Zoho Desk possède un identifiant numérique unique. Vous pouvez le récupérer depuis un appel API précédent qui liste ou crée des tâches, ou en inspectant l'URL de la tâche dans l'interface web de Zoho Desk. Gardez cette valeur à portée de main — il s'agit d'un paramètre de chemin obligatoire pour l'étape suivante. ^[2]

Étape 3. Envoyez une requête GET vers l'endpoint de listage des commentaires de tâche.

Émettez une requête HTTP GET vers le chemin suivant, en remplaçant l'identifiant de tâche par le vôtre :

GET /api/v1/tasks/{taskId}/comments

Le taskId est un paramètre de chemin obligatoire. Un paramètre de requête optionnel p peut être transmis pour contrôler la pagination ou le filtrage des résultats. ^[2]

Voici un exemple minimal en Python utilisant le wrapper client Zoho Desk :

# taskId is a string, e.g. "123456789"
comments = desk_client.list_task_comments(taskId="123456789")

Vous pouvez également passer un dictionnaire comme second argument (p) pour fournir tout paramètre de requête supplémentaire pris en charge par l'endpoint. ^[2]

Étape 4. Analysez la réponse.

Une réponse réussie retournera la liste des commentaires associés à la tâche spécifiée. Chaque objet commentaire dans la réponse peut ensuite être récupéré individuellement dans son intégralité via l'endpoint GET /api/v1/tasks/{taskId}/comments/{commentId} si vous avez besoin de l'enregistrement complet du commentaire. ^[8]

Étape 5. (Optionnel) Créez ou mettez à jour des commentaires si nécessaire.

Si votre flux de travail nécessite d'ajouter de nouveaux commentaires après avoir consulté la liste, utilisez une requête POST vers /api/v1/tasks/{taskId}/comments avec un payload data. ^[5] Pour modifier un commentaire existant, émettez une requête PATCH vers /api/v1/tasks/{taskId}/comments/{commentId} avec le contenu mis à jour dans le corps de la requête. ^[7]

Erreurs courantes

• Scope manquant ou incorrect. L'échec le plus fréquent est un token OAuth qui ne dispose pas de Desk.tasks.READ ou Desk.tasks.ALL. Vérifiez votre configuration de scope et régénérez votre token si vous avez récemment ajouté des scopes — les tokens existants n'héritent pas automatiquement des nouvelles permissions. ^[4]

• Format de taskId incorrect. Le taskId doit être transmis sous forme de chaîne de caractères dans le chemin. Passer un type entier directement dans certaines bibliothèques HTTP peut provoquer des erreurs de routage inattendues ; convertissez-le toujours en chaîne avant de construire l'URL. ^[2]

• Confusion entre liste et récupération unitaire. L'endpoint de liste (GET /api/v1/tasks/{taskId}/comments) retourne tous les commentaires d'une tâche, tandis que l'endpoint de récupération (GET /api/v1/tasks/{taskId}/comments/{commentId}) retourne un seul commentaire par son propre identifiant. Assurez-vous d'appeler le bon selon votre cas d'usage. ^[2][8]

Points à vérifier

• Vérification du scope : Confirmez que Desk.tasks.READ ou Desk.tasks.ALL apparaît dans les scopes accordés de votre token OAuth actif avant d'effectuer l'appel. ^[4]
• Identifiant de tâche valide : Assurez-vous que le taskId que vous utilisez existe bien dans votre portail Zoho Desk et appartient au bon contexte d'organisation. ^[2]
• Gestion de la pagination : Si la tâche comporte de nombreux commentaires, vérifiez si le paramètre p doit être incrémenté pour récupérer les pages de résultats suivantes. ^[2]