Comment créer une intégration personnalisée Zendesk Sunshine Conversations

Créer une intégration personnalisée avec Zendesk Sunshine Conversations vous permet de créer des expériences de messagerie sur mesure qui correspondent exactement aux besoins de votre entreprise. Que vous souhaitiez connecter un CRM propriétaire, créer un bot spécialisé ou orchestrer des flux de conversation complexes, l'API Sunshine Conversations vous fournit les bases dont vous avez besoin.

Ce guide vous explique tout, de la configuration initiale au déploiement en production. À la fin, vous disposerez d'un serveur webhook fonctionnel qui peut recevoir des messages, répondre intelligemment et passer la main à des agents humains si nécessaire. Pour une référence officielle, consultez la documentation de l'API Zendesk.

Si vous préférez éviter le travail d'ingénierie, eesel AI offre une alternative sans code qui se connecte à Zendesk en quelques minutes et gère les conversations de manière autonome.

Zendesk Sunshine Conversations connecte les canaux de messagerie à vos applications d'entreprise via des webhooks et des API.

Ce dont vous aurez besoin

Avant de vous lancer, assurez-vous d'avoir les éléments suivants en place.

Exigences Zendesk :

• Un plan Zendesk Suite Professional ou Enterprise (l'accès à l'API Sunshine Conversations nécessite ces niveaux)
• Un accès administrateur à votre compte Zendesk
• Au moins 1 000 utilisateurs actifs mensuels (MAU, Monthly Active Users) inclus dans votre plan (des packs de MAU supplémentaires sont disponibles au prix de 50 $ par 2 500 MAU)

Exigences techniques :

• Un environnement serveur (Node.js recommandé pour ce guide)
• ngrok pour les tests de webhook locaux
• Connaissance de base des API REST et des webhooks
• Point de terminaison HTTPS pour la production

Comprendre l'architecture de Sunshine Conversations

Sunshine Conversations est la plateforme de messagerie unifiée de Zendesk. Initialement Smooch.io (acquis par Zendesk en 2019), elle alimente désormais la messagerie dans l'ensemble de la suite Zendesk. L'architecture est construite autour de quelques concepts clés que vous devez comprendre avant de construire.

Applications (Apps) : Chaque application représente une entreprise ou une marque. Vous créerez une application dans le Centre d'administration qui contiendra toutes vos données de conversation.

Intégrations : Ce sont les connexions entre Sunshine Conversations et les systèmes externes. Les intégrations personnalisées utilisent des webhooks pour envoyer et recevoir des messages.

Conversations : Une conversation est un fil de messages entre un utilisateur et votre entreprise. Les conversations persistent sur tous les canaux (un utilisateur peut commencer sur le chat Web et continuer sur WhatsApp).

Switchboard : Il contrôle qui « possède » une conversation à un moment donné. Le Switchboard achemine les conversations entre les bots, les agents et les intégrations.

Authentification : L'API utilise l'authentification de base (l'ID de clé comme nom d'utilisateur, le secret comme mot de passe) ou les jetons JWT pour une sécurité renforcée.

Le flux fonctionne comme ceci : un client envoie un message via n'importe quel canal connecté (widget Web, WhatsApp, etc.). Sunshine Conversations reçoit le message et le transmet à votre intégration webhook. Votre serveur traite le message, décide de la manière de répondre et renvoie une réponse via l'API. Si nécessaire, votre intégration peut transférer le contrôle à un agent humain via le Switchboard.

Étape 1 : Créez votre application Sunshine Conversations et vos clés API

Tout d'abord, vous devez créer une application et générer des informations d'identification API.

Accédez au Centre d'administration Zendesk. Allez dans Applications et intégrations > API > API Conversations.

Cliquez sur Créer une clé API et donnez-lui un nom descriptif tel que « Intégration Webhook de production ». Vous recevrez trois informations :

• ID d'application (App ID) : Un identifiant unique pour votre application
• ID de clé (Key ID) : Utilisé comme nom d'utilisateur pour l'authentification API
• Clé secrète (Secret Key) : Utilisée comme mot de passe pour l'authentification API

