接收任务状态回调--实时音视频-火山引擎

文档中心

立即注册

实时音视频

请输入

功能配置

接收任务状态回调

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

适用场景

监听任务状态：
捕获用户结束说话、智能体回答完毕等关键节点，以便触发自定义业务逻辑（记录任务时长、更新客户端 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

消息示例

{
    "AppId": "661e****543cf",
    "BusinessId": "biz1",
    "RoomId": "room1",
    "TaskId": "room1",
    "UserID": "user1",
    "RoundID": 0,
    "EventTime": 1611736812853,
    "EventType": 0,
    "RunStage": "taskStart",
    "ErrorInfo": {
        "Errorcode": 1001,
        "Reason": ""
    }
}

最近更新时间：2026.01.09 15:09:12

这个页面对您有帮助吗？

有用

无用

实时音视频

适用场景 #

前提条件 #

操作步骤 #

回调消息说明 #

数据结构 (EventData) #