Webフック

機械翻訳について

53 Webフック

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

Webhookチャネルを作成するには、次の手順が必要です:

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

次のものとともにこのWebフックを実装します。
- サーバーがデジタル・アシスタントからメッセージを受信できるようにするPOSTコール。
- サーバーからデジタル・アシスタントにメッセージを送信できるようにするPOSTコール。
デジタル・アシスタントのメッセージを受信するwebフック・コールのURI (デジタル・アシスタントはメッセージの送信場所を認識します)。
「チャネルの作成」ダイアログ・ボックスを完了した後にデジタル・アシスタント用に生成されるWebフックURL (メッセージ・サーバーがデジタル・アシスタントにアクセスできるようにするため)。

これらの情報を使用して1つのWebフックを構築するには:

サーバーを設定します。
デジタル・アシスタントからメッセージを受信するには、サーバーでPOSTコールを公開します。
チャネルの作成ダイアログに名前を入力して、次の操作を実行します。
- チャネル・タイプとしてWebフックを選択します。
- プラットフォーム・バージョンを1.1 (会話モデル)に設定します。
- 「発信Webhook URI」フィールドにこのPOSTコールのURIを入力して、デジタル・アシスタントのメッセージの受信者としてサーバーを登録します。
- 必要に応じて、セッションの有効期限を入力して、チャネルが有効をオンに切り替えます。
「図create-webhook-channel.pngの説明」
「作成」をクリックします。

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

「図webhook-channel-config.pngの説明」
サーバーで、2番目のPOST APIを公開します。1つはwebフックURLを使用してデジタル・アシスタントにメッセージを送信します。
チャネルが有効オプションをオンに切り替えます。

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

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

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

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

X-Hub-Signatureヘッダー(ペイロードのSHA256の値を含む)。この呼出しには、秘密キーをそのキーとして使用してこのハッシュを作成する関数を含めます。

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フックで機密情報を直接ハード・コーディングする必要がなくなります。

userId、profile、およびmessagePayloadプロパティを持つJSONオブジェクト:

{
 "userId": "33c0bcBc8e-378c-4496-bc2a-b2b9647de2317",
 "profile": {
    "firstName": "Bob",
    "lastName": "Franklin",
    "age": 45
   },
 "messagePayload": {....}
}

プロパティ	説明	タイプ	必須かどうか
`userId`	ユーザーの一意の識別子。このIDは呼出し元に固有です。	String	はい
`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を使用していない場合、アウトバウンド・メッセージの作成について理解しておく必要があります。

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

デジタル・アシスタントのアウトバウンド・メッセージをコールする方法は、次のとおりです:

X-Hub-Signatureヘッダー(秘密キーをそのキーとして使用して計算されるペイロードのSHA256の値を含む)。

ノート:
Digital Assistantでは、X-Hub-Signatureヘッダーを使用して、受信者がデジタル・アシスタントを送信者として認証し、ペイロードの整合性を検証できます。

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" } }`

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"
  }
}