Référence de l'API d'automatisation Zendesk : un guide pratique pour les développeurs

L'API d'automatisation Zendesk vous offre un contrôle programmatique sur les règles métier temporelles qui assurent le bon fonctionnement de votre service d'assistance. Alors que les déclencheurs se déclenchent immédiatement lorsque des événements se produisent, les automatisations s'exécutent selon un calendrier, vérifiant les conditions toutes les heures et effectuant des actions lorsque ces conditions sont remplies.

Si vous créez des intégrations personnalisées, migrez des flux de travail entre des environnements ou gérez Zendesk à grande échelle, il est essentiel de comprendre cette API. Ce guide couvre tout ce dont vous avez besoin pour implémenter efficacement les automatisations, de l'authentification aux exemples de code concrets.

Pour les équipes sans ressources de développement, il existe une autre voie. eesel AI se connecte directement à Zendesk et gère bon nombre des mêmes scénarios d'automatisation via une interface sans code. Nous explorerons les deux approches afin que vous puissiez choisir celle qui convient à votre équipe.

Comprendre les automatisations Zendesk

Une automatisation est une règle métier temporelle qui effectue une ou plusieurs actions lorsque des conditions spécifiques sont remplies. Contrairement aux déclencheurs, qui répondent instantanément aux événements tels que la création de tickets ou les changements de statut, les automatisations évaluent les conditions toutes les heures.

Voici la distinction clé :

• Les déclencheurs réagissent immédiatement aux événements. Un déclencheur se déclenche lorsqu'un ticket est créé, mis à jour ou lorsqu'un champ spécifique change.
• Les automatisations s'exécutent selon un calendrier. Elles vérifient les conditions toutes les heures et exécutent des actions uniquement lorsque ces conditions sont vraies.

Ce timing rend les automatisations parfaites pour les scénarios où vous devez attendre avant d'agir. Les cas d'utilisation courants incluent :

• Alertes SLA : Informer les responsables lorsque les tickets restent non résolus après 24 heures
• Escalade de ticket : Augmenter la priorité ou réaffecter les tickets ouverts depuis trop longtemps
• Séquences de suivi : Envoyer des e-mails de rappel aux clients qui n'ont pas répondu
• Nettoyage des tickets obsolètes : Fermer les tickets résolus après une période d'inactivité
• Équilibrage de la charge de travail des agents : Réaffecter les tickets des agents surchargés

Le cycle de vie de l'automatisation fonctionne comme ceci : toutes les heures, Zendesk évalue toutes les automatisations actives par rapport à tous les tickets qui répondent aux critères temporels. Si les conditions correspondent, les actions s'exécutent. Il est important de noter que les automatisations continueront de se déclencher tant que les conditions restent vraies, vous devez donc les concevoir avec soin pour éviter les actions répétées.

Authentification et configuration

Avant de pouvoir créer ou gérer des automatisations via l'API, vous devez configurer l'authentification. L'API d'automatisation Zendesk utilise l'authentification basée sur un jeton avec HTTP Basic Auth.

Génération d'un jeton d'API

1. Connectez-vous à votre Zendesk en tant qu'administrateur
2. Accédez à Centre d'administration > Applications et intégrations > API > API Zendesk
3. Cliquez sur l'onglet Paramètres
4. Activez Accès par jeton s'il n'est pas déjà activé
5. Cliquez sur le bouton + pour ajouter un nouveau jeton
6. Donnez à votre jeton un nom descriptif tel que « Gestion de l'automatisation »
7. Copiez immédiatement le jeton (il ne sera plus affiché)

Pour des conseils détaillés, consultez la documentation Zendesk sur la génération de jetons d'API.

Format d'authentification

L'API d'automatisation Zendesk utilise l'authentification de base. Vous devez encoder en Base64 vos informations d'identification dans ce format :

{adresse_e-mail}/token:{jeton_api}

Par exemple, si votre e-mail est admin@company.com et votre jeton est abc123xyz, vous encodez :

admin@company.com/token:abc123xyz

Voici une commande curl pour tester votre authentification :

curl https://{sous-domaine}.zendesk.com/api/v2/automations \
  -v -u {adresse_e-mail}/token:{jeton_api}

