使用 Webhook 記載活動

加強版

每次客戶將輸入提交給助理時，您都可以透過呼叫外部服務或應用程式來記載活動。

webhook 是一種機制，您可以使用它來根據程式中的事件呼叫外部程式。

此功能僅適用於 Plus 和 Enterprise 計劃使用者。 Plus 方案容許每個實例不超過 5 個日誌 Webhook。 此限制不適用於企業方案實例。

如果您想要使用外部服務來記載活動，請將日誌 Webhook 新增至助理。 您可以記載兩種活動:

  • 訊息及回應: 每當助理回應客戶輸入時，即會觸發日誌 Webhook。 您可以使用此選項作為內建分析功能的替代方案，自行處理記載。 (如需內建分析支援的相關資訊，請參閱 快速檢閱整個助理。)

    如果您使用自訂通道，則日誌 Webhook 只會使用 v2 /message API (無狀態及有狀態)。 如需詳細資訊，請參閱 API 參考資料。 所有內建通道整合都使用此 API。

  • 通話詳細記錄 (CDR): 在使用者對使用電話整合的助理進行每一次電話通話之後，即會觸發日誌 Webhook。 「通話詳細記錄 (CDR)」是一份摘要報告，其中記載電話通話的詳細資料，包括電話號碼、通話長度、延遲及其他診斷資訊。 CDR 記錄僅適用於使用電話整合的助理。

日誌 Webhook 不會傳回任何內容給您的助理。

對於使用私人端點的環境，請記住 webhook 會透過網際網路傳送流量。

定義 Webhook

您可以定義一個 Webhook URL，以用於記載每個送入訊息或 CDR 事件。

對外部服務的程式化呼叫必須符合下列需求：

  • 呼叫必須是 POST HTTP 要求。

若要新增 Webhook 詳細資料，請完成下列步驟：

  1. 在助理中，開啟您要在其中配置 Webhook 的環境。

  2. 按一下 環境設定圖示 圖示，以開啟環境設定。

  3. 在「環境設定」頁面上，按一下 日誌 Webhook。

    1. 或者，如果您使用典型體驗，請開啟 助理 頁面。

    2. 針對您要配置的助理，按一下 溢位功能表 圖示，然後選擇 設定。

    3. 按一下 Webhook，然後按一下 日誌 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. 在「標頭」區段中，按一下新增標頭來新增要傳遞給服務的任何標頭，一次新增一個標頭。

    服務會自動傳送含有 JWT 的 Authorization 標頭; 您不需要新增一個標頭。 如果您想要自行處理授權，請新增您自己的授權標頭，並改為使用它。

    儲存標頭值之後，會以星號取代字串，且無法再次檢視。

您的 Webhook 詳細資料會自動儲存。

移除 Webhook

如果您決定不要使用 Webhook 來記載訊息，請完成下列步驟:

  1. 在助理中，移至 環境，然後開啟您要配置 Webhook 的環境。

  2. 按一下 環境設定圖示 圖示，以開啟環境設定。

  3. 在「環境設定」頁面上，按一下 日誌 Webhook。

    1. 或者，如果您使用典型體驗，請開啟 助理 頁面。

    2. 針對您要配置的助理，按一下 溢位功能表 圖示，然後選擇 設定。

    3. 按一下 Webhook，然後按一下 日誌 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 要求內文

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 日誌事件參照。