Webhook 構成

Web フックの詳細を追加するには、以下の手順を実行します。

1. ナビゲーション・パネルから Environmentsをクリックし、Webhookを設定する環境を開きます。

2. アイコンをクリックして、環境設定を開きます。

3. プリメッセージ Webhook スイッチを 有効に設定します。

4. Synchronous event（同期イベント ）で、以下のオプションから1つを選択する：

   • エラーが発生した場合は、Webhookを更新せずにユーザー入力の処理を続行します。

   • Webhookの呼び出しに失敗した場合、クライアントにエラーを返します。

   詳細については、「 前処理のためのウェブフック・エラー処理の設定 」を参照してください。

5. **「URL」**フィールドに、HTTP POST 要求コールアウトを送信する外部アプリケーションの URL を追加します。

   例えば、メッセージが英語以外の言語で書かれているかどうかをチェックし、それを英語に変換するために Language Translator サービスに送信する Cloud Functions ウェブ・アクションを書くことができる。 以下の例にあるように、Web アクションの URL を指定します。

   https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json
   

   SSL プロトコルを使用する URL を指定する必要があります。したがって、https で始まる URL を指定してください。

6. プレメッセージ Webhook の認証を設定するには、「 認証の編集 」をクリックします。 詳細な手順については、 プレメッセージとポストメッセージのウェブフックの認証方法を定義するを 参照してください。

7. Timeout フィールドで、アシスタントがエラーを返す前にWebhookからの応答を待つ時間を秒単位で指定します。 タイムアウト期間は、1 秒未満に短くすることも、30 秒超に長くすることもできません。

8. ヘッダーセクションで、 ヘッダーの追加をクリックし、サービスに渡したいヘッダーを1つずつ追加します。

   あなたが呼び出した外部アプリケーションが応答を返す場合、そのアプリケーションは異なるフォーマットで応答を送信できるかもしれない。 Webhook では、応答が JSON でフォーマットされている必要があります。 以下の表は、結果として返される値がJSON形式であることを示すヘッダーの追加方法を示している。

   ヘッダーの例

   ヘッダー名	ヘッダー値
   Content-Type	application/json

9. ヘッダー値を保存した後、文字列はアスタリスクに置き換えられ、再び表示することはできません。

10. Web フックの詳細は自動的に保存されます。

前処理のためのウェブフック・エラー処理の設定

ウェブフック・コールが失敗した場合、前処理ステップでエラーを返すかどうかを決めることができます。 次の 2 つのオプションがあります。

• エラーが発生した場合、Webhook を更新せずにユーザー入力の処理を続行します。アシスタントはエラーを無視し、Webhook の結果なしでメッセージを処理します。 前処理が有用だが必須ではない場合は、このオプションを検討する。

• Webhook 呼び出しが失敗した場合、クライアントにエラーを返します ：アシスタントがメッセージを処理する前に前処理が重要な場合は、このオプションを選択します。

ウェブフック呼び出しが失敗した場合、クライアントにエラーを返すを有効にすると、前処理ステップが正常に完了するまで、すべてが停止します。

定期的に外部プロセスをテストし、潜在的な障害を特定する。 必要に応じてこの設定を調整し、メッセージ処理の中断を防いでください。

Webhook のテスト

本番環境で使用されるアシスタントのためにそれを有効にする前に、Webhookの広範なテストを行ってください。

Webhook は、メッセージがアシスタントに送信されて処理されるときにトリガーされます。

Webhook のトラブルシューティング

以下のエラー・コードは、発生する可能性がある問題の原因を追跡するのに役立ちます。 たとえば、ウェブチャットとの統合がある場合、送信したテストメッセージがすべて There is an error with the message you just sent, but feel free to ask me something else のようなメッセージを返すと、ウェブフックに問題があることがわかります。 このメッセージが表示された場合は、 cURL, などの REST API ツールを使用してテスト用の /message API リクエストを送信し、エラーコードと返されるメッセージの全文を確認してください。

要求本文の例

外部コードが処理できるように、プレメッセージWebhookのリクエストボディのフォーマットを知っておくと便利です。

ペイロードは、 /message、ステートフルまたはステートレス、APIリクエストのバージョン2のリクエストボディを含む。 イベント名 message_received は、リクエストがプレメッセージウェブフックによって生成されたことを示す。 メッセージ・リクエスト・ボディの詳細については、 APIリファレンスを参照のこと。

{
  "payload" : { Copy of request body sent to /message }
  "event": {
      "name": "message_received"
   }
}

アシスタント処理のスキップ

プレメッセージWebhookの機能強化により、 Cloud Pak for Data、メッセージ処理をスキップし、Webhookからのレスポンスを直接返すことができるようになりました。 この機能は、ウェブフックの HTTP レスポンスに x-watson-assistant-webhook-return ヘッダーを設定することで有効になります。

応答本体

Webhook から POST 要求を受け取るサービスは、JSON オブジェクト (Accept: application/json) を返す必要があります。

応答本体には、以下の構造が必要です。

{
  "payload": {
    ...
  }
}

