实时音视频 服务端功能

一、功能概述

能力	对应事件	业务价值
对话内容落库	ASR 识别结果、LLM 回复结果	用户与 AI 发言实时归档，用于质检、审计与后续分析。
状态同步	AI 状态流转	机器人对话状态实时流转（聆听中/思考中/说话中…），驱动业务侧状态展示。
任务监控告警	任务启动完成、任务结束	启动结果与结束原因（LeaveCode）第一时间触达，便于及时告警与排障。
视觉理解归档	截图上传结果	截图上传云存储的结果通知，配合完成视觉素材归档。

二、配置信息

在实时音视频 TRTC 控制台（或通过腾讯云技术支持）配置业务后端的回调 URL 与回调密钥，配置完成后即可接收事件回调通知。详细操作指引请参见回调配置。

注意：你需要提前准备以下信息：

配置项	要求
回调 URL	公网可达的 HTTP(S) 地址，仅支持 POST 方法。
回调密钥	用于 Sign 签名校验，需妥善保密。

三、超时重试

网络重传等情况下回调可能重复投递，业务侧需按 TaskId + 事件类型 + 时间戳（EventMsTs）做幂等去重。收到回调后请尽快返回 HTTP 200，耗时处理（落库、分析等）建议异步进行，避免阻塞导致重复投递。

四、事件回调消息格式

事件回调消息以 HTTP POST 请求发送给你的服务器，其中：

·请求：HTTP 请求的 header 中包含签名等信息，body 格式为 JSON。

·应答：HTTP STATUS CODE = 200，服务端忽略应答包具体内容，为了协议友好，建议客户应答内容携带 JSON： {"code":0}。

·包体示例：所有回调事件共用同一套报文结构，通过 EventType 区分具体事件，事件内容放在 EventInfo.Payload 中。下述为通用报文结构，各事件详情中的 JSON 为填充了对应 Payload 的完整报文。

{ "EventGroupId": 15, "EventType": 1501, "CallbackTs": 1751196050100, "EventInfo": { "EventMsTs": 1751196050080, "TaskId": "task-88a1b2c3", "RoomId": "room-user123", "RoomIdType": 1, "Payload": { } }}

五、回调消息参数

·事件回调消息的 header 中包含以下字段：

字段名	含义
Content-Type	application/json。
Sign	签名值。
SdkAppId	创建应用时控制台分配的 SdkAppId。

·事件回调消息的 body 中包含以下字段：

字段名	类型	含义
EventGroupId	Integer	事件组 ID，AI 对话 2.0 事件组固定为 15。
EventType	Integer	回调通知的事件类型。
CallbackTs	Integer	事件回调服务器向你的服务器发出回调请求的 Unix 时间戳，单位为毫秒。
EventInfo.EventMsTs	Integer	事件发生的 Unix 时间戳，单位为毫秒。
EventInfo.TaskId	String	AI 任务 ID。
EventInfo.RoomId	String	TRTC 的房间 ID。
EventInfo.RoomIdType	Integer	0：表示数字房间号；1：表示字符串房间号。
EventInfo.Payload	Object	事件内容，随事件类型不同而不同，见下文各事件详情。

六、事件组 ID

字段名	值	含义
EVENT_GROUP_CLOUD_CONVERSATION	15	AI 对话 2.0 事件组。

七、事件类型

字段名	值	含义	触发时机	Payload 关键字段
EVENT_TYPE_CONVERSATION_SERVICE_START	1501	任务启动完成	AI 服务启动流程结束（成功或失败）	Status 、 ConversationMode
EVENT_TYPE_CONVERSATION_SERVICE_STOP	1502	任务结束	任务退出（主动结束/被踢/异常等）	LeaveCode
EVENT_TYPE_CONVERSATION_ASR_MSG	1503	ASR 识别结果	用户一句话识别完成（终态）	UserId 、 Text 、 RoundId 、起止时间
EVENT_TYPE_CONVERSATION_LLM_MSG	1504	LLM 回复结果	AI 单轮回复生成完成（终态）	Text 、 RoundId
EVENT_TYPE_CONVERSATION_AI_STATUS	1505	AI 状态流转	机器人对话状态每次变化	State.Code 、 State.Desc 、 Timestamp
EVENT_TYPE_CONVERSATION_VISION_FRAME_UPLOADED	1506	截图上传结果	周期性截图上传云存储后	Count 、 Frames[]

注意：稳态回调说明：

