TRTC 云助手 快速接入指引（AI 陪伴）

一、概述

·腾讯云控制台配置：创建 IM 应用、创建 AI 聊天机器人。

·业务服务端开发：实现 UserSig 签发、AI 通话管理、好友管理等接口（语言不限）。

·客户端开发：集成 IM SDK 和 TRTC SDK，实现聊天与通话界面。

二、前提条件

·创建腾讯云 IM 应用，获取 SDKAppID 和 密钥（Secret）。

·获取腾讯云 API 密钥（SecretId / SecretKey），用于服务端调用 TRTC Cloud API。

·获取 LLM API Key（如 DeepSeek），用于 TRTC 语音通话场景的大模型配置。

·在 IM 控制台「账号管理」中确认 App 管理员账号的 UserID，调用 IM REST API（如添加好友）时必须使用管理员账号，详见 IM REST API 简介。

四、步骤1：创建 IM AI 聊天机器人

在腾讯云 IM 控制台添加 AI 聊天机器人，具体流程请参见 即时通信 IM AI 聊天机器人。

1. 在 IM 控制台 左侧导航栏选择消息服务 Chat > AI 聊天机器人。

2. 选择对应的应用，单击立即开通。

3. 单击新建 AI 聊天机器人（或使用预设模板）。

4. 配置机器人的基础信息：昵称、描述、UserID、欢迎语、头像等。

5. 配置 AI 服务：选择 AI 服务厂商（如 DeepSeek、腾讯云 LKE 等），填写模型、API-Key、Prompt 等参数。

6. 单击创建并测试完成创建。

五、步骤2：搭建业务服务端

业务服务端语言不限（Python / Java / Go / Node.js 等均可），需实现以下核心接口。

六、2.1 UserSig 签发

客户端登录 IM 和进入 TRTC 房间都需要 UserSig。服务端需基于 SDKAppID 和密钥，使用 TLS 签名算法 为指定 UserID 生成签名。

各语言签名生成工具：

·Python：tls-sig-api-v2

·Java：tls-sig-api-v2-java

·Go：tls-sig-api-v2-golang

·Node.js：tls-sig-api-v2-node

七、2.2 发起 AI 语音通话

当用户在客户端点击语音通话按钮时，业务服务端需完成以下操作：

·生成房间号和签名

·生成一个随机房间号（如8位数字字符串）。

·为用户和机器人分别生成 UserSig。

·构建参数并调用 StartAIConversation。

