Comment récupérer les tags et les abonnés dans Zoho Desk

Les tags et les abonnés d'un document Zoho Desk peuvent être récupérés avec une seule requête GET authentifiée vers le point de terminaison dédié aux tags et abonnés. Cet article vous explique exactement comment procéder à l'aide de l'API Zoho Desk.

Pourquoi c'est important

Lorsque vous créez des intégrations ou des automatisations autour de Zoho Desk, vous avez souvent besoin de savoir quels tags sont associés à un document et qui le suit — par exemple, pour déclencher des notifications ou filtrer du contenu par thème. L'opération tags_followers vous fournit ces deux informations en un seul appel. Il est tout aussi important de comprendre au préalable comment l'authentification et les identifiants d'organisation sont résolus, car un orgId manquant interrompra silencieusement la requête. (Remarque : Beam Help est un service d'assistance expert indépendant pour Zoho — nous ne sommes pas le support officiel de Zoho.)

---

Étape par étape

Étape 1. Assurez-vous de disposer d'une connexion Zoho Desk active avec un jeton d'accès valide et un identifiant d'organisation résolu (orgId). L'orgId est stocké dans votre enregistrement de connexion ; s'il est absent, le système appellera automatiquement getallorganizations, sélectionnera la première organisation retournée et conservera cet identifiant pour les requêtes futures. ^[2]

Étape 2. Instanciez un ZohoDeskClient en fournissant votre domaine API, le jeton d'accès actuel, l'orgId et un callback de renouvellement de jeton. Encapsulez-le dans un objet ZohoDeskApi afin de pouvoir appeler des méthodes de plus haut niveau. ^[2]

Étape 3. Vérifiez que votre jeton d'accès est toujours valide. Le callback de renouvellement interroge le refreshtoken stocké, appelle ZohoOAuth.refreshtokens et — si une clé access_token est présente dans la réponse — écrit le nouveau jeton et sa date d'expiration dans la base de données avant de le retourner. Cette opération s'effectue de manière transparente avant tout appel API. ^[2]

Étape 4. Appelez l'opération tags-and-followers. La signature de la méthode est :

def get_tags_followers(self, p: dict = None):
    """Tags & Followers"""
    return self.c.request("GET", f"/api/v1/_doc/tags___followers", p, None)

Passez les paramètres de requête dont vous avez besoin sous forme de dictionnaire dans l'argument p (par exemple, des clés de pagination ou de filtrage). Si vous n'avez pas de paramètres supplémentaires, passez un dictionnaire vide ou None. ^[5]

Étape 5. Le client sous-jacent émet une requête GET vers le chemin /api/v1/doc/tags__followers sur votre domaine API configuré, avec l'orgId injecté en tant qu'en-tête obligatoire ou paramètre de requête par la couche client. La réponse contient les données de tags et d'abonnés pour le document ciblé. ^[5]

Étape 6. Analysez le contenu retourné. Présentez les champs clés — tels que les noms de tags et les identifiants d'abonnés — directement à l'utilisateur final ou intégrez-les dans votre logique en aval. La couche assistant est conçue pour afficher ces champs dans un format lisible, séparé par des sauts de ligne, plutôt qu'en JSON brut. ^[7]

---

Erreurs courantes

• orgId manquant : Si l'identifiant d'organisation n'a jamais été stocké, le premier appel API tentera une découverte automatique. Si getallorganizations retourne une structure inattendue (ni un dictionnaire avec une clé "data", ni une liste simple), l'orgId restera vide et les requêtes suivantes échoueront. Vérifiez toujours que deskorgid est renseigné dans votre enregistrement de connexion après le premier appel réussi. ^[1][2]

• Jeton d'accès expiré : Le callback de renouvellement ne réussit que lorsque le refreshtoken stocké est toujours valide et que la réponse OAuth contient une clé accesstoken. Si le renouvellement échoue, le callback retourne None et l'appel API sera rejeté. Ré-authentifiez la connexion si vous constatez des erreurs de jeton répétées. ^[2]

• apptype incorrect : Le ZohoDeskClient et le ZohoDeskApi ne sont instanciés que lorsque apptype est défini sur "desk". Passer "crm" redirigera la requête vers le client CRM, qui n'expose pas la méthode gettagsfollowers. ^[2]

---

Ce qu'il faut vérifier

• Confirmez que deskorgid n'est pas vide dans votre enregistrement de connexion avant d'effectuer l'appel — une valeur vide déclenche la découverte automatique à chaque requête, ajoutant une latence inutile. ^[1][2]
• Vérifiez le statut de la réponse HTTP de /api/v1/doc/tags__followers ; un code 401 indique un problème de jeton, tandis qu'un code 403 pointe généralement vers un en-tête orgId incorrect ou manquant. ^[5]
• Après avoir récupéré les données, vérifiez que le tableau de tags et la liste d'abonnés sont tous deux présents dans le contenu — un résultat vide peut signifier que le document n'a pas encore de tags ni d'abonnés, plutôt qu'une erreur dans votre requête. ^[5]