Comment créer un bot personnalisé avec Zendesk Switchboard : un guide pour les développeurs

Si vous devez créer un bot personnalisé qui s'intègre directement à l'infrastructure de messagerie de Zendesk, vous devrez travailler avec Zendesk Switchboard. Cette couche de routage au sein de Sunshine Conversations détermine quel système (votre bot, une IA tierce ou des agents humains) contrôle chaque conversation client.

La création d'une intégration personnalisée vous offre une flexibilité maximale. Vous contrôlez la logique, les règles de transfert et le comportement de votre bot sur différents canaux. Mais cela nécessite également des ressources de développement et une maintenance continue.

Pour les équipes qui souhaitent une automatisation sans la complexité de l'API, il existe un chemin plus simple. Nous gérons l'orchestration des bots automatiquement sans nécessiter de configuration Switchboard. Mais si vous avez besoin du contrôle total qu'offre l'intégration native, ce guide vous explique la configuration complète.

Ce dont vous aurez besoin

Avant de commencer, assurez-vous d'avoir :

• Zendesk Suite Professional ou supérieur – Les API Switchboard nécessitent au moins le plan Professional, qui commence à 115 $ par agent et par mois
• Informations d'identification de l'API Sunshine Conversations – Vous aurez besoin d'un ID de clé, d'un secret et d'un ID d'application depuis votre centre d'administration Zendesk
• Point de terminaison de webhook – Un point de terminaison HTTPS sécurisé où Zendesk peut envoyer des événements de conversation
• Environnement de développement – Votre bot doit être hébergé quelque part avec un accès Internet pour recevoir des webhooks et effectuer des appels d'API

Si vous n'êtes pas sur Suite Professional ou si vous ne disposez pas de ressources de développement, une solution gérée comme la nôtre se connecte via les canaux Zendesk standard sans nécessiter de configuration d'API.

Comprendre les concepts de Zendesk Switchboard

Le Switchboard peut sembler abstrait au début. Décomposons son fonctionnement réel.

Le switchboard et ses intégrations

Considérez le switchboard comme un contrôleur de trafic. Il se situe entre vos clients et vos systèmes d'entreprise, acheminant chaque conversation vers la bonne destination.

Chaque système capable de gérer les conversations apparaît comme une intégration de switchboard. Cela comprend :

• Agents Zendesk AI (le bot natif, identifié comme zd:answerBot)
• Agents AI Advanced (alimenté par Ultimate, identifié comme ultimate)
• Agent Workspace (vos agents humains, identifiés comme zd:agentWorkspace)
• Bots tiers (intégrations de la marketplace via OAuth)
• Intégrations personnalisées (votre bot basé sur webhook)

Source : Documentation Zendesk Switchboard

États d'intégration : actif, en attente et en veille

Chaque intégration de switchboard existe dans l'un des trois états pour une conversation donnée :

Une seule intégration peut être active à la fois. L'intégration active est celle qui est censée répondre aux messages des clients. Si votre bot est en veille, il ne recevra pas les événements conversation:message.

Source : Documentation Zendesk Switchboard

Opérations de transfert de contrôle

Votre bot doit gérer quatre opérations clés :

La plupart du temps, vous utiliserez passControl avec le mot clé "next" pour remonter vers l'intégration configurée comme votre prochain répondeur par défaut (généralement Agent Workspace).

Source : Documentation Zendesk Switchboard

Étape 1 : Obtenir vos informations d'identification de l'API Sunshine Conversations

Votre bot communiquera avec Zendesk via l'API Sunshine Conversations. Voici comment obtenir les informations d'identification dont vous avez besoin.

Tout d'abord, connectez-vous à votre centre d'administration Zendesk. Accédez à Applications et intégrations, puis à API Conversations. Si vous n'avez jamais créé d'informations d'identification d'API auparavant, cliquez sur Créer une clé API.

Vous recevrez :

• ID de clé (agit comme nom d'utilisateur pour l'authentification API)
• Secret (agit comme mot de passe, stockez-le en toute sécurité)
• ID d'application (identifie votre application Sunshine Conversations)

Enregistrez les trois valeurs. Vous les utiliserez dans chaque appel d'API effectué par votre bot.

Testez vos informations d'identification avec un simple appel d'API pour répertorier vos switchboards :

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards \
  --user '{key_id}:{secret}'

Si vous obtenez une réponse JSON avec les détails de votre switchboard, vos informations d'identification fonctionnent.

Source : Documentation du centre d'administration Zendesk

Étape 2 : Créer votre intégration personnalisée

Avant que votre bot puisse rejoindre le switchboard, il doit exister en tant qu'intégration dans Sunshine Conversations. Cela crée l'enregistrement du point de terminaison de webhook que Zendesk utilisera pour envoyer des événements à votre bot.

Utilisez l'API Create Integration :

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/integrations \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{
    "type": "custom",
    "name": "my-custom-bot",
    "webhooks": [{
      "target": "https://your-bot-endpoint.com/webhook",
      "triggers": ["conversation:create", "conversation:message"]
    }]
  }'