Stockez ces informations d'identification en toute sécurité. Vous en aurez besoin pour chaque appel API. La clé secrète n'est affichée qu'une seule fois. Si vous la perdez, vous devrez générer une nouvelle paire de clés.

Configurez vos variables d'environnement pour garder les informations d'identification hors de votre code :

export SUNSHINE_APP_ID="your_app_id"
export SUNSHINE_KEY_ID="your_key_id"
export SUNSHINE_SECRET="your_secret_key"

Étape 2 : Configurez votre intégration webhook

Créez maintenant l'intégration webhook qui recevra les événements de message.

Dans le Centre d'administration, allez dans Intégrations > Intégrations Conversations.

Cliquez sur Créer une intégration et sélectionnez Personnalisée (Custom) comme type. Configurez les éléments suivants :

URL cible (Target URL) : Pour le développement local, utilisez votre URL ngrok (nous la configurerons à l'étape suivante). Pour la production, utilisez votre point de terminaison HTTPS.

Déclencheurs (Triggers) : Sélectionnez les événements que vous souhaitez recevoir. Au minimum, activez :

• conversation:message - Reçoit tous les messages entrants
• postback - Reçoit les clics sur les boutons et les réponses rapides
• conversation:start - Notifie lorsqu'une nouvelle conversation commence

Secret : Générez une chaîne aléatoire pour la vérification de la signature webhook. Cela garantit que les requêtes proviennent réellement de Zendesk.

Enregistrez votre ID Webhook (affiché après la création) et le secret partagé (Shared Secret) que vous avez configuré. Vous aurez besoin des deux pour la vérification de la signature.

Étape 3 : Créez votre serveur webhook

Créons un simple serveur Express.js qui reçoit et répond aux messages.

Tout d'abord, initialisez votre projet :

mkdir sunshine-integration
cd sunshine-integration
npm init -y
npm install express crypto dotenv

Créez un fichier index.js :

require('dotenv').config();
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.raw({ type: 'application/json' }));

// Webhook verification middleware
function verifyWebhook(req, res, next) {
  const signature = req.headers['x-smooch-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  const hash = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');

  if (hash !== signature) {
    return res.status(401).send('Unauthorized');
  }
  next();
}

// Handle incoming messages
app.post('/webhook', verifyWebhook, async (req, res) => {
  const event = JSON.parse(req.body);

  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process the event
  if (event.trigger === 'message:appUser') {
    await handleUserMessage(event);
  }
});

async function handleUserMessage(event) {
  const message = event.messages[0];
  const userId = event.appUser._id;
  const conversationId = event.conversation._id;

  console.log(`Received: ${message.text} from ${userId}`);

  // Simple echo response (replace with your logic)
  await sendMessage(conversationId, `You said: ${message.text}`);
}

async function sendMessage(conversationId, text) {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  const response = await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/conversations/${conversationId}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        author: { type: 'business' },
        content: { type: 'text', text: text }
      })
    }
  );

  if (!response.ok) {
    console.error('Failed to send message:', await response.text());
  }
}

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Créez un fichier .env :

SUNSHINE_APP_ID=your_app_id
SUNSHINE_KEY_ID=your_key_id
SUNSHINE_SECRET=your_secret_key
WEBHOOK_SECRET=your_webhook_secret

Démarrez votre serveur :

node index.js

Étape 4 : Testez localement avec ngrok

Étant donné que Sunshine Conversations nécessite un point de terminaison HTTPS public, utilisez ngrok pour exposer votre serveur local.

Installez ngrok et démarrez un tunnel :

ngrok http 3000

Copiez l'URL HTTPS (quelque chose comme https://abc123.ngrok.io). Mettez à jour votre intégration webhook dans le Centre d'administration avec cette URL comme URL cible.

Testez votre intégration en envoyant un message via le widget Web Zendesk ou tout canal connecté. Vous devriez voir le message enregistré dans la console de votre serveur, et le bot devrait renvoyer le message.

