IBM Cloud Docs
定义音频网络钩子

定义音频网络钩子

该功能目前仅支持电话集成的 Genesys 音频连接器。

只要使用记录响应类型收集音频,音频 webhook 就会调用外部服务或应用程序。 外部服务会处理音频,如果出现错误,就会断开通话。 出于合规原因,音频网络钩子通常用于存储音频,因为 watsonx Assistant 不会存储音频。

准备工作

对外部服务的程序化调用必须满足以下需求:

  • 调用必须是 POST HTTP 请求。

  • 请求体必须是 JSON 对象(Content-Type: multipart/form-data)。

  • 呼叫必须在 30 秒或更短时间内返回。

有关录制音频的更多信息,请参阅 录制来电者的语音

过程

要添加 Webhook 详细信息,请完成以下步骤:

  1. 转到主页 > 环境

  2. "草稿 "选项卡 >" 草稿环境 "或 " 实时 "选项卡 >" 实时环境 "单击 " 设置 齿轮 "图标

  3. 单击音频 webhook

  4. 音频网络钩子开关设置为 Enabled

  5. URL 字段中,添加要发送 HTTP POST 请求的外部应用程序的 URL。 确保 URL 使用 SSL 协议(例如,以 https 开头)。

  6. 密文字段中,添加一个私人密钥,与请求一起传递,以便与外部服务进行身份验证。 密钥必须指定为文本字符串(例如,紫色独角兽),最大长度为 1 024 个字符。

    不能指定上下文变量。 如果外部服务不需要令牌,则可指定任意字符串。 该字段不能为空。 要在输入密码时查看密码,请在键入前单击“显示密码”。 保存密文后,星号将取代字符串,无法再次查看。 有关如何使用此字段的更多信息,请参阅 仅适用于经典体验的 Webhook 安全性

  7. 在“超时”字段中,指定助手在返回错误信息前等待网络钩子响应的时间(秒)。 超时时间必须在 1 至 30 秒之间。

  8. 在“头”部分中,通过单击添加头来添加要传递给服务的任何头,一次添加一个头。

    例如,如果您调用的外部应用程序返回一个响应,它可能会以多种格式发送响应。 网络钩子要求以 JSON 格式作出响应。 下表说明了如何添加标头,以确保返回的结果值是 JSON 格式。

    头示例
    头名称 头值
    Content-Type application/json

保存标题值后,字符串将被星号替换,无法再次查看。

这将自动保存 Webhook 详细信息。

有关更多示例,请参阅 音频 webhook 示例

测试 Webhook

在为生产环境中使用的助手启用网络钩子之前,请对其进行大量测试。

当电话通话中使用录音响应类型时,就会触发 webhook。 如果向网络钩子发出的请求失败,呼叫就会断开。 您可以查看电话集成日志,了解网络钩子失败的更多详情。 有关更多信息,请参阅 电话集成故障排除

请求主体

了解音频网络钩子请求体的格式非常有用,这样您的外部代码就可以处理它。

有效载荷包含音频和元数据(Content-Type: multipart/form-data)。 请求的示例如下

POST /audio-webhook HTTP/1.1
Content-Type: multipart/form-data; boundary=----------3676416B-9AD6-440C-B3C8-FC66DDC7DB45
----------3676416B-9AD6-440C-B3C8-FC66DDC7DB45
Content-Disposition: form-data; name="metadata"
Content-Type: application/json
{
    "assistant_id": "dadf4b56-3b67-411a-b48d-079806b626d3",
    "environment_id": "6205aead-fe91-44af-bfe1-b4435015ba23",
    "session_id": "50989a59-9976-4b3f-9a98-af42adcad69a",
    "recording_id": "3daeb5d2-f52b-4c3e-a869-328b6fc6327c",
    "start_timestamp": "2024-10-21T17:22:07.789Z",
    "stop_timestamp": "2024-10-21T17:22:37.789Z"
}
----------3676416B-9AD6-440C-B3C8-FC66DDC7DB45
Content-Disposition: form-data; name="audio_recording"
Content-Type: audio/mulaw;rate=8000

<binary data>