La réponse inclura un champ id. Enregistrez cet ID d'intégration, vous en aurez besoin pour l'étape suivante.

Source : Référence de l'API Zendesk Conversations

Étape 3 : Ajouter votre intégration au switchboard

Avoir une intégration ne suffit pas. Vous devez l'ajouter à votre switchboard afin qu'il puisse réellement recevoir le contrôle des conversations.

Tout d'abord, trouvez votre ID de switchboard :

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards \
  --user '{key_id}:{secret}'

Créez maintenant une intégration de switchboard qui relie votre intégration personnalisée au switchboard :

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards/{switchboard_id}/switchboardIntegrations \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{
    "name": "my-custom-bot",
    "integrationId": "{custom_integration_id}",
    "deliverStandbyEvents": false,
    "nextSwitchboardIntegrationId": "{agent_workspace_integration_id}"
  }'

Paramètres clés expliqués :

• name : Un identifiant lisible pour votre bot
• integrationId : L'ID de l'étape 2
• deliverStandbyEvents : Définissez sur false sauf si vous devez suivre les conversations que vous ne gérez pas activement
• nextSwitchboardIntegrationId : Généralement votre ID d'intégration Agent Workspace, cela détermine où vont les conversations lorsque votre bot remonte

Source : Référence de l'API Zendesk Conversations

Étape 4 : Configurer les webhooks pour votre bot

Votre bot doit recevoir des événements en temps réel de Zendesk. La configuration de webhook que vous avez définie à l'étape 2 définit où vont ces événements, mais votre point de terminaison doit les gérer correctement.

Événements de webhook requis

Au minimum, votre bot doit s'abonner à :

• conversation:create – Nouvelle conversation démarrée
• conversation:message – Le client a envoyé un message
• switchboard:passControl – Le contrôle a été transmis à ou depuis votre bot
• switchboard:releaseControl – La conversation a été libérée (ticket fermé)

Structure de la charge utile du webhook

Chaque webhook contient un tableau d'événements. Voici à quoi ressemble un événement de message :

{
  "app": { "id": "5ebee0975ac5304b664a12fa" },
  "webhook": { "id": "5f4eaef81e3dcc117c7ba48a", "version": "v2" },
  "events": [{
    "id": "5f74a0d52b5315fc007e798a",
    "createdAt": "2020-09-30T15:14:29.834Z",
    "type": "conversation:message",
    "payload": {
      "conversation": {
        "id": "f52b01137aa6c250bc7251fa",
        "activeSwitchboardIntegration": {
          "id": "67dc32a58d289d63bfeb6346",
          "name": "my-custom-bot"
        }
      },
      "message": {
        "author": { "type": "user" },
        "content": { "type": "text", "text": "I need help with my order" }
      }
    }
  }]
}

Vérifier que vous avez le contrôle

Avant de répondre à un message, vérifiez l'objet activeSwitchboardIntegration. Si le name ne correspond pas au nom de l'intégration de switchboard de votre bot, vous ne devez pas répondre. La conversation est gérée par un autre système.

Source : Documentation Zendesk Receiving Messages

Étape 5 : Implémenter la logique de transfert de contrôle

Lorsque votre bot détermine qu'il ne peut pas résoudre le problème du client, il doit remonter vers un agent humain. C'est là que passControl entre en jeu.

Remontée de base

Pour transmettre le contrôle à la prochaine intégration configurée (généralement Agent Workspace) :

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/passControl \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{"switchboardIntegration": "next"}'

Transmettre des métadonnées pour remplir les champs de ticket

L'une des fonctionnalités les plus puissantes est le remplissage des champs de ticket Zendesk lors du transfert. Incluez des métadonnées dans votre appel passControl :

{
  "switchboardIntegration": "zd-agentWorkspace",
  "metadata": {
    "dataCapture.systemField.priority": "high",
    "dataCapture.systemField.tags": "bot-escalated,shipping-issue",
    "dataCapture.systemField.group_id": "360000123456",
    "dataCapture.ticketField.54321": "Order #12345",
    "first_message_id": "603012d7e0a3f9000c879b67"
  }
}

Cela définit automatiquement la priorité du ticket, ajoute des balises, attribue à un groupe spécifique, remplit un champ personnalisé et contrôle la quantité d'historique de conversation que l'agent voit.

Libérer le contrôle après la résolution

Si votre bot résout complètement le problème du client, appelez releaseControl pour réinitialiser la conversation :

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/releaseControl \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{}'

Cela efface l'intégration active. Si le client revient plus tard, il recommencera avec votre répondeur par défaut.

Source : Référence de l'API Zendesk Conversations

Étape 6 : Tester votre intégration de bot personnalisé

Avant de passer en direct, vérifiez que chaque partie de votre intégration fonctionne correctement.

Liste de contrôle des tests

