Récupérer les abonnés d'un ticket dans Zoho Desk est simple grâce à une seule requête GET vers l'API REST de Desk — il vous suffit de l'identifiant du ticket cible et d'identifiants OAuth valides.
Pourquoi c'est important
Lorsque vous créez des automatisations, des outils d'audit ou des workflows de notification sur Zoho Desk, vous avez souvent besoin de savoir exactement qui est abonné aux mises à jour d'un ticket donné. Récupérer la liste des abonnés par programmation vous permet de synchroniser ces données avec des systèmes externes, d'appliquer des politiques d'abonnement ou d'afficher le nombre d'abonnés dans des tableaux de bord personnalisés. C'est également un complément utile aux opérations d'ajout et de suppression d'abonnés, qui vous permettent de gérer la liste une fois que vous en connaissez l'état actuel.
Étape par étape
Étape 1. Assurez-vous que votre jeton OAuth dispose des scopes Desk appropriés avant d'effectuer tout appel API. Vous avez au minimum besoin de Desk.tickets.READ dans votre ensemble de scopes autorisés — des scopes de tickets plus larges tels que Desk.tickets.ALL satisfont également cette exigence. [6]
Étape 2. Obtenez le ticketId du ticket dont vous souhaitez consulter les abonnés. Il s'agit de l'identifiant numérique interne que Zoho Desk attribue à chaque enregistrement de ticket, et non du numéro de ticket lisible par l'humain affiché dans l'interface. Vous pouvez le récupérer depuis n'importe quelle réponse API de liste ou de détail de ticket.
Étape 3. Envoyez une requête GET vers l'endpoint des abonnés, en substituant votre véritable identifiant de ticket dans le chemin :
GET /api/v1/tickets/{ticketId}/followersLe paramètre de requête optionnel p peut être transmis pour contrôler la pagination si la liste des abonnés est longue. [1]
Étape 4. En Python, si vous utilisez un wrapper ZohoDeskApi, appelez la méthode comme indiqué ci-dessous :
followers = api.get_ticket_followers(ticketId="your_ticket_id_here")
print(followers)Le wrapper émet la requête GET sous-jacente et retourne la réponse analysée. [1]
Étape 5. Inspectez le contenu de la réponse. L'objet retourné contiendra les enregistrements des abonnés pour ce ticket. Présentez les champs clés — tels que le nom et l'e-mail de l'agent — à vos utilisateurs finaux dans un format lisible, en ignorant les valeurs vides ou les identifiants internes bruts. [5]
Étape 6. Si votre intégration doit également modifier la liste des abonnés, notez qu'il existe deux endpoints complémentaires :
- Ajouter des abonnés :
POST /api/v1/tickets/{ticketId}/addFollowers— accepte un corpsdatacontenant les agents ou contacts à abonner. [3] - Supprimer des abonnés :
POST /api/v1/tickets/{ticketId}/removeFollowers— accepte un corpsdataidentifiant les abonnés à désabonner. [4]
Ces opérations sont distinctes de l'appel de lecture, donc votre jeton OAuth devra disposer de scopes de tickets en écriture (Desk.tickets.WRITE ou Desk.tickets.ALL) si vous souhaitez les utiliser. [6]
Étape 7. Si votre jeton d'accès a expiré, le client API doit le renouveler automatiquement à l'aide du refreshtoken stocké. Vérifiez que votre logique de renouvellement de jeton met à jour les valeurs accesstoken et tokenexpiresat persistées dans votre magasin de données après chaque cycle de renouvellement, afin que les appels suivants ne échouent pas. [7]
Erreurs courantes
orgIdmanquant ou incorrect : Zoho Desk exige un en-tête d'identifiant d'organisation sur chaque appel API. Si votre client a été initialisé sans undeskorgidvalide, la requête sera rejetée. L'approche recommandée est d'appeler l'endpoint des organisations lors de la première utilisation pour découvrir et persister automatiquement l'identifiant correct. [7]- Scopes OAuth insuffisants : Demander la liste des abonnés avec un jeton qui ne dispose que de
Desk.contacts.READouDesk.basic.READne fonctionnera pas — vous avez spécifiquement besoin d'un scope de lecture au niveau des tickets. Vérifiez votre chaîne de scopes configurée avant de chercher la cause ailleurs. [6] - Confusion entre le numéro de ticket et le
ticketId: Le paramètre de chemin{ticketId}est l'identifiant système interne, et non le numéro de style#1234visible dans l'interface Desk. Utiliser le numéro d'affichage retournera une erreur 404 ou un résultat vide.
Ce qu'il faut vérifier
- Confirmez que le jeton OAuth utilisé inclut
Desk.tickets.READouDesk.tickets.ALLdans ses scopes accordés. [6] - Vérifiez que le
ticketIdque vous transmettez est bien l'identifiant d'enregistrement Desk interne, et que le ticket existe réellement dans votre organisation. - Après un appel réussi, validez que la structure de la réponse correspond à ce qu'attend votre code en aval — en particulier si vous prévoyez de l'enchaîner avec les endpoints d'ajout ou de suppression d'abonnés. [3][4]
---
*Beam Help fournit une assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Référez-vous toujours à la documentation officielle de Zoho pour les spécifications API les plus récentes.*