Remplacez {sous-domaine} par votre sous-domaine Zendesk, {adresse_e-mail} par votre e-mail d'administrateur et {jeton_api} par le jeton que vous avez généré.

Structure de l'URL de base

Tous les points de terminaison de l'API d'automatisation utilisent cette URL de base :

https://{sous-domaine}.zendesk.com/api/v2/automations

Limites de débit

Zendesk applique des limites de débit pour maintenir la stabilité du système. La plupart des points de terminaison autorisent 700 requêtes par minute, mais cela peut varier en fonction de votre plan et de votre point de terminaison. Si vous dépassez la limite, vous recevrez une réponse 429 Too Many Requests. Implémentez une interruption exponentielle dans votre code pour gérer cela avec élégance.

Points de terminaison de l'API principale

L'API d'automatisation fournit des opérations CRUD standard. Voici les points de terminaison que vous utiliserez le plus souvent.

Liste des automatisations

GET /api/v2/automations

Ce point de terminaison renvoie toutes les automatisations de votre compte. Vous pouvez filtrer par statut actif et contrôler le tri.

Paramètres disponibles :

Paramètre	Type	Description
active	boolean	Filtrer les automatisations actives (true) ou inactives (false)
sort_by	string	Trier par « alphabetical », « created_at », « updated_at », « usage_1h », « usage_24h » ou « usage_7d »
sort_order	string	« asc » ou « desc »

Exemple curl :

curl https://{sous-domaine}.zendesk.com/api/v2/automations?active=true \
  -u {adresse_e-mail}/token:{jeton_api}

Afficher l'automatisation

GET /api/v2/automations/{id}

Récupérer une seule automatisation par son ID.

Exemple curl :

curl https://{sous-domaine}.zendesk.com/api/v2/automations/25 \
  -u {adresse_e-mail}/token:{jeton_api}

Créer une automatisation

POST /api/v2/automations

Créer une nouvelle automatisation. Le corps de la requête doit inclure un objet JSON avec la définition de l'automatisation.

Exigences importantes pour les nouvelles automatisations :

• Doit avoir au moins une condition temporelle
• Doit inclure au moins une condition vérifiant status, type, group_id, assignee_id ou requester_id
• Doit avoir une action qui annule au moins une condition (empêche les boucles infinies)

Exemple curl :

curl -u {adresse_e-mail}/token:{jeton_api} \
  https://{sous-domaine}.zendesk.com/api/v2/automations \
  -H "Content-Type: application/json" -X POST -d \
  '{
    "automation": {
      "title": "Escalader les anciens tickets",
      "all": [
        { "field": "status", "operator": "is", "value": "open" },
        { "field": "hours_since_created", "operator": "greater_than", "value": "24" }
      ],
      "actions": [
        { "field": "priority", "value": "high" }
      ]
    }
  }'

Mettre à jour l'automatisation

PUT /api/v2/automations/{id}

Modifier une automatisation existante. Envoyez l'objet d'automatisation complet avec vos modifications.

Supprimer l'automatisation

DELETE /api/v2/automations/{id}

Supprimer définitivement une automatisation.

Pagination

L'API prend en charge deux méthodes de pagination :

• Pagination par curseur (recommandée) : Utilisez ?page[size]=50&page[after]=cursor pour de meilleures performances avec les grands ensembles de données
• Pagination par décalage : Utilisez ?page=2&per_page=50 pour des implémentations plus simples

Structure de l'objet d'automatisation

Une automatisation est représentée sous forme d'objet JSON avec des propriétés spécifiques. Comprendre cette structure est essentiel pour créer des automatisations efficaces.

Propriétés principales

Propriété	Type	Obligatoire	Description
title	string	Oui	Nom lisible pour l'automatisation
actions	array	Oui	Actions à effectuer lorsque les conditions sont remplies
conditions	object	Oui	Conditions qui doivent être vraies pour que les actions s'exécutent
active	boolean	Non	Indique si l'automatisation est activée (par défaut : true)
position	integer	Non	Ordre d'exécution (les nombres les plus bas s'exécutent en premier)

Propriétés en lecture seule

Propriété	Type	Description
id	integer	Identifiant unique attribué par Zendesk
created_at	string	Horodatage ISO 8601 de la création
updated_at	string	Horodatage ISO 8601 de la dernière modification
default	boolean	Indique s'il s'agit d'une automatisation par défaut du système

