文档中心

实时音视频

用户指南

接收任务状态回调

接收任务状态回调

通过服务端回调，您可以实时获取所有硬件对话智能体任务的状态变化（如任务开始、结束）和错误信息，从而实现精细化的任务监控和故障排查。

适用场景

监听任务状态：

捕获用户结束说话、智能体回答完毕等关键节点，以便触发自定义业务逻辑（记录任务时长、更新客户端 UI 状态或触发下游数据分析流程等）。

分析服务端耗时：

通过比对不同状态回调的时间戳，分析 ASR、LLM、TTS 等处理阶段的耗时，辅助性能优化。

排查任务异常：

当任务发生异常时，回调消息中将提供错误码和详细信息，帮助快速定位问题根源。

前提条件

已经集成硬件对话智能体。更多信息，请参见快速集成指南。

操作步骤

登录硬件对话智能体控制台。

在左侧导航栏，单击功能配置。

在回调设置标签页，单击添加配置，然后按页面指引填写相关参数。

配置项	说明
回调事件	选择 VoiceChat。
回调区域	选择接收回调消息的业务服务器所在的区域（如 CN 表示中国大陆），建议选择就近区域以降低延迟。
回调 URL	设置接收回调消息的公网 URL 地址。必须以 http:// 或 https:// 开头，且确保公网可访问。如果使用 HTTPS，请确保您的服务器已安装有效的 SSL 证书。
回调密钥	自定义签名密钥。服务端发起回调时，将使用此密钥对请求进行签名。您需要在接收侧校验签名，以防止非法请求。具体签名算法请参见接收消息通知回调。

单击确定。

配置完成后，当智能体任务状态变更或发生错误时，您配置的回调 URL 将收到 HTTP(S) POST 请求，消息体为 JSON 格式。

回调消息说明

消息事件名称：VoiceChat

HTTP 方法：POST

Content-Type：application/json

数据结构 (EventData)

参数名	类型	描述	示例值
AppId	String	音视频应用的唯一标识。对于硬件对话智能体，该参数无实际用途，您无需关注。	661e****543cf
BusinessId	String	业务标识。对于硬件对话智能体，该参数无实际用途，您无需关注。	biz1
RoomId	String	房间 ID。对于硬件对话智能体，该参数无实际用途，您无需关注。	room1
TaskId	String	智能体任务 ID。	task1
UserID	String	说话人 UserId。	user1
RoundID	Integer	对话轮次，从 0 开始计数。	0
EventTime	Integer	事件发生的 Unix 时间戳 (ms)。	1611736812853
EventType	Integer	事件类型。 0：智能体任务状态变化。 1：智能体任务出现错误。	0
RunStage	String	状态详情。 taskStart：任务开始。 taskStop：任务结束。 beginAsking：用户开始说话。 asrFinish：用户结束说话。 answerFinish：智能体说话完成。 asr：ASR 处理阶段。 llm：LLM 处理阶段。 tts：TTS 处理阶段。 preParamCheck：参数校验错误。	preParamCheck
ErrorInfo	Object	错误信息对象。仅当 EventType 为 1 时存在。	n/a

ErrorInfo 对象结构

参数名	类型	描述	示例值
Errorcode	Integer	错误状态码。	1001
Reason	String	错误详细原因。	n/a

消息示例

最近更新时间：2026.07.19 13:27:35

这个页面对您有帮助吗？

有用

有用

无用

无用