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.

Pour créer un canal de webhook, vous devez disposer des éléments suivants :
  • 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).

Pour assembler ces éléments dans un webhook, procédez comme suit :
  1. Configurez le serveur.

  2. Pour recevoir des messages de l'assistant numérique, publiez l'appel POST sur le serveur.

  3. 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'image create-webhook-channel.png
    Description de l'illustration create-webhook-channel.png
  4. 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
    Description de l'image webhook-channel-config.png

  5. Sur votre serveur, publiez la seconde API POST, qui envoie des messages à votre assistant numérique à l'aide de l'URL de webhook.

  6. 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 :

  1. 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 et BOT_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.

  2. Objet JSON comportant les propriétés userId, profile et messagePayload :
    {
     "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 et LastName. Objet JSON Non
    messagePayload La valeur messagePayload peut être text, postback, attachment ou location. Objet JSON Oui
    Remarque

    Si votre brique ou votre assistant numérique doit détecter la langue utilisateur, assurez-vous que profile.locale et profile.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
{
    "type": "text",
    "text": "hello, world!"
}
postback
{
  "type": "postback",
  "postback": {
    "state": "orderPizza",
    "action": "deliverPizza",
    "variables": {
      "pizzaSize": "Large",
      "pizzaCrust": "Thin",
      "pizzaType": "Hawaiian"
    }
  }
}
attachment
{
  "type": "attachment",
  "attachment": {
    "type": "image",
    "url": "https://image.freepik.com/free-icon/attachment-tool-ios-7-interface-symbol_318-35539.jpg"
  }
}
location
{
  "type": "location",
  "location": {
    "longitude": -122.265987,
    "latitude": 37.529818
  }
}

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.

L'appel destiné aux messages sortants de votre assistant numérique doit comporter les éléments suivants :
  1. 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ête X-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.
  2. Charge utile JSON comportant l'identificateur unique userID spécifié par le message entrant, à savoir type, qui peut prendre les valeurs text, attachment et card. Comme illustré dans les exemples suivants, les types de réponse text et card 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éponse text 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"
      }
    }