L'objet conditions

L'objet conditions contient deux tableaux qui définissent quand l'automatisation s'exécute :

{
  "conditions": {
    "all": [
      { "field": "status", "operator": "is", "value": "open" },
      { "field": "hours_since_created", "operator": "greater_than", "value": "24" }
    ],
    "any": [
      { "field": "priority", "operator": "is", "value": "high" }
    ]
  }
}

• all : Toutes les conditions de ce tableau doivent être vraies (logique ET)
• any : Au moins une condition de ce tableau doit être vraie (logique OU)

Le tableau actions

Les actions définissent ce qui se passe lorsque les conditions sont remplies. Chaque action a un champ et une valeur :

{
  "actions": [
    { "field": "priority", "value": "high" },
    { "field": "group_id", "value": "360000000000" }
  ]
}

Exemple complet

Voici un objet d'automatisation complet qui escalade les tickets ouverts depuis plus de 24 heures :

{
  "automation": {
    "title": "Escalader les tickets ouverts > 24 heures",
    "active": true,
    "conditions": {
      "all": [
        { "field": "status", "operator": "is", "value": "open" },
        { "field": "hours_since_created", "operator": "greater_than", "value": "24" },
        { "field": "priority", "operator": "less_than", "value": "high" }
      ],
      "any": []
    },
    "actions": [
      { "field": "priority", "value": "high" },
      { "field": "current_tags", "value": "escalated" }
    ],
    "position": 1
  }
}

Conditions et actions disponibles

Les automatisations partagent de nombreuses conditions et actions avec les déclencheurs et les macros, mais elles ont également des capacités temporelles uniques. Pour une référence complète, consultez la documentation des actions Zendesk.

Champs de condition courants

Ces champs fonctionnent sur les automatisations, les déclencheurs et les macros :

Champ	Description	Opérateurs d'exemple
status	Statut du ticket	is, is_not, less_than
priority	Priorité du ticket	is, less_than, greater_than
type	Type de ticket	is, is_not
assignee_id	Agent affecté	is, is_not
group_id	Groupe affecté	is, is_not
requester_id	Demandeur du ticket	is, is_not
current_tags	Balises sur le ticket	includes, not_includes
via	Canal d'où provient le ticket	is, is_not

Conditions temporelles (spécifiques à l'automatisation)

Ces conditions sont propres aux automatisations et permettent des flux de travail temporels :

Champ	Description
hours_since_created	Heures depuis la création du ticket
hours_since_updated	Heures depuis la dernière mise à jour
hours_since_assigned	Heures depuis l'affectation du ticket
hours_since_requester_updated	Heures depuis la dernière mise à jour du demandeur
hours_since_agent_updated	Heures depuis la dernière mise à jour de l'agent
hours_since_due_date	Heures jusqu'à ou depuis la date d'échéance

Opérateurs de condition

Opérateur	Description
is	Correspondance exacte
is_not	Ne correspond pas
less_than	Numériquement ou alphabétiquement inférieur
greater_than	Numériquement ou alphabétiquement supérieur
includes	Contient la valeur (pour les balises, les listes)
not_includes	Ne contient pas la valeur

Actions partagées

Ces actions fonctionnent dans les automatisations, les déclencheurs et les macros :

Champ	Description	Valeurs d'exemple
status	Modifier le statut du ticket	"open", "pending", "solved", "closed"
priority	Définir la priorité	"low", "normal", "high", "urgent"
type	Définir le type de ticket	"question", "incident", "problem", "task"
assignee_id	Affecter à l'agent	ID d'agent ou « current_user »
group_id	Affecter au groupe	ID de groupe
set_tags	Remplacer toutes les balises	"tag1 tag2 tag3"
current_tags	Ajouter des balises	"new_tag"
remove_tags	Supprimer des balises	"old_tag"

Actions spécifiques à l'automatisation

Champ	Description
notification_user	Envoyer un e-mail à l'utilisateur
notification_group	Envoyer un e-mail au groupe
notification_target	Envoyer à la cible externe
notification_webhook	Déclencher un webhook
satisfaction_score	Envoyer une enquête de satisfaction

Exemples d'implémentation pratiques

Passons en revue quelques scénarios d'automatisation concrets avec des exemples de code complets.

Exemple 1 : Escalader automatiquement les tickets ouverts depuis plus de 24 heures

Cette automatisation augmente la priorité et ajoute une balise d'escalade pour les tickets ouverts depuis trop longtemps.

Requête :

curl -u {adresse_e-mail}/token:{jeton_api} \
  https://{sous-domaine}.zendesk.com/api/v2/automations \
  -H "Content-Type: application/json" -X POST -d \
  '{
    "automation": {
      "title": "Escalader les tickets ouverts > 24 heures",
      "active": true,
      "conditions": {
        "all": [
          { "field": "status", "operator": "is", "value": "open" },
          { "field": "hours_since_created", "operator": "greater_than", "value": "24" },
          { "field": "priority", "operator": "less_than", "value": "high" }
        ]
      },
      "actions": [
        { "field": "priority", "value": "high" },
        { "field": "current_tags", "value": "escalated" }
      ]
    }
  }'

