Enregistrement de l'activité avec un webhook
Vous pouvez enregistrer l'activité en effectuant un appel vers un service ou une application externe chaque fois qu'un client soumet des données à l'assistant.
Un webhook est un mécanisme que vous pouvez utiliser pour appeler un programme externe en fonction d'événements survenus dans votre programme.
Cette fonction n'est disponible que pour les utilisateurs des plans Plus et Entreprise. Le plan Plus ne permet pas plus de 5 webhooks par instance. Cette limite ne s'applique pas aux instances du plan Enterprise.
Ajoutez un webhook de journalisation à votre assistant si vous souhaitez utiliser un service externe pour journaliser l'activité. Vous pouvez consigner deux types d'activité :
Messages et réponses: Le webhook du journal est déclenché chaque fois que l'assistant répond à un message du client. Vous pouvez utiliser cette option comme alternative à la fonction d'analyse intégrée pour gérer vous-même la journalisation. (Pour plus d'informations sur le support d'analyse intégrée, voir Examiner l'intégralité de votre assistant en un coup d'œil.)
Si vous utilisez un canal personnalisé, le webhook de journalisation ne fonctionne qu'avec l'API v2 " /message (sans état et avec état). Pour plus d'informations, consultez la documentation de l'API. Toutes les intégrations de canal intégrées utilisent cette API.
Enregistrements détaillés des appels (CDR): Le webhook d'enregistrement est déclenché après chaque appel téléphonique d'un utilisateur à votre assistant qui utilise l'intégration téléphonique. Un enregistrement de détails d'appel (CDR) est un rapport récapitulatif qui documente les détails d'un appel téléphonique, y compris les numéros de téléphone, la longueur d'appel, le temps d'attente et d'autres informations de diagnostic. Les enregistrements CDR ne concernent que les assistants qui utilisent l'intégration téléphonique.
Le webhook de journal ne renvoie rien à votre assistant.
Pour les environnements où les nœuds finaux privés sont en cours d'utilisation, gardez à l'esprit qu'un webhook en ligne envoie du trafic sur Internet.
Définition du webhook
Vous pouvez définir une URL de webhook à utiliser pour la journalisation de chaque message entrant ou événement CDR.
L'appel par programmation au service externe doit répondre aux conditions suivantes :
L'appel doit être une demande HTTP POST.
Pour ajouter les détails du webhook, procédez comme suit :
Dans votre assistant, ouvrez l'environnement dans lequel vous souhaitez configurer le webhook.
Cliquez sur
l'icône pour ouvrir les paramètres de l'environnement.Sur la page Paramètres de l'environnement, cliquez sur Log webhook.
Pour l'assistant que vous souhaitez configurer, cliquez sur
l'icône, puis sélectionnez Paramètres.Cliquez sur Webhooks, puis sur Log webhook.
Définissez le commutateur webhook du journal sur Activé.
Si vous ne pouvez pas activer le webhook, vous devrez peut-être mettre à niveau votre plan de service.
Dans la zone URL, ajoutez l'URL de l'application externe à laquelle vous souhaitez envoyer des appels de demande POST HTTP. Par exemple,
https://example.com/my_log_service.
Vous devez spécifier une URL qui utilise le protocole SSL, donc indiquez une URL commençant parhttps.
Dans la zone du secret, ajoutez un jeton à transmettre avec la demande qui peut être utilisée pour l'authentification auprès du service externe.
Le secret doit être spécifié sous la forme d'une chaîne de texte, telle que purple unicorn. La longueur maximale est de 1 024 caractères. Vous ne pouvez pas spécifier une variable de contexte.
Il est de la responsabilité du service extérieur de vérifier et de tester le secret. Si le service externe ne nécessite pas de jeton, indiquez la chaîne de votre choix. Vous ne pouvez pas laisser cette zone vide.
Si vous souhaitez voir le mot de passe au fur et à mesure que vous le saisissez, cliquez sur l'icône « Afficher le mot 
de passe » avant de commencer à taper. Après avoir enregistré le secret, la chaîne est remplacée par des astérisques et ne peut plus être consultée.
Cliquez sur les cases à cocher appropriées pour sélectionner les types d'activité à consigner :
Pour consigner les messages et les réponses, sélectionnez S'abonner aux journaux de conversation.
Pour consigner les événements CDR pour l'intégration téléphonique, sélectionnez S'abonner à CDR (Call Detail Records).
Dans la section Headers, ajoutez les en-têtes que vous souhaitez transmettre au service, l'un après l'autre, en cliquant sur Add header.
Le service envoie automatiquement un en-tête Authorization avec un JWT ; vous n'avez pas besoin d'en ajouter un. Si vous souhaitez gérer l'autorisation vous-même, ajoutez votre propre en-tête d'autorisation et il sera utilisé à la place.
Après avoir enregistré la valeur de l'en-tête, la chaîne est remplacée par des astérisques et ne peut plus être consultée.
Les détails du webhook sont sauvegardés automatiquement.
Retrait du webhook
Si vous décidez de ne pas consigner les messages à l'aide d'un webhook, procédez comme suit :
Dans votre assistant, allez dans Environnements et ouvrez l'environnement dans lequel vous souhaitez configurer le webhook.
Cliquez sur
l'icône pour ouvrir les paramètres de l'environnement.Sur la page Paramètres de l'environnement, cliquez sur Log webhook.
Pour l'assistant que vous souhaitez configurer, cliquez sur
l'icône, puis sélectionnez Paramètres.Cliquez sur Webhooks, puis sur Log webhook.
Effectuez l'une des opérations suivantes :
Pour modifier le webhook que vous souhaitez appeler, cliquez sur Supprimer le webhook pour supprimer l'URL et le secret actuellement spécifiés. Vous pouvez ensuite ajouter une adresse URL et d'autres détails.
Pour arrêter d'appeler un webhook pour consigner chaque message et réponse, cliquez sur le commutateur webhook du journal pour désactiver complètement le webhook.
Sécurité du webhook
Pour authentifier la demande webhook, vérifiez le jeton Web JSON (JWT) qui est envoyé avec la demande. Le micro-service webhook génère automatiquement un JWT et l'envoie dans l'en-tête Authorization avec chaque appel webhook. Il est de votre responsabilité d'ajouter du code au service externe qui vérifie le JWT.
Par exemple, si vous indiquez " purple unicorn dans le champ Secret, vous pouvez ajouter un code tel que :
const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
// error thrown if token is invalid
}Corps de demande Webhook
Le corps de la requête que le webhook envoie au service externe est un objet JSON avec la structure suivante :
{
"event": {
"name": "{event_type}"
},
"payload": {
...
}
}Où {event_type} est message_logged (pour les messages et les réponses) ou cdr_logged (pour les événements CDR).
L'objet payload contient les données d'événement à consigner. La structure de l'objet payload dépend du type d'événement.
Contenu d'événement de message
Pour les événements " message_logged, l'objet " payload contient des données relatives à une demande de message envoyée à l'assistant et à la réponse au message renvoyée à l'application d'intégration ou à l'application client. Pour plus d'informations sur les zones qui font partie des demandes de message et des réponses, voir le Référence de l'interface de programmation.
Le contenu du journal de webhook peut inclure des données qui ne sont pas actuellement prises en charge par l'API. Les zones qui ne sont pas définies dans la documentation de référence de l'interface de programmation peuvent être modifiées.
Charge d'événement de l'enregistrement de détail d'appel
Pour les événements cdr_logged, l'objet payload contient des données relatives à un événement CDR (enregistrement de détail d'appel) géré par l'intégration téléphonique. La structure de l'objet payload pour un événement d'enregistrement de détail d'appel est comme illustré par cet exemple :
{
"primary_phone_number": "+18005550123",
"global_session_id": "9caa8bad-aaa8-4a5a-a4b5-62bccc703d15",
"failure_occurred": false,
"transfer_occurred": false,
"active_calls": 0,
"warnings_and_errors": [
{
"code": "CWSMR0033W",
"message": "CWSMR0033W: The inbound RTP audio stream jitter of 43 ms exceeds the maximum jitter threshold of 30 ms."
},
{
"code": "CWSMR0070W",
"message": "CWSMR0070W: A request to the Watson Speech To Text service failed for the following reason = Unexpected server response: 403, response headers = {\"strict-transport-security\":\"max-age=31536000; includeSubDomains;\",\"content-length\":\"157\",\"content-type\":\"application/json\",\"x-dp-watson-tran-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-request-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-global-transaction-id\":\"6c764df3-81db-41bb-a14f-62384facffca\",\"server\":\"watson-gateway\",\"x-edgeconnect-midmile-rtt\":\"1\",\"x-edgeconnect-origin-mex-latency\":\"28\",\"date\":\"Thu, 13 May 2021 20:31:12 GMT\",\"connection\":\"keep-alive\"}, response body = {\"code\":403,\"trace\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"error\":\"Forbidden\",\"more_info\":\"[https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error](https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error)\"}, x-global-transaction-id = 6c764df3-81db-41bb-a14f-62384facffca. The Media Relay will reattempt to send the request."
}
],
"realtime_transport_network_summary": {
"inbound_stream": {
"average_jitter": 4,
"canonical_name": "b74f3689-1ae8-4a0a-bde3-adf5b488553e",
"maximum_jitter": 18,
"packets_lost": 0,
"packets_transmitted": 952,
"tool_name": ""
},
"outbound_stream": {
"average_jitter": 0,
"canonical_name": "voice.gateway",
"maximum_jitter": 0,
"packets_lost": 0,
"packets_transmitted": 838,
"tool_name": "IBM Voice Gateway/1.0.7.0"
}
},
"call": {
"start_timestamp": "2021-10-12T20:54:02.591Z",
"stop_timestamp": "2021-10-12T20:54:20.375Z",
"milliseconds_elapsed": 17784,
"outbound": false,
"end_reason": "assistant_hangup",
"security": {
"media_encrypted": false,
"signaling_encrypted": false,
"sip_authenticated": false
}
},
"session_initiation_protocol": {
"invite_arrival_time": "2021-10-12T20:54:00.565Z",
"setup_milliseconds": 2026,
"headers": {
"call_id": "17465345_115257202@10.90.150.99",
"from_uri": "sip:+18885550456@pstn.twilio.com",
"to_uri": "sip:+18005550123@public.voip.us-south.assistant.test.watson.cloud.ibm.com"
}
},
"max_response_milliseconds": {
"assistant": 339,
"text_to_speech": 535,
"speech_to_text": 0
},
"assistant_interaction_summaries": [
{
"session_id": "7874ec3a-1330-4180-afe1-46bfb220af5b",
"assistant_id": "97f16ba4-ad94-41af-aa6c-33cd56ad5e7e",
"turns": [
{
"assistant": {
"log_id": "58bebfd1-0118-419b-a555-b152a1efbbe8",
"response_milliseconds": 339,
"start_timestamp": "2021-10-12T20:54:00.722Z"
},
"request": {
"type": "start"
},
"response": [
{
"barge_in_occurred": true,
"streaming_statistics": {
"response_milliseconds": 301,
"start_timestamp": "2021-10-12T20:54:00.722Z",
"stop_timestamp": "2021-10-12T20:54:01.023Z",
"transaction_id": "3dce431c-fb2f-4b62-9fce-585f4e06fe00"
},
"type": "text_to_speech"
}
]
},
{
"assistant": {
"log_id": "38f36bfb-c2aa-4600-9418-6ab422664e31",
"response_milliseconds": 158,
"start_timestamp": "2021-10-12T20:54:05.621Z"
},
"request": {
"type": "dtmf"
},
"response": [
{
"type": "disable_speech_barge_in"
},
{
"type": "text_to_speech",
"barge_in_occurred": false,
"streaming_statistics": {
"transaction_id": "af4c47c3-5cc4-43c8-9b9c-81d6f997c52f",
"start_timestamp": "2021-10-12T20:54:06.321Z",
"stop_timestamp": "2021-10-12T20:54:14.338Z",
"response_milliseconds": 535
}
},
{
"type": "enable_speech_barge_in"
},
{
"type": "text_to_speech",
"barge_in_occurred": true,
"streaming_statistics": {
"transaction_id": "eafdd846-2829-4e1a-8068-b1035510b1e1",
"start_timestamp": "2021-10-12T20:54:14.795Z",
"stop_timestamp": "2021-10-12T20:54:20.388Z",
"response_milliseconds": 447
}
}
]
},
{
"assistant": {
"log_id": "07d74b35-0205-43e4-923c-1e43e1cb429c",
"response_milliseconds": 0,
"start_timestamp": "2021-10-12T20:54:20.377Z"
},
"request": {
"type": "hangup"
},
"response": []
}
]
}
]
}
Pour plus d'informations sur la structure de la charge utile de l'événement CDR, voir la référence de l'événement du journal CDR.