手順

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

1. アシスタントで、 「環境」 に移動し、Webhook を構成する環境を開きます。

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

3. 環境設定ページで、 ポストメッセージWebhookをクリックします。

   クラシックを体験するには、以下のステップを完了する：

   • 設定したいアシスタントの「 クリックし、「 Settings 」を選択します。

   • Webhooks > Post-message webhook をクリックします。

4. ポストメッセージ Webhook スイッチを 有効に設定します。

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

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

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

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

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

   例えば、アシスタントの応答を別のコンテンツ管理システムに保管するとします。 アシスタントが入力を理解すると、処理されたアクションは、CMS 内の応答に対応する固有 ID を返します。 特定の固有 ID について CMS から応答を取得するサービスを呼び出すには、サービス・インスタンスの URL を指定します。 例えば、https://example.com/get_answer です。

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

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

   • クラシックを体験するには、 シークレットの欄に記入してください。 詳細については、 クラシック体験のみの秘密の追加を ご覧ください。

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

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

   Classicエクスペリエンスでは、サービスは自動的にJWT付きのAuthorizationヘッダーを送信する。 認可を自分で処理したい場合は、独自の認可ヘッダーを追加し、サービスがそれを代わりに使用する。

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

   ヘッダーの例

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

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

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

Webhook のテスト

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

Webhookは、アシスタントがメッセージを処理し、チャネルにレスポンスを返す準備ができたときにのみトリガーされます。

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

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

ClassicエクスペリエンスのみのWebhookセキュリティ

Classicエクスペリエンスでは、リクエストとともに送信されるJSON Web Token（JWT）を検証することで、Webhookリクエストを認証します。 ウェブフック・マイクロサービスは自動的にJWTを生成し、各ウェブフック・コールで Authorization ヘッダーにそれを送信する：

• 新しい Webhook または Edit 認証で更新された Webhook の場合、authorization ヘッダーは無視されます。

• 認証ヘッダーが保存されている既存の Webhook の場合、[ 認証の編集 ] ボタンは無効になります。

• 新しい認証設定を使用するように既存のWebhookを更新すると、その動作が変更されます。

JWT検証をテストする必要がある場合は、外部サービスにコードを追加できます。 例えば、 Secret フィールドに purple unicorn ：

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
  // error thrown if token is invalid
}

要求本文の例

リクエスト・ポストメッセージのウェブフック・ボディのフォーマットを知っておくと、外部コードがそれを処理できるので便利です。

ペイロードには、v2 /message（ステートフルおよびステートレス）APIコールに対してアシスタントが返すレスポンスボディが含まれます。 イベント名 message_processed は、ポストメッセージWebhookがリクエストを生成することを示す。 メッセージ要求本体について詳しくは、 API リファレンスを参照してください。

次のサンプルは、単純なリクエストボディがどのようにフォーマットされるかを示しています：

{
 "event": {
    "name": "message_processed"
},
"options": {},
"payload": {
    "output": {
        "intents": [
            {
                "intent": "General_Greetings",
                "confidence": 1
            }
        ],
        "entities": [],
        "generic": [
            {
                "response_type": "text",
                "text": "Hello. Good evening"
            }
        ]
    },
    "user_id": "test user",
    "context": {
        "global": {
            "system": {
                "user_id": "test user",
                "turn_count": 11
            },
            "session_id": "sxxx"
        },
        "skills": {
            "actions skill": {
                "user_defined": {
                    "var": "anthony"
                },
                "system": {
                    "state": "nnn"
                }
            }
        }
    }
}

補助処理を省略する

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

{
    "output": {
      "generic": [
        {
          "response_type": "text",
          "text": "This response is directly from the pre-message webhook."
        }
      ]
    }
}

例 1

この例では、アシスタントからの各レスポンスの最後に y'all を追加する方法を示しています。

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

クラシック経験者にとって、 シークレットフィールドに価値はない。

• URL: https://your-webhook-url/
• ヘッダー名: Content-Type
• ヘッダー値: application/json

ポストメッセージ Webhook は IBM Cloud Functions Web アクション名 add_southern_charm を呼び出します。

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

function main(params) {
  console.log(JSON.stringify(params))
  if (params.payload.output.generic[0].text !== '') {
      //Get the length of the input text
        var length = params.payload.output.generic[0].text.length;
        //create a substring that removes the last character from the input string, which is typically punctuation.
        var revision = params.payload.output.generic[0].text.substring(0,length-1);
        const response = {
            body : {
                payload : {
                    output : {
                        generic : [
                              {
                                  //Replace the input text with your shortened revision and append y'all to it.
                                "response_type": "text",
                                "text": revision + ', ' + 'y\'all.'
                              }
                        ],
                    },
                },
            },
        };
        return response;
  }
  else {
    return {
        body : params
    }
  }
}

例 2

この例では、メッセージ応答を顧客の言語に翻訳する方法を示します。 これは、 例2の ステップを実行し、オリジナルのメッセージを英語に翻訳するプレメッセージWebhookを定義した場合にのみ機能します。

IBM Cloud Functions で Web アクションのシーケンスを定義します。 この変数は、プレメッセージのウェブフック・コードの original_input というコンテキスト変数に格納されています。 シーケンス内の 2 番目のアクションは、ダイアログ応答テキストを英語から顧客が使用した元の言語に変換します。

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

クラシック経験者にとって、 シークレットフィールドに価値はない。

• URL: https://your-webhook-url/
• ヘッダー名: Content-Type
• ヘッダー値: application/json

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

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

function main(params) {
console.log(JSON.stringify(params))

if (params.payload.output.generic[0].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': 'nnnn'
       },
  headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.context.skills['actions skill'].user_defined.original_input
  ],
  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 param
}
};

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

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

function main(params) {
  console.log(JSON.stringify(params))
    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'
        },
    body: {
        text: [
            params.payload.output.generic[0].text
            ],
            target: params.payload.context.skills["actions skill"].user_defined.language
    },
    json: true
    };
      return rp(options)
      .then(res => {
          params.payload.context.skills["actions skill"].user_defined["original_output"] = params.payload.output.generic[0].text;
          params.payload.output.generic[0].text = res.translations[0].translation;
          return {
            body : params
          }
  })
  }
  return {
    body : params
  }
};

例 3

この例では、 watsonx Assistant にメッセージの処理を省略させ、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. アシスタントで 「環境」 に移動し、ウェブフックを削除したい環境を開きます。

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

3. 環境設定ページで、 ポストメッセージWebhookをクリックします。

   クラシックを体験するには、以下のステップを完了する：

   • 設定したいアシスタントの「 クリックし、「 Settings 」を選択します。

   • Webhooks > Post-message webhook をクリックします。

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

• すべての受信メッセージを処理するためにウェブフックを呼び出すのを停止するには、 ポストメッセージウェブフックスイッチ を無効に設定します。

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