IBM Cloud Docs
Webhook を使用したアクティビティーのロギング

Webhook を使用したアクティビティーのロギング

プラス

顧客がアシスタントに入力を送信するたびに外部サービスまたはアプリケーションへの呼び出しを行うことにより、アクティビティーをログに記録できます。

ウェブフックとは、プログラム内のイベントに基づいて外部プログラムを呼び出すために使用できる仕組みです。

この機能は、PlusプランおよびEnterpriseプランのユーザーのみご利用いただけます。 プラス・プランでは、インスタンスごとに許可されるログ Webhook は 5 個までです。 この制限は、エンタープライズ・プラン・インスタンスには適用されません。

外部サービスを使用してアクティビティをログに記録したい場合は、ログウェブフックをアシスタントに追加します。 以下の 2 種類のアクティビティーをログに記録できます。

  • メッセージと応答 : アシスタントが顧客の入力に対して応答するたびに、ログウェブフックがトリガーされます。 このオプションは、ロギングを自分で処理するための組み込み分析機能の代わりに使用できます。 (組み込み分析サポートについて詳しくは、アシスタント全体を一目で確認を参照してください。)

    カスタムチャンネルを使用している場合は、ログウェブフックv2の /message APIのみ(ステートレスおよびステートフル)で動作します。 詳細は、 APIリファレンスを参照してください。 すべての組み込みチャネル統合で、この API が使用されます。

  • 通話明細記録(CDR): 電話統合を使用するユーザーがアシスタントに電話をかけるたびに、ログウェブフックが起動します。 発着信詳細記録 (CDR) は、通話の詳細 (電話番号、通話の長さ、待ち時間、その他の診断情報を含む) を記録する要約レポートです。 CDRレコードは、電話統合を使用するアシスタントのみに適用されます。

ログ Webhook はアシスタントに何も返しません。

プライベート・エンドポイントが使用されている環境では、Web フックがトラフィックをインターネット経由で送信することに留意してください。

Web フックの定義

すべての着信メッセージまたは CDR イベントのロギングに使用する Webhook URL を 1 つ定義できます。

外部サービスへのプログラマチック呼び出しは、以下の要件を満たす必要があります。

  • 呼び出しは POST HTTP 要求であること。

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

  1. アシスタントで、Web フックを構成したい環境を開きます。

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

  3. 環境設定ページで、 ウェブフックを記録をクリックします。

    1. または、クラシック・エクスペリエンスを使用している場合は、 「アシスタント (Assistants)」 ページを開きます。

    2. 構成するアシスタントの 「オーバーフロー・メニュー」 アイコンをクリックし、 「設定」 を選択します。

    3. 「Webhook」 をクリックしてから、 「Webhook をログに記録 (Log webhook)」 をクリックします。

  4. ログ Webhook スイッチを「有効」に設定します。

    Webhook を有効にできない場合は、サービス・プランのアップグレードが必要になることがあります。

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

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

  6. シークレット」フィールドに、外部サービスでの認証に使用できる要求で渡すトークンを追加します。

    シークレットは、purple unicorn などのテキスト・ストリングとして指定する必要があります。 最大長は 1,024 文字です。 コンテキスト変数を指定することはできません。

    シークレットを確認して検証するのは、外部サービスの責任です。 外部サービスがトークンを必要としない場合は、任意の文字列を指定します。 このフィールドを空のままにすることはできません。

    入力時にシークレットを表示するには、入力を開始する前に 「パスワードの表示」 アイコン ビュー・アイコン をクリックします。 シークレットを保存すると、ストリングはアスタリスクに置き換えられ、再度表示することはできません。

  7. 該当するチェック・ボックスをクリックして、ログに記録するアクティビティーの種類を選択します。

    • メッセージと応答をログに記録するには、会話ログのサブスクライブを選択します。
    • 電話統合の CDR イベントをログに記録するには、CDR (発着信詳細記録) のサブスクライブを選択します。
  8. 「ヘッダー」セクションで、**「ヘッダーの追加 (Add header)」**をクリックし、サービスに渡すヘッダーを 1 つずつ追加します。

    サービスは JWT 付きの Authorization ヘッダーを自動的に送信します。追加する必要はありません。 認証を独自に処理したい場合は、独自の認証ヘッダーを追加すると、そのヘッダーが代わりに使用されます。

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

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