レスポンス payload 、リクエストボディの payload。 あなたのコードは、プロパティ値を変更したり、コンテキスト変数を変更したりできますが、返されるメッセージのペイロードは、 message メソッドのスキーマに従わなければなりません。 詳細は APIリファレンスを 参照。

例 1

この例では、入力テキストの言語をチェックし、その言語情報を入力テキスト文字列に追加する方法を示します。

プレメッセージWebhook設定ページでは、以下の値を指定します：

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language
• ヘッダー名: Content-Type
• ヘッダー値: application/json

プレメッセージ Webhook は IBM Cloud Functions Web アクション名 check_language を呼び出します。

check_language Web アクションの node.js コードは以下のようになります。

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
  // Send a request to the Watson Language Translator service to check the language of the input text.
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        //Append "in" plus "the language code" to the input text, surrounded by parentheses.
        const response = {
            body : {
                payload : {
                    input : {
                        text : params.payload.input.text + ' ' + '(in ' + res.languages[0].language + ')'
                    },
                },
            },
        };
        return response;
})
}
return {
    body : params
}
};

Webhook をテストするには、プレビューをクリックします。 Buenos días を送信してください。 アシスタントはおそらく入力を理解できず、 Anything else ノードからの応答を返します。 しかし、アシスタントの「分析」ページで 「会話」を開くと、投稿された内容を見ることができます。 最新のユーザー会話を確認します。 ログによると、ユーザー入力は Buenos días (in es)。 括弧内の es はスペイン語の言語コードを表しているため、ウェブフックは機能し、送信されたテキストがスペイン語のフレーズであることを認識した。

例 2

この例では、受信メッセージの言語をチェックし、英語でなければアシスタントに送信する前に英語に翻訳する方法を示しています。

IBM Cloud Functions で Web アクションのシーケンスを定義します。 シーケンス内の最初のアクションは、着信テキストの言語を検査します。 シーケンス内の 2 番目のアクションは、テキストを元の言語から英語に変換します。

プレメッセージWebhook設定ページでは、以下の値を指定します：

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence
• ヘッダー名: Content-Type
• ヘッダー値: application/json

シーケンス内の最初の Web アクションの node.js コードは、以下のようになります。

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
      //Set the language property of the incoming message to the language that was identified by Watson Language Translator.
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        return params;
})
}
else {
    params.payload.context.skills["actions skill"].user_defined["language"] = 'none'
    return params
}
};

シーケンス内の 2 番目の Web アクションは、テキストを Watson Language Translator サービスに送信して、前の Web アクションで識別された言語からの入力テキストを英語に変換します。 翻訳されたストリングは、元のテキストではなく、アシスタントに送信されます。

シーケンス内の 2 番目のアクションの node.js コードは、以下のようになります。

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
//If the the incoming message is not null and is not English, translate it.
if ((params.payload.context.skills["actions skill"].user_defined.language !== 'en') && (params.payload.context.skills["actions skill"].user_defined.language !== 'none')) {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/translate?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
  headers: {
    "Content-Type":"application/json"
  },
       //The body includes the parameters that are required by the Language Translator service, the text to translate and the target language to translate it into.
  body: {
      text: [
          params.payload.input.text
          ],
          target: 'en'
  },
  json: true
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["original_input"] = params.payload.input.text;
        const response = {
            body : {
                payload : {
                    "context" : params.payload.context,
                    "input" : {
                        "text" : res.translations[0].translation,
                        "options" : {
                            "export" : true
                            }
                    },
                },
            },
        };
    return response
})
}
return {
    body : params
    }
};

プレビュー・パネルで Webhook をテストすると、Buenos días を実行依頼できます。アシスタントは、Good morning と英語で応答した場合と同様に応答します。 実際、アシスタントの分析ページをチェックし、 会話を開くと、ログにはユーザーの入力が Good morning。

あなたは、メッセージの応答が表示される前に顧客の言語に翻訳し直すために、メッセージ後のWebhookを追加することができます。 詳しくは 例2を 参照。

例 3

この例では、 Cloud Pak for Data にメッセージの処理を省略させ、webhook のレスポンスを直接返すように webhook レスポンスを構成する方法を示します。

function main(params) {
  // Your custom logic to determine the response
  let responseText = "This response is directly from the pre-message webhook.";

  const response = {
    headers: {
      "X-Watson-Assistant-Webhook-Return": "true"
    },
    body: {
      output: {
        generic: [
          {
            response_type: "text",
            text: responseText
          }
        ]
      }
    }
  };

  return response;
}

Webhook の削除

Webhookで顧客の入力を前処理したくない場合は、次の手順を実行します：

1. アシスタントの Environmentsで、Webhookを削除したい環境を開いてください。

2. アイコンをクリックして、環境設定を開きます。

3. 環境設定ページで、 プリメッセージ・ウェブフックをクリックします。

4. 以下のいずれかのステップを実行します。

• 受信メッセージを処理するために Webhook を呼び出すのを止めるには、 Pre-message Webhook スイッチを Disabled に設定します。

• 呼び出す Webhook を変更するには、 Delete webhook をクリックします。