Oracle Cloud Infrastructureドキュメント

Webフック

使用するメッセージング・チャネルがOracle Digital Assistantでデフォルトでサポートされていない場合は、Webフックを使用してそのチャネルを手動で統合できます。

Webフック・チャネルを作成するには、次のものが必要です:

  • Webフックを使用してユーザー・デバイスとデジタル・アシスタント(またはスキル)の間でメッセージをリレーする、パブリックにアクセス可能なHTTPメッセージング・サーバー。

    次のものとともにこのWebフックを実装します:

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

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

  • デジタル・アシスタントのメッセージを受信するWebフック・コールのURI (メッセージの送信先をデジタル・アシスタントが認識するため)。

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

これらの要素をWebフックに組み入れるには:

  1. サーバーを設定します。

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

  3. 「チャネルの作成」ダイアログで名前を入力し、次に:

    • チャネル・タイプとして「Webフック」を選択します。

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

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

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


    create-webhook-channel.pngの説明が続きます
    図create-webhook-channel.pngの説明

  4. 「作成」をクリックします。

    デジタル・アシスタントは、デジタル・アシスタントのWebフックURLと、メッセージを暗号化するための秘密キーを生成します。WebフックURLは、メッセージング・サーバーがデジタル・アシスタントにメッセージを返送するために必要なポインタであるため、手元に用意しておいてください。
    webhook-channel-config.pngの説明が続きます
    図webhook-channel-config.pngの説明

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

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

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

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

Oracle Digital AssistantのNode.js SDKのWebhookClientライブラリにより、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_URLおよびBOT_WEBHOOK_SECRETはノード・サーバーで設定する環境変数です。これらの環境変数を使用すると、機密情報をWebフック内で直接ハードコーディングすることを回避できます

  2. userId、profileおよびmessagePayloadプロパティを含むJSONオブジェクト:
    {
 "userId": "33c0bcBc8e-378c-4496-bc2a-b2b9647de2317",
 "profile": {
    "firstName": "Bob",
    "lastName": "Franklin",
    "age": 45
   },
 "messagePayload": {....}
}
    プロパティ 説明 タイプ 必須?
    userId ユーザーの一意の識別子。このIDはコール元に固有です。 文字列 はい
    profile firstNameやLastNameなど、ユーザーを表すプロパティ。 JSONオブジェクト いいえ
    messagePayload messagePayloadには、text、postback、attachmentおよびlocationを指定できます。 JSONオブジェクト はい
    ノート

    スキルまたはデジタル・アシスタントでユーザー言語を検出する必要がある場合は、Webフック・メッセージでprofile.localeおよびprofile.languageTagがnullに設定されていることを確認してください。

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

メッセージ・タイプ ペイロードの例
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 SDKのWebhookClientライブラリにより、Webフック・チャネルでのメッセージの送信および受信の設定が簡単になります。SDKを使用していない場合は、アウトバウンド・メッセージの作成について理解しておく必要のあることを次に示します。

デジタル・アシスタントに必要なJSONフォーマットのコールを、認可ヘッダーとともに公開する必要があります。

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

    デジタル・アシスタントでは、X-Hub-Signatureヘッダーを使用して、受信者がデジタル・アシスタントを送信者として認証し、ペイロードの整合性を検証できるようにします。
  2. JSONペイロード(userID、インバウンド・メッセージによって指定された一意の識別子、type (text、attachmentおよび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 attachmentのレスポンス・タイプは、image、audio fileまたはvideoになります: 
    
...
{
  "type": "attachment",
  "attachment": {
    "type": "video",
    "url": "https://www.youtube.com/watch?v=CMNry4PE93Y"
  }
}