Webhook の削除

Webhook でメッセージをログに記録しないことにした場合は、以下の手順を実行します。

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

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

  3. 環境設定ページで、 ウェブフックを記録をクリックします。

    1. または、クラシック・エクスペリエンスを使用している場合は、 「アシスタント (Assistants)」 ページを開きます。

    2. 構成するアシスタントの 「オーバーフロー・メニュー」 アイコンをクリックし、 「設定」 を選択します。

    3. 「Webhook」 をクリックしてから、 「Webhook をログに記録 (Log webhook)」 をクリックします。

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

    • 呼び出す Webhook を変更するには、Webhook の削除 をクリックして、現在指定されている URL と秘密を削除します。 次に URL やその他の詳細情報を追加できます。
    • すべてのメッセージと応答をログに記録するために Webhook の呼び出しを停止するには、ログ Webhook スイッチをクリックして、Webhook を完全に無効にします。

Webhook セキュリティー

Webhook 要求を認証するには、要求とともに送信される JSON Web トークン (JWT) を確認します。 Webhook マイクロサービスは、自動的に JWT を生成し、各 Webhook 呼び出しとともに Authorization ヘッダーで送信します。 JWT を検証する外部サービスにコードを追加するのはユーザーの責任です。

例えば、 「シークレット」 フィールドに 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
}

Webhook 要求本文

ウェブフックが外部サービスに送信するリクエストボディは、以下の構造のJSONオブジェクトです

{
  "event": {
    "name": "{event_type}"
   },
  "payload": {
    ...
  }
}

ここで、{event_type}message_logged (メッセージおよび応答の場合) または cdr_logged (CDR イベントの場合) のいずれかです。

payload オブジェクトには、ログに記録されるイベント・データが含まれます。 payload オブジェクトの構造は、イベントのタイプによって異なります。

メッセージ・イベント・ペイロード

message_logged イベントの場合、 payload オブジェクトには、アシスタントに送信されたメッセージリクエストと、統合またはクライアントアプリケーションに返されたメッセージレスポンスに関するデータが含まれます。 メッセージ要求および応答の一部であるフィールドについて詳しくは、API リファレンスを参照してください。

ログ Webhook ペイロードには、API で現在サポートされていないデータが含まれていることがあります。 API リファレンス資料で定義されていないフィールドは、変更される可能性があります。

CDR イベント・ペイロード

cdr_logged イベントの場合、payload オブジェクトには、電話統合によって処理された発着信詳細記録 (CDR) イベントに関するデータが含まれます。 CDR イベントの payload オブジェクトの構造は、次の例のようになります。

