Comment lister les événements par ticket dans Zoho Desk

Lister les événements associés à un ticket spécifique dans Zoho Desk s'effectue via une simple requête GET ciblant l'identifiant unique du ticket. Chez Beam Help — support expert indépendant pour Zoho (et non le support officiel Zoho) — nous vous guidons pas à pas dans cette configuration.

Pourquoi c'est important

Lors de la gestion des workflows de support, vous avez souvent besoin de consulter tous les événements planifiés ou enregistrés liés à un ticket particulier — comme des appels de suivi ou des réunions. Les récupérer de manière programmatique vous permet de créer des tableaux de bord, d'automatiser des rappels ou d'auditer l'activité sans parcourir manuellement l'interface agent de Zoho Desk. Cela s'avère particulièrement utile lors de l'intégration des données Desk dans des outils de reporting externes ou des portails personnalisés.

Étape par étape

Étape 1. Vérifiez que votre token OAuth inclut le scope Desk events approprié avant tout appel API. Le scope requis pour la lecture des événements est Desk.events.READ, et pour un accès complet (création, mise à jour, suppression) vous aurez besoin de Desk.events.ALL. Ces deux scopes doivent être présents dans votre token autorisé. ^[2]

Étape 2. Identifiez le ticketId du ticket dont vous souhaitez récupérer les événements. Il s'agit de l'identifiant numérique ou alphanumérique unique attribué par Zoho Desk à chaque enregistrement de ticket. Vous pouvez l'obtenir depuis l'URL du ticket dans le portail agent ou à partir d'un appel API précédent ayant retourné des données de ticket. ^[3]

Étape 3. Envoyez une requête GET vers l'endpoint suivant, en substituant l'identifiant réel de votre ticket dans le chemin :

GET /api/v1/tickets/{ticketId}/events

Cette opération est nommée listeventsby_ticket dans l'API Zoho Desk. Le paramètre de chemin ticketId est obligatoire ; le paramètre de requête p est optionnel et peut être utilisé pour transmettre des options de pagination ou de filtrage supplémentaires. ^[3]

Étape 4. Dans le code, l'appel se présente ainsi (en Python) :

def list_events_by_ticket(self, ticketId: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/tickets/{ticketId}/events", p, None)

Passez l'identifiant du ticket sous forme de chaîne de caractères, et fournissez éventuellement un dictionnaire de paramètres de requête via p si vous avez besoin de filtrer ou de paginer les résultats. ^[3]

Étape 5. Analysez la réponse. Le payload retourné contiendra une clé events sous un wrapper data. Parcourez la liste pour accéder aux objets événement individuels et à leurs propriétés. ^[7]

Étape 6. Si vous créez un lien dans une interface utilisateur pour naviguer directement vers le ticket dans le portail agent Zoho Desk, le modèle d'URL suit cette structure :

https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}

Remplacez {dc} par le suffixe de votre centre de données (par ex., com, eu, in), {portal} par le nom de votre portail Desk ou l'ID de votre organisation, et {TicketId} par l'identifiant du ticket concerné. ^[5]

Erreurs courantes

• Scope OAuth manquant ou incorrect. Si votre token a été généré sans Desk.events.READ ou Desk.events.ALL, l'API retournera une erreur d'autorisation. Vérifiez toujours la liste complète des scopes dans votre configuration OAuth avant de tester. ^[2]

• orgId incorrect ou manquant. Les appels à l'API Zoho Desk nécessitent que l'identifiant d'organisation correct soit résolu et attaché au contexte de la requête. Si le deskorgid n'est pas défini dans votre enregistrement de connexion, le système peut ne pas être en mesure d'acheminer la requête vers la bonne organisation. Assurez-vous que votre connexion dispose d'un deskorgid valide et qu'il est transmis au client API. ^[4]

• Confusion entre événements et tâches. Zoho Desk expose un endpoint distinct pour les tâches liées à un ticket — GET /api/v1/tickets/{ticketid}/tasks — qui correspond à une opération différente (listtasksbyticket). Assurez-vous d'appeler le chemin /events et non le chemin /tasks si ce sont bien des événements dont vous avez besoin. ^[8]

• Tableau events vide. Si aucun événement n'a été enregistré pour le ticket, la réponse retournera une liste vide plutôt qu'une erreur. Concevez votre code pour gérer ce cas correctement, sans traiter un résultat vide comme un échec. ^[7]

Points à vérifier

• Vérifiez que votre token OAuth inclut au minimum Desk.events.READ et qu'il n'a pas expiré avant d'effectuer l'appel. ^[2]
• Confirmez que le ticketId que vous transmettez existe bien dans votre organisation Desk et appartient au orgId correct configuré dans votre connexion. ^[4]
• Assurez-vous que votre logique d'analyse de réponse gère sans erreur aussi bien une liste events remplie qu'une liste vide. ^[7]