Étape 5 : Configurez le Switchboard pour les transferts bot-agent

Le Switchboard contrôle le moment où votre bot gère les messages par rapport au moment où les agents humains prennent le relais. Ceci est essentiel pour les déploiements en production.

Concepts clés du Switchboard :

• Passer le contrôle (Pass Control) : Transfère immédiatement la propriété à une autre intégration
• Offrir le contrôle (Offer Control) : Partage le contrôle jusqu'à ce que la cible accepte
• Libérer le contrôle (Release Control) : Renvoie la conversation à son état par défaut

Pour trouver votre ID Switchboard :

async function getSwitchboardId() {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  const response = await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/switchboards`,
    {
      headers: { 'Authorization': `Basic ${auth}` }
    }
  );

  const data = await response.json();
  return data.switchboards[0].id;
}

Pour passer à un agent humain :

async function escalateToAgent(conversationId, switchboardId, metadata = {}) {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/conversations/${conversationId}/switchboard/passControl`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        switchboardIntegration: 'zd:agentWorkspace', // Zendesk Agent Workspace
        metadata: {
          priority: 'high',
          topic: metadata.topic || 'general',
          ...metadata
        }
      })
    }
  );
}

Lorsque vous passez le contrôle avec des métadonnées, Zendesk remplit automatiquement les champs de ticket, définit la priorité et achemine vers l'équipe appropriée en fonction de vos déclencheurs.

Étape 6 : Connectez les canaux de messagerie

Votre intégration fonctionne avec n'importe quel canal connecté à Sunshine Conversations. Les canaux disponibles incluent :

• Widget Web (intégré)
• API WhatsApp Business
• Facebook Messenger
• Instagram
• Apple Messages for Business
• LINE
• Telegram
• SMS via Twilio ou MessageBird
• SDK Android et iOS

Pour ajouter un canal, accédez à Centre d'administration > Canaux > [Nom du canal] et suivez les étapes d'authentification. Chaque canal a des exigences spécifiques :

• WhatsApp : Nécessite la vérification Meta Business et un compte API WhatsApp Business
• Facebook/Instagram : Se connecte via votre Facebook Business Manager
• SMS : Nécessite un compte Twilio ou MessageBird avec un numéro de téléphone

Une fois connectés, tous les messages transitent par le même point de terminaison webhook, quel que soit le canal. Votre code n'a pas besoin d'être modifié pour prendre en charge de nouveaux canaux.

Test et débogage de votre intégration

Avant de passer en direct, testez minutieusement votre intégration.

Meilleures pratiques de développement local :

• Utilisez la fonction de relecture de ngrok pour renvoyer les webhooks pendant le débogage
• Implémentez une journalisation complète pour chaque événement reçu et action entreprise
• Créez des conversations de test et vérifiez le flux complet du message à la réponse

Erreurs courantes et solutions :

Limitation du débit : Sunshine Conversations limite les requêtes API à 100 par minute par défaut. Implémentez une gestion appropriée :

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await delay(retryAfter * 1000);
  // Retry the request
}

Limites de taille de conversation : Les conversations ont une limite de 30 000 messages. Archivez les anciennes conversations pour rester sous cette limite.

Meilleures pratiques de sécurité

Les intégrations de production nécessitent des mesures de sécurité supplémentaires.

Stockage des informations d'identification : Ne validez jamais les informations d'identification dans le contrôle de version. Utilisez des variables d'environnement ou un gestionnaire de secrets comme AWS Secrets Manager ou HashiCorp Vault. Zendesk suit les pratiques de sécurité standard de l'industrie pour protéger vos données.

Vérification de la signature du webhook : Vérifiez toujours l'en-tête X-Smooch-Signature. Sans cela, n'importe qui peut envoyer de faux webhooks à votre point de terminaison.

HTTPS uniquement : Sunshine Conversations nécessite HTTPS pour les URL webhook en production. Utilisez un certificat SSL valide.

Authentification JWT : Pour une sécurité renforcée, passez de l'authentification de base aux jetons JWT :