{
  "primary_phone_number": "+18005550123",
  "global_session_id": "9caa8bad-aaa8-4a5a-a4b5-62bccc703d15",
  "failure_occurred": false,
  "transfer_occurred": false,
  "active_calls": 0,
  "warnings_and_errors": [
    {
      "code": "CWSMR0033W",
      "message": "CWSMR0033W: The inbound RTP audio stream jitter of 43 ms exceeds the maximum jitter threshold of 30 ms."
    },
    {
      "code": "CWSMR0070W",
      "message": "CWSMR0070W: A request to the Watson Speech To Text service failed for the following reason = Unexpected server response: 403, response headers = {\"strict-transport-security\":\"max-age=31536000; includeSubDomains;\",\"content-length\":\"157\",\"content-type\":\"application/json\",\"x-dp-watson-tran-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-request-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-global-transaction-id\":\"6c764df3-81db-41bb-a14f-62384facffca\",\"server\":\"watson-gateway\",\"x-edgeconnect-midmile-rtt\":\"1\",\"x-edgeconnect-origin-mex-latency\":\"28\",\"date\":\"Thu, 13 May 2021 20:31:12 GMT\",\"connection\":\"keep-alive\"}, response body = {\"code\":403,\"trace\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"error\":\"Forbidden\",\"more_info\":\"[https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error](https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error)\"}, x-global-transaction-id = 6c764df3-81db-41bb-a14f-62384facffca. The Media Relay will reattempt to send the request."
    }
  ],
  "realtime_transport_network_summary": {
    "inbound_stream": {
      "average_jitter": 4,
      "canonical_name": "b74f3689-1ae8-4a0a-bde3-adf5b488553e",
      "maximum_jitter": 18,
      "packets_lost": 0,
      "packets_transmitted": 952,
      "tool_name": ""
    },
    "outbound_stream": {
      "average_jitter": 0,
      "canonical_name": "voice.gateway",
      "maximum_jitter": 0,
      "packets_lost": 0,
      "packets_transmitted": 838,
      "tool_name": "IBM Voice Gateway/1.0.7.0"
    }
  },
  "call": {
    "start_timestamp": "2021-10-12T20:54:02.591Z",
    "stop_timestamp": "2021-10-12T20:54:20.375Z",
    "milliseconds_elapsed": 17784,
    "outbound": false,
    "end_reason": "assistant_hangup",
    "security": {
      "media_encrypted": false,
      "signaling_encrypted": false,
      "sip_authenticated": false
    }
  },
  "session_initiation_protocol": {
    "invite_arrival_time": "2021-10-12T20:54:00.565Z",
    "setup_milliseconds": 2026,
    "headers": {
      "call_id": "17465345_115257202@10.90.150.99",
      "from_uri": "sip:+18885550456@pstn.twilio.com",
      "to_uri": "sip:+18005550123@public.voip.us-south.assistant.test.watson.cloud.ibm.com"
    }
  },
  "max_response_milliseconds": {
    "assistant": 339,
    "text_to_speech": 535,
    "speech_to_text": 0
  },
  "assistant_interaction_summaries": [
    {
      "session_id": "7874ec3a-1330-4180-afe1-46bfb220af5b",
      "assistant_id": "97f16ba4-ad94-41af-aa6c-33cd56ad5e7e",
      "turns": [
        {
          "assistant": {
            "log_id": "58bebfd1-0118-419b-a555-b152a1efbbe8",
            "response_milliseconds": 339,
            "start_timestamp": "2021-10-12T20:54:00.722Z"
          },
          "request": {
            "type": "start"
          },
          "response": [
            {
              "barge_in_occurred": true,
              "streaming_statistics": {
                "response_milliseconds": 301,
                "start_timestamp": "2021-10-12T20:54:00.722Z",
                "stop_timestamp": "2021-10-12T20:54:01.023Z",
                "transaction_id": "3dce431c-fb2f-4b62-9fce-585f4e06fe00"
              },
              "type": "text_to_speech"
            }
          ]
        },
        {
          "assistant": {
            "log_id": "38f36bfb-c2aa-4600-9418-6ab422664e31",
            "response_milliseconds": 158,
            "start_timestamp": "2021-10-12T20:54:05.621Z"
          },
          "request": {
            "type": "dtmf"
          },
          "response": [
            {
              "type": "disable_speech_barge_in"
            },
            {
              "type": "text_to_speech",
              "barge_in_occurred": false,
              "streaming_statistics": {
                "transaction_id": "af4c47c3-5cc4-43c8-9b9c-81d6f997c52f",
                "start_timestamp": "2021-10-12T20:54:06.321Z",
                "stop_timestamp": "2021-10-12T20:54:14.338Z",
                "response_milliseconds": 535
              }
            },
            {
              "type": "enable_speech_barge_in"
            },
            {
              "type": "text_to_speech",
              "barge_in_occurred": true,
              "streaming_statistics": {
                "transaction_id": "eafdd846-2829-4e1a-8068-b1035510b1e1",
                "start_timestamp": "2021-10-12T20:54:14.795Z",
                "stop_timestamp": "2021-10-12T20:54:20.388Z",
                "response_milliseconds": 447
              }
            }
          ]
        },
        {
          "assistant": {
            "log_id": "07d74b35-0205-43e4-923c-1e43e1cb429c",
            "response_milliseconds": 0,
            "start_timestamp": "2021-10-12T20:54:20.377Z"
          },
          "request": {
            "type": "hangup"
          },
          "response": []
        }
      ]
    }
  ]
}

CDRイベントペイロードの構造についての詳細は 、CDRログイベントリファレンス を参照してください。