接收回调

注意

回调服务不能保证完全可靠，请慎重考虑使用回调方案构建核心业务流程的风险。

通过本回调，您可以监听用户与智能体对话过程中所发生的事件，包含 ASR 结果、LLM 结果、异常事件、智能体被打断事件、用户说话行为、智能体说话行为、用户说话音频数据、智能体实例创建成功、智能体实例删除成功。

说明

如您需要接收以下类型的回调结果，请在创建智能体实例时，配置相应的 CallbackConfig 参数为 1：

ASR 结果：CallbackConfig.ASRResult。
LLM 结果：CallbackConfig.LLMResult。
智能体被打断事件：CallbackConfig.Interrupted。
用户说话行为：CallbackConfig.UserSpeakAction。
智能体说话行为：CallbackConfig.AgentSpeakAction。
用户说话音频数据：CallbackConfig.UserAudioData。

回调说明

请求方法：POST。
说明
回调数据格式为 JSON。您需要对其进行 UrlDecode 解码.
请求地址：请提供您业务后台用于接收回调的地址并联系 ZEGO 技术支持配置。
传输协议：HTTPS/HTTP，建议使用 HTTPS。

回调参数

说明

回调的相关参数，ZEGO 会在之后的迭代计划中，持续优化更新（例如：新增字段、或新增某些字段的参数取值）。开发者在接入时，请避免将代码写死，造成后期更新后，无法兼容新版本。

参数	类型	描述
AppId	Number	ZEGO 给开发者 APP 的唯一标识。
Event	String	事件通知类型。 ASRResult：ASR 结果。 LLMResult：LLM 结果。 Exception：异常事件。 Interrupted：智能体被打断。 UserSpeakAction：用户说话行为。 AgentSpeakAction：智能体说话行为。 UserAudioData：用户说话音频数据。 AgentInstanceCreated：智能体实例创建成功。 AgentInstanceDeleted：智能体实例删除成功。
Nonce	String	随机数，用于检验串计算。
Timestamp	Number	回调发送时的 Unix 时间戳（毫秒），用于检验串计算。
Signature	String	检验串，验证回调发送方身份。
AgentInstanceId	String	智能体实例的唯一标识。
AgentUserId	String	智能体的用户 ID。
RoomId	String	房间 ID。
Sequence	Number	回调序号，保证有序性，不保证连续性。
Data	Object	事件详细信息。本参数结构，请参考 Data。

Data

根据 Event 取值不同，Data 包含的参数不同。

ASRResult

LLMResult

Exception

Interrupted

UserSpeakAction

AgentSpeakAction

UserAudioData

AgentInstanceCreated

AgentInstanceDeleted

回调示例

以下展示各 Event 的回调示例。

ASRResult

LLMResult

Exception

Interrupted

UserSpeakAction

AgentSpeakAction

UserAudioData

AgentInstanceCreated

AgentInstanceDeleted

验证签名

为提高数据安全性，建议开发者在收到 ZEGO 服务端发出的回调时，进行本地签名计算，并与 signature 进行对比，判断该请求是否合法。

校验的使用流程如下：

对参数进行排序

将 callbacksecret、timestamp、nonce 三个参数按照字典序进行排序

计算 SHA1

将排序后的 callbacksecret、timestamp、nonce 拼接成一个字符串并进行sha1计算

校验 signature

将计算后的哈希字符串与 signature 进行校验对比，如果相同则标识该请求来源于 ZEGO

参数说明如下：

参数	说明
callbacksecret	服务端校验密钥。在 ZEGO 控制台注册项目时生成，可在 “控制台 > 项目配置 > 项目信息 > 配置信息” 中查看。
timestamp	Unix 时间戳。
nonce	随机数。

使用示例

返回响应

当您收到回调后，请返回 HTTP status code 为 2XX （例如 200），表示接收成功。返回其他，都表示接收失败。

回调重试策略

如果 ZEGO 服务器没有收到响应，或收到的 HTTP status code 不为 2XX（例如 200），都会尝试重试，最多进行 5 次重试。每次重试请求与上一次请求的间隔时间分别为 2s、4s、8s、16s、32s。若第 5 次重试后仍然失败，将不再重试，该回调丢失。