注意：ASR 识别结果与 LLM 回复结果事件只在终态投递一次完整文本，不推送中间流式片段。

八、1501：任务启动完成

AI 服务启动流程结束（Bot 进房、链路就绪）后推送。

字段名	类型	含义
EventMsTs	Integer	事件发生的 Unix 时间戳，单位为毫秒。
TaskId	String	AI 任务 ID。
RoomId	String	TRTC 的房间 ID。
RoomIdType	Integer	0：表示数字房间号；1：表示字符串房间号。
Payload.Status	Integer	启动结果：0：启动 AI 任务成功；1：启动 AI 任务失败。
Payload.ConversationMode	String	对话模式：Cascade；S2S。

九、1502：任务结束

任务退出后推送，通过 LeaveCode 区分退出原因。

字段名	类型	含义
EventMsTs	Integer	事件发生的 Unix 时间戳，单位为毫秒。
TaskId	String	AI 任务 ID。
RoomId	String	TRTC 的房间 ID。
RoomIdType	Integer	0：表示数字房间号；1：表示字符串房间号。
Payload.LeaveCode	Integer	0：正常结束，业务后端调用「删除任务」接口后退出；1：业务自行踢掉 Bot 后退出；2：业务解散房间后退出；3：TRTC 服务端踢掉机器人；4：TRTC 服务端解散房间；98：内部异常错误，建议业务重试；99：房间内除 Bot 外无其他用户流，超时退出。

{ "EventGroupId": 15, "EventType": 1502, "CallbackTs": 1751196050100, "EventInfo": { "EventMsTs": 1751196050080, "TaskId": "task-88a1b2c3", "RoomId": "room-user123", "RoomIdType": 1, "Payload": { "LeaveCode": 0 } }}

十、1503：ASR 识别结果

用户一句话识别完成（终态）后推送，Text 为该句完整识别文本。

字段名	类型	含义
EventMsTs	Integer	事件发生的 Unix 时间戳，单位为毫秒。
TaskId	String	AI 任务 ID。
RoomId	String	TRTC 的房间 ID。
RoomIdType	Integer	0：表示数字房间号；1：表示字符串房间号。
Payload.UserId	String	说话用户的 ID。
Payload.Text	String	识别出的完整文本（终态）。
Payload.StartTimeMs	Integer	句子开始时间，单位为毫秒。
Payload.EndTimeMs	Integer	句子结束时间，单位为毫秒。
Payload.StartUtcMs	Integer	句子开始的 UTC 时间，单位为毫秒。
Payload.EndUtcMs	Integer	句子结束的 UTC 时间，单位为毫秒。
Payload.RoundId	String	轮次 ID，用于关联同一轮的 ASR 与 LLM 结果。

{ "EventGroupId": 15, "EventType": 1503, "CallbackTs": 1751196050100, "EventInfo": { "EventMsTs": 1751196050080, "TaskId": "task-88a1b2c3", "RoomId": "room-user123", "RoomIdType": 1, "Payload": { "UserId": "user123", "Text": "这个按钮为啥点不动？", "StartTimeMs": 1751196058500, "EndTimeMs": 1751196060100, "StartUtcMs": 1751196058500, "EndUtcMs": 1751196060100, "RoundId": "2b7d223d-35b8-4d29-bd1a-69ec8cb89f0b-0" } }}

十一、1504：LLM 回复结果

AI 单轮回复生成完成（终态）后推送，Text 为该轮完整回复文本。

字段名	类型	含义
EventMsTs	Integer	事件发生的 Unix 时间戳，单位为毫秒。
TaskId	String	AI 任务 ID。
RoomId	String	TRTC 的房间 ID。
RoomIdType	Integer	0：表示数字房间号；1：表示字符串房间号。
Payload.Text	String	LLM 单轮回复的完整文本（终态）。
Payload.RoundId	String	轮次 ID，与同轮的 ASR 识别结果事件一致。

{ "EventGroupId": 15, "EventType": 1504, "CallbackTs": 1751196050100, "EventInfo": { "EventMsTs": 1751196050080, "TaskId": "task-88a1b2c3", "RoomId": "room-user123", "RoomIdType": 1, "Payload": { "Text": "这个按钮是灰色禁用状态，需要先勾选上方的\\"同意协议\\"才能激活。", "RoundId": "554772d4-5f23-4b5a-8361-764d0fc7bb0f-0" } }}

十二、1505：AI 状态流转

机器人每发生一次对话状态流转即推送一条，实时性最高。状态码与客户端 SDK 的状态事件共用同一套定义。