Réponse :

{
  "automation": {
    "id": 3600123456789,
    "title": "Escalader les tickets ouverts > 24 heures",
    "active": true,
    "conditions": {
      "all": [
        { "field": "status", "operator": "is", "value": "open" },
        { "field": "hours_since_created", "operator": "greater_than", "value": "24" },
        { "field": "priority", "operator": "less_than", "value": "high" }
      ]
    },
    "actions": [
      { "field": "priority", "value": "high" },
      { "field": "current_tags", "value": "escalated" }
    ],
    "position": 1,
    "created_at": "2026-02-24T10:00:00Z",
    "updated_at": "2026-02-24T10:00:00Z"
  }
}

Exemple 2 : Envoyer un e-mail de rappel pour les tickets en attente après 48 heures

Cette automatisation envoie un e-mail au demandeur lorsque son ticket est en attente depuis deux jours.

curl -u {adresse_e-mail}/token:{jeton_api} \
  https://{sous-domaine}.zendesk.com/api/v2/automations \
  -H "Content-Type: application/json" -X POST -d \
  '{
    "automation": {
      "title": "Rappel : Ticket en attente 48 heures",
      "active": true,
      "conditions": {
        "all": [
          { "field": "status", "operator": "is", "value": "pending" },
          { "field": "hours_since_updated", "operator": "greater_than", "value": "48" }
        ]
      },
      "actions": [
        {
          "field": "notification_user",
          "value": ["requester_id", "Nous travaillons toujours sur votre demande", "Votre ticket est en attente depuis 48 heures. Veuillez répondre avec toute information supplémentaire."]
        }
      ]
    }
  }'

Exemple 3 : Fermer les tickets résolus après 72 heures d'inactivité

Cette automatisation permet de garder votre file d'attente de tickets propre en fermant automatiquement les tickets résolus.

curl -u {adresse_e-mail}/token:{jeton_api} \
  https://{sous-domaine}.zendesk.com/api/v2/automations \
  -H "Content-Type: application/json" -X POST -d \
  '{
    "automation": {
      "title": "Fermeture automatique des tickets résolus après 72 heures",
      "active": true,
      "conditions": {
        "all": [
          { "field": "status", "operator": "is", "value": "solved" },
          { "field": "hours_since_updated", "operator": "greater_than", "value": "72" }
        ]
      },
      "actions": [
        { "field": "status", "value": "closed" }
      ]
    }
  }'

Exemple 4 : Baliser les tickets VIP pour le routage prioritaire

Cette automatisation balise les tickets des clients VIP pour une gestion spéciale.

curl -u {adresse_e-mail}/token:{jeton_api} \
  https://{sous-domaine}.zendesk.com/api/v2/automations \
  -H "Content-Type: application/json" -X POST -d \
  '{
    "automation": {
      "title": "Baliser les tickets des clients VIP",
      "active": true,
      "conditions": {
        "all": [
          { "field": "current_tags", "operator": "includes", "value": "vip_customer" }
        ],
        "any": [
          { "field": "status", "operator": "is", "value": "new" },
          { "field": "status", "operator": "is", "value": "open" }
        ]
      },
      "actions": [
        { "field": "priority", "value": "high" },
        { "field": "current_tags", "value": "vip_priority" }
      ]
    }
  }'

Test et débogage

