帮你快速理解、总结文档立即下载
文档中心>实时音视频>AI 实时对话>高级设置>AI 对话 2.0 服务端回调

AI 对话 2.0 服务端回调

最近更新时间：2026-10-09 11:26:11
我的收藏

本页目录：

本文用于介绍 AI 对话 2.0 服务相关的云 API 接口产生的事件，以 HTTP 请求的形式通知到您的服务器。任务运行期间，TRTC 将 AI 对话过程中的关键事件以回调（Webhook）方式实时推送到业务后端的回调 URL，业务侧无需轮询查询接口即可获取对话内容、状态流转与任务生命周期信息。
说明：
AI 对话 2.0 使用全新的事件组，与 1.0 的回调事件完全隔离，互不影响。

功能概述

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

配置信息

在实时音视频 TRTC 控制台（或通过腾讯云技术支持）配置业务后端的回调 URL 与回调密钥，配置完成后即可接收事件回调通知。
注意：
您需要提前准备以下信息：
必要项：接收回调通知的 HTTP/HTTPS 服务器地址，需公网可达，仅支持 POST 方法。
必要项：用于 Sign 签名校验的回调密钥，需妥善保密。密钥仅用于服务端签名校验，不要下发到客户端或写入前端代码。
配置项
要求
回调 URL
公网可达的 HTTP(S) 地址，仅支持 POST 方法。
回调密钥
用于 Sign 签名校验，需妥善保密。

超时重试

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

事件回调消息格式

事件回调消息以 HTTP POST 请求发送给您的服务器，其中：
请求：HTTP 请求的 header 中包含签名等信息，body 格式为 JSON。
应答：HTTP STATUS CODE = 200。
包体示例：所有回调事件共用同一套报文结构，通过 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。
{
    "EventGroupId": 15,
    "EventType": 1501,
    "CallbackTs": 1751196050100,
    "EventInfo": {
        "EventMsTs": 1751196050080,
        "TaskId": "task-88a1b2c3",
        "RoomId": "room-user123",
        "RoomIdType": 1,
        "Payload": {
            "Status": 0,
            "ConversationMode": "Cascade"
        }
    }
}

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. 截图回调的前提：截图上传结果事件仅在配置云存储归档后才会推送，不配置时截图仅驻留内存、不落盘。
中国站