1. Créer une conversation de test via votre Web Widget ou votre canal de messagerie
2. Vérifier que votre bot reçoit l'événement conversation:create
3. Envoyer un message de test et confirmer que votre bot reçoit conversation:message
4. Vérifier que votre bot ne répond que lorsque activeSwitchboardIntegration.name correspond
5. Tester la remontée en déclenchant votre flux passControl
6. Vérifier la création de ticket dans Agent Workspace avec les métadonnées correctes
7. Fermer le ticket et confirmer que le contrôle revient à votre bot après l'exécution de l'automatisation

Problèmes de test courants

Source : Documentation Zendesk Agent Workspace

Modèles courants et meilleures pratiques

Routage spécifique au canal

Différents canaux ont souvent besoin de différents répondeurs par défaut. Configurez les valeurs par défaut par canal à l'aide de l'API Update Integration :

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/integrations/{channel_integration_id} \
  -X PATCH \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{"defaultResponderId": "{switchboard_integration_id}"}'

Par exemple, acheminez les conversations WhatsApp directement vers les agents (canal à forte valeur ajoutée) tout en envoyant d'abord le trafic Web Widget à votre bot.

Déploiements progressifs pendant les migrations

Si vous migrez d'une plateforme de bot à une autre, exécutez les deux simultanément pendant la transition :

1. Ajouter les deux bots en tant qu'intégrations de switchboard
2. Acheminer des marques ou des canaux spécifiques vers chaque bot
3. Déplacer progressivement le trafic au fur et à mesure que vous validez le nouveau bot
4. Supprimer l'ancienne intégration de bot une fois la migration terminée

Contrôle de l'historique des conversations

Par défaut, Zendesk inclut les 10 derniers messages lors de la création d'un ticket. Pour inclure la conversation complète, suivez l'ID du premier message lorsque la conversation démarre :

{
  "metadata": {
    "first_message_id": "{first_message_id}"
  }
}

Transmettez ceci dans votre appel passControl pour vous assurer que les agents voient l'historique complet de la conversation.

Dépannage des problèmes courants

Conversations bloquées sur la mauvaise intégration

Si les clients sont bloqués en train de parler à un bot qui aurait dû remonter, vérifiez que votre bot appelle passControl ou releaseControl correctement. Vérifiez également que nextSwitchboardIntegrationId est configuré sur l'intégration de switchboard de votre bot.

Métadonnées ne passant pas aux tickets

Les clés de champ doivent suivre des modèles exacts :

• Champs standard : dataCapture.systemField.{field_name}
• Champs personnalisés : dataCapture.ticketField.{field_id}

Vérifiez vos ID de champ personnalisé dans le centre d'administration Zendesk. Ce sont des valeurs numériques, pas les noms de champ que vous voyez dans l'interface utilisateur.

Transferts échouant silencieusement

Activez la journalisation pour tous les événements de webhook que votre bot reçoit. Si vous appelez passControl mais que vous ne voyez pas le changement de switchboard, vérifiez que vos informations d'identification API ont les étendues correctes et que votre JSON de charge utile est valide.

État d'intégration active inconnu

Si vous n'êtes pas sûr de l'intégration qui contrôle actuellement une conversation, utilisez l'API Get Conversation :

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id} \
  --user '{key_id}:{secret}'

Vérifiez la propriété activeSwitchboardIntegration dans la réponse.

Une approche plus simple de l'orchestration des bots Zendesk

La création et la maintenance d'une intégration Switchboard personnalisée nécessitent des ressources de développement continues. Votre équipe doit gérer l'infrastructure de webhook, le contrôle de version de l'API, la gestion des erreurs et la maintenance continue à mesure que Zendesk met à jour sa plateforme.

Pour les équipes qui souhaitent une automatisation sans la complexité de l'API, nous proposons une approche différente. eesel AI gère l'orchestration automatiquement sans nécessiter de configuration Switchboard.

Voici comment cela fonctionne :

• Aucune configuration d'API nécessaire – Nous nous intégrons via les canaux standard de Zendesk
• Apprend de votre contenu – Notre IA s'entraîne sur votre centre d'aide, vos tickets passés et votre documentation
• Routage automatique – Les conversations sont acheminées en fonction de vos règles, sans configuration manuelle du switchboard
• Règles de remontée en langage clair – Au lieu de JSON, vous définissez des règles telles que « Toujours remonter les litiges de facturation à un humain »

Notre plan Business comprend des fonctionnalités d'agent AI qui répondent directement aux clients, le triage AI pour le routage des tickets et la simulation en masse pour tester par rapport aux tickets passés avant de passer en direct. Les plans commencent à 239 $ par mois (facturation annuelle) avec un essai gratuit de 7 jours.

Le bon choix dépend de la capacité technique de votre équipe. Native Switchboard offre une flexibilité maximale pour une logique personnalisée complexe. Notre approche offre un délai de rentabilisation plus rapide lorsque vous souhaitez une automatisation sophistiquée sans le travail d'infrastructure.