Webhooks
Si le canal de messagerie à utiliser n'est pas pris en charge immédiatement dans Oracle Digital Assistant, vous pouvez utiliser un webhook pour l'intégrer manuellement.
-
Serveur de messagerie HTTP accessible publiquement qui relaie les messages entre l'appareil de l'utilisateur et votre assistant numérique (ou votre brique) à l'aide d'un webhook.
Vous pouvez implémenter ce webhook à l'aide des éléments suivants :
-
Appel POST permettant au serveur de recevoir des messages de l'assistant numérique.
-
Appel POST permettant au serveur d'envoyer des messages à l'assistant numérique.
-
-
URI de l'appel de webhook qui reçoit les messages de votre assistant numérique (indique à l'assistant numérique où envoyer les messages).
-
URL de webhook générée pour l'assistant numérique une fois que vous avez renseigné les champs de la boîte de dialogue Créer un canal (permet au serveur de messagerie d'accéder à votre assistant numérique).
-
Configurez le serveur.
-
Pour recevoir des messages de l'assistant numérique, publiez l'appel POST sur le serveur.
-
Dans la boîte de dialogue Créer un canal, entrez un nom, puis effectuez les opérations suivantes :
-
Choisissez Webhook comme type de canal.
-
Définissez la version de la plate-forme sur 1.1 (modèle de conversation).
-
Inscrivez le serveur comme destinataire des messages de l'assistant numérique en entrant l'URI de cet appel POST dans le champ URI de webhook sortant.
-
Si nécessaire, entrez l'expiration de la session et activez l'option Canal activé.
Description de l'illustration create-webhook-channel.png -
-
Cliquez sur Créer.
Digital Assistant génère l'URL de webhook de votre assistant numérique, ainsi que sa clé secrète pour le cryptage des messages. Assurez-vous que l'URL de webhook est pratique, car il s'agit du pointeur dont votre serveur de messagerie a besoin pour renvoyer des messages à votre assistant numérique.
Description de l'image webhook-channel-config.png -
Sur votre serveur, publiez la seconde API POST, qui envoie des messages à votre assistant numérique à l'aide de l'URL de webhook.
-
Activez l'option Canal activé.
Vous pouvez utiliser le kit SDK Node.js de Digital Assistant pour configurer l'envoi de messages à votre assistant numérique et à partir de celui-ci.
Messages entrants
La bibliothèque WebhookClient
dans le kit SDK Node.js d'Oracle Digital Assistant simplifie la configuration de l'envoi et de la réception de messages dans les canaux de webhook. Si vous n'utilisez pas le kit SDK, voici ce que vous devez savoir sur la création de messages entrants.
L'appel permettant d'envoyer des messages à votre assistant numérique (ou brique) doit comporter les éléments suivants :
-
En-tête
X-Hub-Signature
contenant la valeur SHA256 de la charge utile. Cet appel inclut des fonctions qui créent le hachage en utilisant la clé secrète en tant que clé.const body = Buffer.from(JSON.stringify(messageToBot), 'utf8'); const headers = {}; headers['Content-Type'] = 'application/json; charset=utf-8'; headers['X-Hub-Signature'] = buildSignatureHeader(body, channelSecretKey); ... function buildSignatureHeader(buf, channelSecretKey) { return 'sha256=' + buildSignature(buf, channelSecretKey); } function buildSignature(buf, channelSecretKey) { const hmac = crypto.createHmac('sha256', Buffer.from(channelSecretKey, 'utf8')); hmac.update(buf); return hmac.digest('hex'); }
BOT_WEBHOOK_URL
etBOT_WEBHOOK_SECRET
sont des variables d'environnement que vous définissez sur le serveur de noeud. L'utilisation de ces variables d'environnement vous permet d'éviter de coder en dur les informations sensibles directement dans le webhook. -
Objet JSON comportant les propriétés
userId
,profile
etmessagePayload
:{ "userId": "33c0bcBc8e-378c-4496-bc2a-b2b9647de2317", "profile": { "firstName": "Bob", "lastName": "Franklin", "age": 45 }, "messagePayload": {....} }
Propriété Description Type Requis ? userId
Identificateur unique de l'utilisateur. Cet ID est propre à l'appelant. Chaîne Oui profile
Propriétés représentant l'utilisateur, telles que firstName
etLastName
.Objet JSON Non messagePayload
La valeur messagePayload
peut êtretext
,postback
,attachment
oulocation
.Objet JSON Oui Remarque
Si votre brique ou votre assistant numérique doit détecter la langue utilisateur, assurez-vous queprofile.locale
etprofile.languageTag
sont définis sur NULL dans les messages de webhook.
Exemples de charge utile : messages entrants
Type de message | Exemple de charge utile |
---|---|
text |
|
postback |
|
attachment |
|
location |
|
Messages sortants
La bibliothèque WebhookClient
dans le kit SDK Node.js d'Oracle Digital Assistant simplifie la configuration de l'envoi et de la réception de messages dans les canaux de webhook. Si vous n'utilisez pas le kit SDK, voici ce que vous devez savoir sur la création de messages sortants.
Vous devez publier les appels au format JSON attendu par Digital Assistant, ainsi que l'en-tête d'autorisation.
-
En-tête
X-Hub-Signature
contenant la valeur SHA256 de la charge utile, calculé en utilisant la clé secrète en tant que clé.Remarque
Digital Assistant utilise l'en-têteX-Hub-Signature
pour permettre au destinataire d'authentifier l'assistant numérique en tant qu'expéditeur et de valider l'intégrité de la charge utile. -
Charge utile JSON comportant l'identificateur unique
userID
spécifié par le message entrant, à savoirtype
, qui peut prendre les valeurstext
,attachment
etcard
. Comme illustré dans les exemples suivants, les types de réponsetext
etcard
peuvent être associés à des actions. Tous les types de réponse peuvent également inclure des actions globales.Type de réponse Exemple de charge utile text
{ "userId":"22343248763458761287 "messagePayload": { "type": "text", "text": "Hello, how are you?" } }
Le fragment de code suivant montre une réponsetext
comportant des actions :{ "userId":"22343248763458761287 "messagePayload": { "type": "text", "text": "What do you want to do?", "actions": [ { "type": "postback", "label": "Order Pizza", "postback": { "state": "askAction", "action": "orderPizza" } }, { "type": "postback", "label": "Cancel A Previous Order", "postback": { "state": "askAction", "action": "cancelOrder" } ] } }
card
... { "type": "card", "layout": "horiztonal", "cards": [ { "title": "Hawaiian Pizza", "description": "Ham and pineapple on thin crust", "actions": [ { "type": "postback", "label": "Order Small", "postback": { "state": "GetOrder", "variables": { "pizzaType": "hawaiian", "pizzaCrust": "thin", "pizzaSize": "small" } } }, { "type": "postback", "label": "Order Large", "postback": { "state": "GetOrder", "variables": { "pizzaType": "hawaiian", "pizzaCrust": "thin", "pizzaSize": "large" } } } ] }, { "title": "Cheese Pizza", "description": "Cheese pizza (i.e. pizza with NO toppings) on thick crust", "actions": [ { "type": "postback", "label": "Order Small", "postback": { "state": "GetOrder", "variables": { "pizzaType": "cheese", "pizzaCrust": "thick", "pizzaSize": "small" } } }, { "type": "postback", "label": "Order Large", "postback": { "state": "GetOrder", "variables": { "pizzaType": "cheese", "pizzaCrust": "thick", "pizzaSize": "large" } } } ] } ], "globalActions": [ { "type": "call", "label": "Call for Help", "phoneNumber": "123456789" } ] }
attachment
Le type de réponse de la pièce jointe peut être une image, un fichier audio ou une vidéo : ... { "type": "attachment", "attachment": { "type": "video", "url": "https://www.youtube.com/watch?v=CMNry4PE93Y" } }