使用网络钩子记录活动
每次客户向助手提交输入时，您都可以通过调用外部服务或应用程序来记录活动。
网络钩子是一种机制，可用于根据程序中的事件调用外部程序。
此功能仅适用于 Plus 和 Enterprise 计划用户。 Plus 计划允许每个实例不超过 5 个日志网络钩子。 此限制不适用于企业计划实例。
如果要使用外部服务记录活动，可在助手中添加日志 webhook。 您可以记录两种活动：
信息和回复：每次助理响应客户输入时，都会触发日志 webhook。 您可以使用此选项替代内置分析功能，自行处理日志记录。 （有关内置分析功能的更多信息，请参阅 《一目了然地查看整个助手 》。）
如果您使用的是自定义通道，则日志网络钩子仅适用于v2"/message应用程序接口（无状态和有状态）。 如需更多信息，请参阅 API 参考文档。 所有内置渠道集成都使用此 API。
通话详细记录 (CDR)：用户每次拨打使用电话集成的助手的电话后，都会触发日志 webhook。 通话详细记录 (CDR) 是记录电话通话细节的汇总报告，包括电话号码、通话时长、延迟和其他诊断信息。 CDR 记录只针对使用电话集成的助手。
日志网络钩子不会向助手返回任何信息。
对于使用专用端点的环境，请记住网络钩子会通过互联网发送流量。
定义 Webhook
您可以定义一个 Webhook URL ，用于记录每一条传入信息或 CDR 事件。
对外部服务的程序化调用必须满足以下需求：
调用必须是 POST HTTP 请求。
要添加 Webhook 详细信息，请完成以下步骤：
在助手中，打开要配置 webhook 的环境。
点击 图标
以打开环境设置。在环境设置页面，单击日志网络钩子。
对于您要配置的助手，请点击 图标
，然后选择 “设置 ”。单击Webhooks，然后单击Log webhook。
将日志网络钩子开关设置为已启用。
如果无法启用网络钩子，您可能需要升级服务计划。
在 URL 字段中，添加要向其发送 HTTP POST 请求调出的外部应用程序的 URL。 例如，
https://example.com/my_log_service。
您必须指定一个使用 SSL 协议的 URL ，因此请指定一个以 https. 开头的 URL。
在 "密文"字段中，添加一个与请求一起传递的令牌，该令牌可用于外部服务的身份验证。
密文必须指定为文本字符串，如 "purple unicorn。 最大长度为 1 024 个字符。 不能指定上下文变量。
外部服务有责任检查和验证该秘密。 如果外部服务不需要令牌，则可指定任意字符串。 该字段不能为空。
如果您希望在输入密码时查看密码内容，请在开始输入前点击 “ 
显示密码”图标。 保存秘密后，字符串将被星号替换，无法再次查看。
单击相应的复选框，选择要记录的活动类型：
要记录信息和回复，请选择订阅对话日志。
要记录电话集成的 CDR 事件，请选择订阅 CDR（通话详细记录）。
在“头”部分中，通过单击添加头来添加要传递给服务的任何头，一次添加一个头。
服务会自动发送带有 JWT 的 "Authorization标头，您无需添加。 如果您想自己处理授权，请添加自己的授权标头，然后使用它。
保存标题值后，字符串将被星号替换，无法再次查看。
这将自动保存 Webhook 详细信息。
删除网络钩子
如果决定不使用 webhook 记录信息，请完成以下步骤：
在助手中，转到环境并打开要配置 webhook 的环境。
点击 图标
以打开环境设置。在环境设置页面，单击日志网络钩子。
对于您要配置的助手，请点击 图标
，然后选择 “设置 ”。单击Webhooks，然后单击Log webhook。
执行下列其中一项操作：
要更改要调用的网络钩子，请单击 " 删除网络钩子 " 删除当前指定的 URL 和密 码。 然后，您可以添加 URL 和其他详细信息。
要停止调用网络钩子来记录每条信息和响应，请单击 "记录网络钩子 "开关以完全禁用网络钩子。
Webhook 安全性
要验证 webhook 请求，请验证随请求一起发送的 JSON 网络令牌 (JWT)。 网络挂钩微服务会自动生成 JWT，并在每次网络挂钩调用时通过 "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 日志事件参考。