Oracle Cloud Infrastructureドキュメント

Webフック

チャネル・サービスまたはメッセージ・サービスがデフォルトでサポートされていない場合は、HTTP webフック・チャネルを使用してOracle Digital Assistantを手動で統合できます。

webフック・チャネルを作成するには、次のものが必要です:
  • webフックを使用してユーザー・デバイスとデジタル・アシスタント(またはスキル)間でメッセージをリレーする、パブリックからアクセス可能なHTTPメッセージング・サーバー。

    このwebフックを実装しました:

    • サーバーがデジタル・アシスタントからメッセージを受信できるようにするPOSTコール。

    • サーバーからデジタル・アシスタントにメッセージを送信できるようにするPOSTコール。

  • デジタル・アシスタントのメッセージを受信するwebフック・コールのURI (デジタル・アシスタントはメッセージの送信場所を認識します)。

  • 「チャネルの作成」ダイアログ・ボックスを完了した後にデジタル・アシスタント用に生成されるWebフックURL (メッセージ・サーバーがデジタル・アシスタントにアクセスできるようにするため)。

これらの要素をwebフックに組み入れるには:
  1. サーバーを設定します。

  2. デジタル・アシスタントからメッセージを受信するには、サーバーでPOSTコールを公開します。

  3. 「チャネルの作成」ダイアログで名前を入力し、次を行います:
    • チャネル・タイプとしてWebフックを選択します。

    • プラットフォーム・バージョンを1.1 (会話モデル)に設定します。

    • 「発信Webhook URI」フィールドにこのPOSTコールのURIを入力して、デジタル・アシスタントのメッセージの受信者としてサーバーを登録します。

    • 必要に応じて、セッション失効を入力し、チャネル有効をオンに切り替えます。


    create_webhook_channel.pngの説明が続きます
    「図create_webhook_channel.pngの説明」
  4. 「作成」(コールバック)をクリックします。

    Digital Assistantでは、デジタル・アシスタントのwebフックURLと、メッセージを暗号化するための秘密キーが生成されます。 メッセージをデジタル・アシスタントに送信して戻す必要があるポインタのため、webフックのURLはそのままにしてください。
    webhook_channel_config.pngの説明が続きます
    「図webhook_channel_config.pngの説明」

  5. サーバーで、2番目のPOST APIを公開します。1つはwebフックURLを使用してデジタル・アシスタントにメッセージを送信します。

  6. チャネル有効オプションを切り替えます。

Digital Assistant Node.js SDKを使用して、デジタル・アシスタントとの間でメッセージの送信を設定できます。

ビデオ: チャネルの概要

webフックの詳細を表示するには、このビデオをチェックアウトします。

インバウンド・メッセージ

Oracle Digital Assistant Node.js SDKWebhookClientライブラリにより、Webフック・チャネルでのメッセージの送信と受信の設定が簡素化されます。 SDKを使用していない場合、インバウンド・メッセージの作成について理解しておく必要があります。

デジタル・アシスタント(またはスキル)にメッセージを送信するコールには、次のものが必要です:

  1. ペイロードのSHA256値を含むX-Hub-Signatureヘッダー。 このコールには、秘密キーをキーとして使用してこのハッシュを作成する関数が含まれています。
    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_URLBOT_WEBHOOK_SECRETは、ノード・サーバーで設定した環境変数です。 これらの環境変数を使用すると、Webフックで機密情報を直接ハード・コーディングする必要がなくなります。

  2. userIduserProfileおよびmessagePayloadプロパティを持つJSONオブジェクトは、次のとおりです:
    {
     "userId: "33c0bcBc8e-378c-4496-bc2a-b2b9647de2317"
     "userProfile": {
        "firstName": "Bob",
        "lastName": "Franklin",
        "age": 45
       },
     "messagePayload: {....}
    }
    プロパティ 説明 タイプ 必須?
    userId ユーザーの一意の識別子。 このIDはコール元に固有です。 文字列 はい
    userProfile firstNameLastNameなど、ユーザーを表すプロパティ。 JSONオブジェクト いいえ
    messagePayload messagePayloadは、textpostbackattachmentおよびlocationを使用できます。 JSONオブジェクト はい

ペイロードの例: インバウンド・メッセージ

メッセージ・タイプ ペイロードの例
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
  }
}

アウトバウンド・メッセージ

Oracle Digital Assistant Node.js SDKWebhookClientライブラリにより、Webフック・チャネルでのメッセージの送信と受信の設定が簡素化されます。 SDKを使用していない場合、アウトバウンド・メッセージの作成について理解しておく必要があります。

Digital Assistantが予期するJSON形式のコールを、承認ヘッダーとともに公開する必要があります。

デジタル・アシスタントのアウトバウンド・メッセージをコールする方法は、次のとおりです:
  1. ペイロードのSHA256値を含むX-Hub-Signatureヘッダー。秘密キーをキーとして使用して計算されます。
    ノート

    Digital Assistantでは、X-Hub-Signatureヘッダーを使用して、受信者がデジタル・アシスタントを送信者として認証し、ペイロードの整合性を検証できます。
  2. インバウンド・メッセージ、typeで指定される一意の識別子であるuserIDを含むJSONペイロードで、textattachmentおよびcardがあります。 次の例に示すように、textおよびcardの両方のレスポンス・タイプにアクションを関連付けることができます。 いずれのレスポンス・タイプにも、グローバル・アクションを含めることができます。
    レスポンス・タイプ ペイロードの例
    text
    {
     "userId":"22343248763458761287
     "messagePayload": {
        "type": "text",
        "text": "Hello, how are you?"
         }
    }
    次のスニペットは、textレスポンスとアクションを示しています:
    {
     "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 アタッチメント・レスポンス・タイプには、イメージ、オーディオ・ファイルまたはビデオがあります:
    
    ...
    {
      "type": "attachment",
      "attachment": {
        "type": "video",
        "url": "https://www.youtube.com/watch?v=CMNry4PE93Y"
      }
    }