{ "SdkAppId": 1400000000, "RoomId": "12345678", "RoomIdType": 1, "AgentConfig": { "UserId": "@RBT#bot_001", "UserSig": "机器人的UserSig", "TargetUserId": "user_123", "MaxIdleTime": 60, "WelcomeMessage": "你好，我是你的AI伙伴！", "InterruptMode": 0, "InterruptSpeechDuration": 500 }, "STTConfig": { "Language": "16k_zh_en", "VadSilenceTime": 600, "VadLevel": 3 }, "LLMConfig": "{\\"LLMType\\":\\"openai\\",\\"Model\\":\\"deepseek-chat\\",\\"APIKey\\":\\"你的APIKey\\",\\"APIUrl\\":\\"https://api.deepseek.com/chat/completions\\",\\"Streaming\\":true,\\"SystemPrompt\\":\\"你是一个友好的AI助手\\",\\"History\\":10,\\"Timeout\\":10}", "TTSConfig": "{\\"TTSType\\":\\"flow\\",\\"Model\\":\\"flow_01_turbo\\",\\"VoiceId\\":\\"v-male-W1tH9jVc\\",\\"Language\\":\\"zh\\"}"}

注意：LLMConfig 和 TTSConfig 需以 JSON 字符串形式传入，而非 JSON 对象。

·返回结果给客户端。

将 TaskId（用于后续停止通话）、RoomId、UserSig、SdkAppId 返回给客户端。关键参数说明如下：

八、2.3 停止 AI 语音通话

当用户挂断时，调用 StopAIConversation 停止 AI 对话任务。

{ "TaskId": "startCall返回的TaskId"}

九、2.4 好友关系管理

用户需将 AI 机器人添加为好友后才能发起文字聊天。为避免 AI 资源被恶意消耗，添加机器人好友不支持客户端 IM SDK 直接操作，需由业务服务端调用 IM REST API v4/sns/friend_add 完成双向添加。

IM REST API（包括添加好友接口）要求以 App 管理员身份 发起请求，具体规则参见 IM REST API 简介：

·服务端在调用 REST API 时，identifier 必须为 App 管理员账号。

·可以在每次调用 REST API 时都生成管理员账号的 UserSig，亦可生成一个固定的 UserSig 重复使用，但请特别注意 UserSig 的有效期。

·若使用普通用户账号调用，服务端会返回60010等权限错误。

完整请求 URL 示例：

https://console.tim.qq.com/v4/sns/friend_add ?sdkappid=1400000000 &identifier=administrator // 必须是管理员账号 &usersig=<管理员的UserSig> &random=99999999 &contenttype=json

请求 Body 示例：

{ "From_Account": "user_123", "AddFriendItem": [ { "To_Account": "@RBT#bot_001", "AddSource": "AddSource_Type_API" } ], "AddType": "Add_Type_Both", "ForceAddFlags": 1}

十、2.5 多角色人设管理（可选）

如需支持多个 AI 角色（如不同性格的聊天伙伴），可在服务端按机器人 UserID 维护不同的 SystemPrompt 和 WelcomeMessage，在调用 StartAIConversation 时动态传入。

示例人设配置结构：

机器人 UserID → { SystemPrompt, WelcomeMessage }─────────────────────────────────────────────────@RBT#Jarvis → "你化身为AI助手贾维斯…" / "你好，我是贾维斯"@RBT#Teacher → "你是一名耐心的英语老师…" / "Hi! Ready to practice?"默认 → "你是一个友好的AI助手…" / "你好，有什么可以帮你的？"

十二、3.1 集成 IM SDK

集成 IM SDK 实现登录、好友管理和文字聊天功能。

核心实现：

1. 登录：从业务服务端获取 SDKAppID 和 UserSig，调用 V2TIMManager.login() 登录 IM。

2. 添加好友：客户端调用业务服务端的好友管理接口，由服务端通过 IM REST API 将 AI 机器人添加为用户好友。注意：IM REST API 必须使用 App 管理员账号调用（identifier 填管理员 UserID、usersig 为管理员的 UserSig），客户端 IM SDK 无法直接添加机器人好友，详见 IM REST API 简介。

3. 发送消息：通过 sendC2CTextMessage() 向机器人发送文本消息。

4. 接收 AI 回复：监听 onRecvNewMessage 和 onRecvMessageModified 回调，解析自定义消息中的 chunks[] 实现流式渲染。

AI 流式消息格式（customElem.data）：

{ "chatbotPlugin": 2, "src": 2, "chunks": ["你", "好", "！"], "isFinished": 0}

十三、3.2 集成 TRTC SDK

集成 TRTC SDK 实现语音通话功能。

核心实现：

1. 发起通话：调用业务服务端"发起 AI 通话"接口，获取 roomId、userSig、sdkAppId、taskId。

2. 进入房间：使用返回参数调用 enterRoom()，场景选择 audioCall。

3. 开启音频：调用 startLocalAudio(.speech) 开启麦克风采集。推荐使用 SPEECH 模式，该模式专注语音信号、过滤环境噪音。

4. 开启 AI 降噪（推荐）：通过 TRTC 实验性 API 开启 AI 降噪，提升语音识别精度。

5. 接收实时字幕：通过 onRecvCustomCmdMsg（cmdID=1）接收实时字幕和 AI 状态。

6. 结束通话：调用业务服务端"停止 AI 通话"接口，然后 exitRoom() 退出房间。

·实时字幕消息格式（cmdID=1）：

{ "type": 10000, "sender": "user_a", "payload": { "text": "你好，很高兴认识你", "roundid": "xxxxx", "end": true }}

·AI 状态消息格式：

{ "type": 10001, "payload": { "state": 1 }}

十四、步骤4：验证与测试

1. 启动业务服务端。

2. 在客户端输入任意 UserID 登录 IM。

3. 添加机器人为好友，进入聊天对话。

4. 文字聊天测试：发送文字消息，确认 AI 以流式打字机效果回复。

5. 语音通话测试：点击语音通话按钮，确认能与 AI 进行实时语音对话，检查实时字幕是否正常显示。

十六、远场人声抑制

在语音通话场景中，可能出现将环境中其他人声误识别为用户发言的情况。TRTC AI 对话支持远场人声抑制能力（STTConfig.VadLevel 设为2或3），可有效过滤背景交谈声，提升 AI 对目标用户语音的识别准确性。

十七、AI 记忆能力

AI 陪伴支持三层记忆体系，使 AI 在文字和语音交互中都能保持连贯性：

·短期记忆：在发起语音通话时，服务端通过 IM REST API 拉取最近 N 条聊天记录，转换为 [{ Role, Content }] 格式后通过 LLMConfig.UserMessages 注入。

·长期记忆：基于 IM 聊天记录和 TRTC 903 服务端回调 获取的语音对话记录，通过 LLM 生成摘要注入 LLMConfig.SystemPrompt。

十八、服务端回调

可在 TRTC 控制台配置 AI 实时对话回调地址，接收 AI 对话过程中的各类事件通知，如对话文本内容（903回调）、对话开始/结束等。可参见 AI 对话服务端回调。

十九、常见问题

为什么文字聊天没有收到 AI 回复？

·检查 IM 控制台是否已正确创建并启用 AI 聊天机器人。

·确认机器人的 AI 服务配置（模型、API-Key）是否正确。

·确认是 C2C 单聊场景，AI 聊天机器人目前仅支持1v1单聊。

调用添加好友接口报 60010 错误？

IM REST API（包括 v4/sns/friend_add）要求使用 App 管理员账号发起请求。请检查：

·URL 参数 identifier 是否填写的是管理员账号的 UserID（如 administrator），而不是普通用户账号。

·usersig 是否为该管理员账号对应的 UserSig，而不是普通用户的 UserSig。

·管理员账号是否已在 IM 控制台「账号管理」中存在。

详见 IM REST API 简介。

为什么语音通话没有声音 / 没有 AI 回应？

·检查客户端是否已开启麦克风采集并发布音频流。

·确认 StartAIConversation 中的 RoomId 与客户端进房的 RoomId 一致，且房间号类型（RoomIdType）也一致。

·检查 LLMConfig 和 TTSConfig 的 JSON 字符串格式是否正确。

·确认腾讯云 API 密钥（SecretId / SecretKey）有效且有 TRTC 接口调用权限。

UserSig 如何生成？

UserSig 是基于 SDKAppID 和密钥的安全签名，用于 IM 登录和 TRTC 进房。请参见 UserSig 生成与校验，各语言均有对应的签名生成库。

注意：安全提示：UserSig 的计算必须在业务服务端完成，切勿将密钥暴露在客户端代码中。

TRTC 相关错误如何排查？

TRTC SDK 遇到不可恢复的错误会在 onError 回调中抛出，常见错误：

详情请参见 TRTC 错误码表。

20、方案配套产品

21、结语

当用户对 AI 陪伴和社交互动的需求不断增长时，AI 陪伴正在成为连接人与 AI 的重要交互形态。其目标并非简单的问答工具，而是通过文字聊天与语音通话的双通道融合，以及 AI 记忆能力的加持，为用户提供自然、连贯、有温度的 AI 社交体验。

基于腾讯云 IM 的 AI 聊天机器人能力和 TRTC AI 实时对话能力，AI 陪伴从概念走向工程化落地。开发者只需集成 IM SDK 和 TRTC SDK，搭建轻量业务服务端对接少量 Cloud API，即可快速构建完整的 AI 对话应用，将更多精力集中于业务场景与用户体验本身。