Avec les Webhooks, l'API Apps envoie une notification en temps réel à votre application chaque fois qu'un événement pertinent se produit lors d'une session de chat (par exemple, lorsqu'un chat est créé, qu'un message est reçu, ou qu'un chat est transféré ou escaladé). Utilisez des webhooks pour réagir à l'activité du chat en temps réel au lieu d'interroger l'API.
Les Webhooks sont limités aux sessions de chat sur l'API Apps. Contact Center AI Platform fournit tous les événements de webhook de chat d'API d'applications compatibles en tant que requêtes HTTP POST à une seule URL de webhook que vous configurez. Il n'existe pas d'abonnement par événement.
Avant de commencer
- Pour configurer des Webhooks, vous devez être administrateur ou disposer d'un rôle vous permettant de modifier les paramètres pour les développeurs.
- Préparez un point de terminaison pouvant recevoir des requêtes HTTP
POST. L'URL de webhook doit utiliser le protocole HTTPS.
Activer les webhooks
Lorsque vous activez les webhooks, Contact Center AI Platform envoie les événements de webhook à l'URL que vous avez configurée. Les champs "URL" et "Secret" s'affichent alors. Lorsque les Webhooks sont désactivés, aucun événement n'est envoyé.
Pour activer les webhooks, procédez comme suit :
- Dans le portail CCAI Platform, cliquez sur Settings > Developer Settings (Paramètres > Paramètres pour les développeurs). Si le menu Paramètres ne s'affiche pas, cliquez sur Menu.
- Accédez au volet Webhooks, puis cliquez sur le bouton Webhooks pour l'activer.
Configurer l'URL de webhook
- Dans URL, saisissez le point de terminaison de votre webhook.
- Vérifiez que le point de terminaison utilise le protocole HTTPS et peut recevoir des requêtes
POST. Contact Center AI Platform envoie tous les événements compatibles à cette URL unique.
Générer des secrets de signature
Contact Center AI Platform signe chaque requête de webhook afin que votre application puisse confirmer que la requête provient de Contact Center AI Platform. Il envoie la signature dans l'en-tête de requête X-Signature et l'horodatage de la signature dans X-Signature-Timestamp.
Vous pouvez configurer jusqu'à deux secrets de signature :
- Code secret principal : jeton principal utilisé pour signer les requêtes de webhook.
- Secret secondaire : deuxième jeton facultatif. Lorsqu'un code secret secondaire est défini, Contact Center AI Platform signe chaque requête avec les deux codes secrets, ce qui vous permet de les faire alterner sans manquer d'événements.
Générez chaque secret séparément. Pour générer un secret, procédez comme suit :
- Dans le portail CCAI Platform, cliquez sur Settings > Developer Settings (Paramètres > Paramètres pour les développeurs). Si le menu Paramètres ne s'affiche pas, cliquez sur Menu.
- Accédez au volet Webhooks.
- Dans la section Secret principal, cliquez sur Générer. Cliquez sur Copier pour copier un secret et le stocker de manière sécurisée. La clé secrète complète ne s'affiche que juste après sa génération. Il est ensuite masqué.
- Facultatif : Dans la section Secret secondaire, cliquez sur Générer. Cliquez sur Copier pour copier un secret et le stocker de manière sécurisée.
- Confirmez dans la boîte de dialogue d'avertissement. Un nouveau secret prend effet immédiatement. Par conséquent, tout ce qui utilise encore un secret remplacé échoue.
Effectuer une rotation des secrets de signature
Lorsqu'un secret principal existe, l'action Rotate Secrets (Faire pivoter les secrets) devient disponible. Pour des raisons de sécurité, il est recommandé d'alterner régulièrement vos secrets. Étant donné que Contact Center AI Platform signe chaque requête avec les secrets principal et secondaire, vous pouvez les faire pivoter sans interrompre la diffusion :
- Dans le portail CCAI Platform, cliquez sur Settings > Developer Settings (Paramètres > Paramètres pour les développeurs). Si le menu Paramètres ne s'affiche pas, cliquez sur Menu.
- Assurez-vous qu'un secret principal et un secret secondaire sont définis.
- Cliquez sur Rotate Secrets (Faire pivoter les secrets) pour échanger les secrets principal et secondaire.
- Mettez à jour votre application pour valider les signatures par rapport au nouveau secret actif. Pendant la période de chevauchement, Contact Center AI Platform signe chaque requête avec les deux secrets configurés. Vous pouvez donc accepter l'un ou l'autre, et la diffusion n'est pas interrompue.
Enregistrer votre configuration
Sélectionnez Enregistrer pour appliquer l'état activé et l'URL du webhook. La génération ou la rotation d'un code secret prennent effet immédiatement et ne nécessitent pas d'opération d'enregistrement. Contact Center AI Platform commence à envoyer des événements une fois les Webhooks activés et une URL de Webhook et un code secret principal définis.
Ce que votre application reçoit
Une fois les webhooks activés, Contact Center AI Platform envoie une requête HTTP POST pour chaque événement de chat compatible, comme les modifications du cycle de vie, l'activité des participants, les messages, les transferts, les escalades, les formulaires Web et les avertissements de fermeture. Chaque corps de requête est une enveloppe JSON avec event_type, timestamp, chat_id et un body spécifique à l'événement.