Avant de déployer des automatisations en production, vous devez les tester minutieusement.

Utilisation de la console API Zendesk

Zendesk fournit une console API dans la documentation du développeur où vous pouvez tester les requêtes sans écrire de code. Ceci est utile pour vérifier votre structure JSON et votre authentification.

Test avec Postman

Zendesk gère une collection Postman officielle qui inclut des points de terminaison d'automatisation. Importez cette collection pour tester les points de terminaison avec une interface conviviale. Vous pouvez également explorer la documentation de référence de l'API Zendesk complète pour obtenir des informations détaillées sur tous les points de terminaison disponibles.

Réponses d'erreur courantes

Statut HTTP	Signification	Causes courantes
200 OK	Succès	Requête terminée avec succès
201 Created	Créé	L'automatisation a été créée avec succès
400 Bad Request	Requête non valide	JSON mal formé, champs obligatoires manquants
401 Unauthorized	Authentification échouée	Informations d'identification ou jeton non valides
403 Forbidden	Autorisation refusée	L'utilisateur n'a pas les droits d'administrateur/d'agent
404 Not Found	Ressource introuvable	L'ID d'automatisation n'existe pas
422 Unprocessable	Validation échouée	Conditions ou actions non valides
429 Too Many Requests	Limite de débit atteinte	Trop de requêtes, réessayer avec une interruption

Vérification de l'exécution de l'automatisation

Pour vérifier si votre automatisation s'exécute correctement :

1. Affichez les événements de ticket pour voir les actions d'automatisation dans le journal d'activité
2. Utilisez le sideload usage_24h lors de la liste des automatisations pour voir les nombres d'exécution
3. Vérifiez l'horodatage updated_at de l'automatisation pour confirmer qu'elle est active

Tester les conditions avant la mise en service

Créez une automatisation de test avec une balise unique que vous pouvez facilement identifier. Appliquez-la à un ticket de test et surveillez les résultats avant de la déployer en production.

Limites de débit et bonnes pratiques

Le respect des bonnes pratiques vous aidera à créer des automatisations fiables et maintenables.

Gestion des limites de débit

La limite de débit par défaut de Zendesk est de 700 requêtes par minute pour la plupart des points de terminaison. Si vous atteignez cette limite :

1. Implémentez une interruption exponentielle dans votre code
2. Utilisez la pagination par curseur pour lister un grand nombre d'automatisations
3. Mettez en cache les résultats le cas échéant
4. Traitez les opérations par lots lorsque cela est possible

Position de l'automatisation et ordre d'exécution

Les automatisations s'exécutent dans l'ordre de position, du plus bas au plus élevé. Placez les automatisations urgentes plus tôt dans la séquence pour vous assurer qu'elles s'exécutent rapidement.

Éviter les boucles d'automatisation

L'erreur d'automatisation la plus courante est la création de boucles infinies. Incluez toujours une action qui modifie une condition :

• Si vous vérifiez status: open, modifiez le statut dans vos actions
• Si vous vérifiez priority: low, modifiez la priorité
• Ajoutez une balise unique et vérifiez son absence

Quand utiliser l'API par rapport au générateur natif

Utilisez l'API lorsque vous devez :

• Gérer les automatisations sur plusieurs instances Zendesk
• Contrôler la version de vos configurations d'automatisation
• Créer des automatisations par programmation en fonction de données externes
• Intégrer avec des outils d'infrastructure en tant que code tels que Terraform

Utilisez le générateur d'automatisation natif de Zendesk lorsque :

• Vous ne gérez qu'une seule instance Zendesk
• Vos automatisations changent rarement
• Vous préférez une interface visuelle

Alternative : Automatisation sans code avec eesel AI

La création et la maintenance d'automatisations basées sur l'API nécessitent des ressources de développement, une infrastructure de test et une maintenance continue. Pour de nombreuses équipes, ces frais généraux ne sont pas pratiques.

eesel AI offre une approche alternative. Au lieu d'écrire du code, vous connectez eesel AI à votre instance Zendesk et configurez les automatisations via des instructions en langage naturel.

Voici comment les approches se comparent :

Aspect	API Zendesk	eesel AI
Temps de configuration	Heures à jours	Minutes
Compétences techniques requises	Développeur	Aucune
Maintenance	Mises à jour du code, tests