function generateJWT() {
  const header = { alg: 'HS256', typ: 'JWT' };
  const now = Math.floor(Date.now() / 1000);
  const payload = {
    scope: 'app',
    iat: now,
    exp: now + 600 // 10 minutes
  };

  const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
  const signature = crypto
    .createHmac('sha256', process.env.SUNSHINE_SECRET)
    .update(`${encodedHeader}.${encodedPayload}`)
    .digest('base64url');

  return `${encodedHeader}.${encodedPayload}.${signature}`;
}

Rotation des clés API : Générez régulièrement de nouvelles clés et révoquez les anciennes. Sunshine Conversations prend en charge plusieurs clés actives pour une rotation sans interruption de service.

Déploiement en production

Lorsque vous êtes prêt à passer en direct, suivez cette liste de contrôle.

Liste de contrôle de déploiement en production :

• Passez de ngrok à un point de terminaison HTTPS permanent
• Implémentez une gestion des erreurs et une logique de nouvelle tentative appropriées
• Configurez la surveillance et les alertes pour les échecs de webhook
• Configurez l'agrégation des journaux pour le débogage
• Testez les transferts Switchboard avec des agents réels
• Vérifiez que la limitation du débit n'aura pas d'impact sur votre cas d'utilisation
• Documentez vos politiques de transfert

Recommandations de surveillance :

Suivez ces mesures pour garantir une intégration saine :

• Taux de réussite de la livraison des webhooks (cible : > 99 %)
• Temps de réponse moyen (maintenir en dessous de 5 secondes)
• Taux d'erreur par type d'erreur
• Volume de conversation par canal

Configurez des alertes pour les échecs de livraison de webhook, les taux d'erreur élevés et les limites de débit approchantes.

Alternative : eesel AI pour une implémentation plus rapide

La création d'une intégration personnalisée vous donne un contrôle total, mais elle nécessite un temps de développement important et une maintenance continue. Si vous avez besoin d'une messagerie basée sur l'IA sans les frais généraux d'ingénierie, envisagez eesel AI comme alternative.

eesel AI se connecte directement à Zendesk et gère automatiquement l'ensemble du flux de conversation. Au lieu de créer des webhooks et une logique Switchboard, vous :

1. Connectez eesel AI à votre compte Zendesk (intégration en un clic)
2. Entraînez l'agent d'IA sur vos anciens tickets, votre centre d'aide et votre documentation
3. Configurez les règles de transfert en langage clair (« Transférer les litiges de facturation à l'équipe des finances »)
4. Testez dans un bac à sable avec les anciens tickets avant de passer en direct

Les intégrations personnalisées sont judicieuses lorsque vous avez des systèmes propriétaires qui ne correspondent pas aux modèles standard ou qui ont besoin de flux de conversation hautement spécialisés. Pour la plupart des équipes qui cherchent à ajouter la messagerie IA à Zendesk, eesel AI offre des résultats plus rapides avec moins de maintenance. Vous pouvez voir eesel en action ou l'essayer gratuitement.

Commencez à créer avec Zendesk Sunshine Conversations

Vous avez maintenant tout ce dont vous avez besoin pour créer une intégration personnalisée avec Zendesk Sunshine Conversations. De la création de clés API et de la configuration de webhooks à la gestion du Switchboard et au déploiement en production, les bases sont en place.

Les prochaines étapes dépendent de votre cas d'utilisation spécifique. Vous pouvez intégrer à votre CRM pour extraire les données client, vous connecter à une base de connaissances pour des réponses intelligentes ou créer une logique de routage personnalisée basée sur le contenu du message.

Si la route personnalisée vous semble demander plus d'ingénierie que votre équipe ne peut en assumer pour le moment, nous pouvons vous aider. Nos agents d'IA s'intègrent à Zendesk en quelques minutes et gèrent les conversations de manière autonome tout en transférant à votre équipe en cas de besoin. Vous pouvez essayer eesel gratuitement et le tester sur les anciens tickets pour voir exactement comment il fonctionnerait avant de passer en direct.