Comment lister les tickets par contact dans Zoho Desk

Lister tous les tickets d'assistance associés à un contact spécifique dans Zoho Desk est simple dès lors que vous disposez de l'identifiant du contact — un seul appel API renvoie la liste complète des tickets de cette personne.

Pourquoi c'est important

Lorsqu'un client contacte votre équipe d'assistance à plusieurs reprises, vous avez besoin d'une vue consolidée de chaque ticket qu'il a jamais ouvert. Cela est essentiel pour comprendre l'historique d'un contact avant de répondre, pour les révisions d'escalade et pour les rapports sur les contacts à fort volume. Sans cette recherche, les agents doivent effectuer des recherches ou des filtres manuellement, ce qui est lent et source d'erreurs.

Étape par étape

Étape 1. Identifiez le contact_id de la personne dont vous souhaitez récupérer les tickets. Vous pouvez le trouver en accédant à Contacts dans votre portail Zoho Desk (le modèle d'URL suit desk.zoho.com/agent/{portal}/contacts) ou en interrogeant d'abord l'endpoint des contacts. L'identifiant est l'identifiant numérique unique affiché dans l'URL de la fiche contact. ^[1]

Étape 2. Vérifiez que votre token OAuth inclut les scopes Zoho Desk appropriés. Vous avez au minimum besoin de Desk.tickets.READ et Desk.contacts.READ pour résoudre le contact et lire ses tickets. Si vous utilisez une intégration plus large, des scopes tels que Desk.tickets.ALL couvriront également cette opération. ^[5]

Étape 3. Effectuez une requête GET vers l'endpoint de l'API Zoho Desk suivant, en substituant l'identifiant réel du contact dans le chemin : ^[2]

GET /api/v1/contacts/{contact_id}/tickets

L'opération est identifiée en interne sous le nom listticketsbycontact. Le paramètre de chemin contactid est obligatoire ; le paramètre de requête optionnel p peut être utilisé pour contrôler la pagination. ^[2]

Étape 4. En Python, l'appel ressemble à ceci : ^[2]

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

Passez l'identifiant du contact sous forme de chaîne de caractères. Si vous avez besoin d'une page spécifique de résultats, fournissez un dictionnaire de pagination comme second argument ; sinon, laissez-le à None. ^[2]

Étape 5. Analysez la réponse. L'API Zoho Desk renvoie des enregistrements de tickets contenant des champs clés tels que le sujet, le statut, l'agent assigné et le département. Notre équipe recommande d'afficher au minimum : le sujet du ticket, le statut actuel et l'agent responsable, afin que l'appelant obtienne un résumé immédiatement exploitable. ^[6]

Étape 6. Si vous souhaitez un lien direct dans le navigateur vers un ticket renvoyé dans la réponse, le modèle d'URL à construire est le suivant : ^[3]

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, et {TicketId} par l'identifiant issu de la réponse API. ^[3]

---

*Beam Help est une ressource d'assistance experte indépendante — et non le support officiel de Zoho.*

Erreurs courantes

• orgId manquant ou incorrect : Zoho Desk exige que l'identifiant d'organisation soit envoyé avec chaque requête API. S'il est absent, le système tentera de le découvrir automatiquement en appelant d'abord l'endpoint des organisations, puis persistera la valeur pour les appels futurs. Si vous rencontrez des erreurs d'authentification ou des erreurs « org not found », vérifiez que deskorgid est correctement stocké et transmis au client. ^{[7] [8]}
• Scopes OAuth insuffisants : La récupération des tickets d'un contact nécessite à la fois les permissions de lecture des contacts et des tickets. Si votre token a été émis sans Desk.contacts.READ ou Desk.tickets.READ, l'API renverra une erreur de permission. Réautorisez avec l'ensemble complet des scopes. ^[5]
• Pagination non gérée : Le paramètre p contrôle la page de résultats renvoyée. Si un contact possède de nombreux tickets et que vous omettez la gestion de la pagination, vous ne verrez que la première page. Parcourez les pages en boucle jusqu'à ce que la réponse renvoie moins d'enregistrements que la taille de page. ^[2]
• Mauvais centre de données : L'URL de base doit correspondre au centre de données où votre compte Desk est hébergé. Utiliser desk.zoho.com pour un compte hébergé en Europe échouera ; utilisez plutôt desk.zoho.eu. ^[3]

Ce qu'il faut vérifier

• Vérifiez que le contact_id que vous transmettez existe bien dans Zoho Desk en ouvrant la fiche contact dans le portail agent avant d'effectuer l'appel API. ^[1]
• Confirmez que votre token OAuth actif contient au moins Desk.tickets.READ et Desk.contacts.READ dans sa liste de scopes. ^[5]
• Vérifiez que le orgId (identifiant d'organisation) est correctement configuré dans votre client API, en particulier s'il s'agit du premier appel après une nouvelle autorisation OAuth. ^{[7] [8]}