ウェブフックによるアクティビティのログ

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

Webhookは、プログラム内のイベントに基づいて外部プログラムに呼び出すために使用できるメカニズムです。

この機能はPlusプランとEnterpriseプランのユーザーだけが利用できます。 Plusプランでは、1インスタンスあたり5ログウェブフックまでしか許可されません。 この制限はエンタープライズプランのインスタンスには適用されません。

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

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

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

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

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

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

Web フックの定義

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

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

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

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

  1. アシスタントで、Webhookを設定したい環境を開きます。

  2. 環境設定アイコンアイコンをクリックして環境設定を開く。

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

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

    2. Webhooksをクリックし、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. アシスタントのEnvironmentsに移動し、Webhookを設定したい環境を開きます。

  2. 環境設定アイコンアイコンをクリックして環境設定を開く。

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

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

    2. Webhooksをクリックし、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ログイベントリファレンスを参照してください。