字段名	类型	含义
EventMsTs	Integer	事件发生的 Unix 时间戳，单位为毫秒。
TaskId	String	AI 任务 ID。
RoomId	String	TRTC 的房间 ID。
RoomIdType	Integer	0：表示数字房间号；1：表示字符串房间号。
Payload.State.Code	Integer	机器人对话状态码：0：AI 空闲中；1：AI 聆听中（ASR 识别中）；2：AI 思考中（LLM 推理中）；3：AI 说话中（TTS 播报中）；4：AI 被打断（轮次提前终止）；5：AI 已说完（轮次正常结束）。
Payload.State.Desc	String	状态描述。
Payload.Timestamp	Integer	状态流转时间戳，单位为毫秒。

{ "EventGroupId": 15, "EventType": 1505, "CallbackTs": 1751196050100, "EventInfo": { "EventMsTs": 1751196050080, "TaskId": "task-88a1b2c3", "RoomId": "room-user123", "RoomIdType": 1, "Payload": { "State": { "Code": 5, "Desc": "AI Speaking Finished" }, "Timestamp": 1790820920603 } }}

十三、1506：截图上传结果

启用视觉理解并配置云存储归档（StorageType=1 + CloudStorage）后，后台将截图异步上传至云存储，并周期性推送上传结果。

字段名	类型	含义
EventMsTs	Integer	事件发生的 Unix 时间戳，单位为毫秒。
TaskId	String	AI 任务 ID。
RoomId	String	TRTC 的房间 ID。
RoomIdType	Integer	0：表示数字房间号；1：表示字符串房间号。
Payload.PeriodStartMs	Integer	本批次截图的时间区间起点，单位为毫秒。
Payload.PeriodEndMs	Integer	本批次截图的时间区间终点，单位为毫秒。
Payload.Count	Integer	本批次上传的截图数量。
Payload.Frames	Array of Object	截图列表，每项字段定义见下表。

Payload.Frames 元素字段：

字段名	类型	含义
FrameId	String	截图帧 ID。
CaptureMs	Integer	截图时间，单位为毫秒。
Reason	String	截图触发原因，如 scene_change 表示场景变化。
ObjectKey	String	云存储对象路径，格式为：vision/{SdkAppId}/{日期}/{TaskId}/{captureTs}_{reason}_{frameId}.jpg。
SizeBytes	Integer	图片大小，单位为字节。

{ "EventGroupId": 15, "EventType": 1506, "CallbackTs": 1751196050100, "EventInfo": { "EventMsTs": 1751196050080, "TaskId": "task-88a1b2c3", "RoomId": "room-user123", "RoomIdType": 1, "Payload": { "PeriodStartMs": 1751196060000, "PeriodEndMs": 1751196061000, "Count": 2, "Frames": [ { "FrameId": "F-8a3f2c1e-0007", "CaptureMs": 1751196060120, "Reason": "scene_change", "ObjectKey": "vision/1400000000/20260812/task-88a1b2c3/1751196060120_scene-change_F-8a3f2c1e-0007.jpg", "SizeBytes": 52310 } ] } }}

十四、计算签名

签名放在请求头 Sign 中。你的事件回调接收服务器收到回调消息后，通过同样的方式计算出签名，相同则说明是腾讯云实时音视频的事件回调，没有被伪造。签名的计算方式与 Java / Python / PHP / Golang 校验示例代码，详见签名校验示例。

注意：计算签名时，body 须为你收到回调请求的原始包体，不要做任何转化，需完整保留 \\n、\\t 等转义字符。

十五、注意事项

1. 必须校验签名：未校验 Sign 的回调接收端点存在被伪造请求攻击的风险。

2. 稳态回调：ASR 识别结果与 LLM 回复结果只在终态投递一次完整文本，不推送中间流式片段；如需流式字幕请使用客户端字幕通道。

3. 幂等处理：网络重传等情况下回调可能重复投递，业务侧需按 TaskId + 事件类型 + 时间戳（EventMsTs / Timestamp）做幂等去重。

4. 及时响应：收到回调后尽快返回 HTTP 200，耗时处理（落库、分析等）建议异步进行，避免阻塞导致重复投递。

5. 回调密钥保密：密钥仅用于服务端签名校验，不要下发到客户端或写入前端代码。

6. 截图回调的前提：截图上传结果事件仅在配置云存储归档后才会推送，不配置时截图仅驻留内存、不落盘。