TRTC 云助手快速接入指引

概述
本指引将帮助您利用腾讯云 IM 和 TRTC AI 对话能力，从零搭建一个完整的 AI 陪伴应用。您需要完成以下工作：
腾讯云控制台配置：创建 IM 应用、创建 AI 聊天机器人。
业务服务端开发：实现 UserSig 签发、AI 通话管理、好友管理等接口（语言不限）。
客户端开发：集成 IM SDK 和 TRTC SDK，实现聊天与通话界面。
前提条件
注意：
TRTC AI 实时对话调用会产生使用费用，具体详情请参见 AI 实时对话计费说明。
IM AI 聊天机器人使用会产生 IM 相关费用，具体详情请参见 IM 计费说明。
﻿创建腾讯云 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. 单击创建并测试完成创建。
注意：
记录机器人的 UserID，后续服务端配置和客户端添加好友时都需要用到。
目前 AI 聊天机器人仅支持 1v1 单聊，请勿将其添加至群聊。
如需配置 IM 文字聊天的上下文记忆，可在机器人编辑页调整 历史消息条数（最大支持50条）。
步骤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 返回给客户端。关键参数说明如下：
参数
说明
参考文档
AgentConfig
机器人进房配置，包括 UserId、WelcomeMessage、打断模式等
﻿AgentConfig 数据结构﻿
STTConfig
语音识别配置，包括语言、VAD 静音时间、VAD 等级等
﻿STTConfig 说明﻿
LLMConfig
大模型配置，包括模型类型、API 地址、SystemPrompt、History 等
﻿LLMConfig 配置说明﻿
TTSConfig
语音合成配置，包括模型、音色 VoiceId、语言等
﻿TTSConfig 配置说明﻿
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：开发客户端
3.1 集成 IM SDK
集成 IM SDK 实现登录、好友管理和文字聊天功能。
平台
集成指引
iOS
﻿IM SDK iOS 无 UI 集成﻿
Android
﻿IM SDK Android 无 UI 集成﻿
Web
﻿IM SDK Web 集成﻿
Flutter
﻿IM SDK Flutter 集成﻿
核心实现：
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
}
字段
说明
src=2
AI 流式回复
src=22
中断 AI 生成（用户可发送此消息停止 AI 回复）
isFinished=1
回复生成完成
3.2 集成 TRTC SDK
集成 TRTC SDK 实现语音通话功能。
平台
集成指引
iOS
﻿TRTC iOS 无 UI 集成﻿
Android
﻿TRTC Android 无 UI 集成﻿
Web
﻿TRTC Web 集成﻿
Flutter
﻿TRTC Flutter 集成﻿
核心实现：
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
  }
}
state 值
含义
1
聆听中
2
思考中
3
说话中
4
被打断
5
说完了
步骤4：验证与测试
1. 启动业务服务端。
2. 在客户端输入任意 UserID 登录 IM。
3. 添加机器人为好友，进入聊天对话。
4. 文字聊天测试：发送文字消息，确认 AI 以流式打字机效果回复。
5. 语音通话测试：点击语音通话按钮，确认能与 AI 进行实时语音对话，检查实时字幕是否正常显示。
高级功能
远场人声抑制
在语音通话场景中，可能出现将环境中其他人声误识别为用户发言的情况。TRTC AI 对话支持远场人声抑制能力（STTConfig.VadLevel 设为2或3），可有效过滤背景交谈声，提升 AI 对目标用户语音的识别准确性。
AI 记忆能力
AI 陪伴支持三层记忆体系，使 AI 在文字和语音交互中都能保持连贯性：
维度
IM 文字记忆
TRTC 短期记忆
TRTC 长期记忆
技术方案
腾讯云 IM 原生
LLMConfig.UserMessages 注入 IM 历史
LLMConfig.SystemPrompt 注入 LLM 摘要
覆盖范围
最近 50 条
最近 N 条（可配置）
全量历史（压缩摘要）
精度
高（原文）
高（原文）
中（摘要）
短期记忆：在发起语音通话时，服务端通过 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 回调中抛出，常见错误：
错误
错误码
描述
ERR_TRTC_USER_SIG_CHECK_FAILED
-100018
UserSig 校验失败，检查签名是否正确或已过期
ERR_TRTC_CONNECT_SERVER_TIMEOUT
-3308
进房超时，检查网络连接
ERR_TRTC_INVALID_SDK_APPID
-3317
SDKAppID 错误
ERR_MIC_NOT_AUTHORIZED
-1317
麦克风未授权
详情请参见 TRTC 错误码表。
方案配套产品
系统层级
产品名称
场景用途
接入层
﻿即时通信 IM﻿
提供登录鉴权、好友关系链、单聊消息、AI 聊天机器人能力
接入层
﻿实时音视频 TRTC﻿
提供低延迟音频通话和 AI 实时对话能力（STT + LLM + TTS）
结语
当用户对 AI 陪伴和社交互动的需求不断增长时，AI 陪伴正在成为连接人与 AI 的重要交互形态。其目标并非简单的问答工具，而是通过文字聊天与语音通话的双通道融合，以及 AI 记忆能力的加持，为用户提供自然、连贯、有温度的 AI 社交体验。
基于腾讯云 IM 的 AI 聊天机器人能力和 TRTC AI 实时对话能力，AI 陪伴从概念走向工程化落地。开发者只需集成 IM SDK 和 TRTC SDK，搭建轻量业务服务端对接少量 Cloud API，即可快速构建完整的 AI 对话应用，将更多精力集中于业务场景与用户体验本身。
﻿

参数	说明	参考文档
AgentConfig	机器人进房配置，包括 UserId、WelcomeMessage、打断模式等	AgentConfig 数据结构
STTConfig	语音识别配置，包括语言、VAD 静音时间、VAD 等级等	STTConfig 说明
LLMConfig	大模型配置，包括模型类型、API 地址、SystemPrompt、History 等	LLMConfig 配置说明
TTSConfig	语音合成配置，包括模型、音色 VoiceId、语言等	TTSConfig 配置说明

平台	集成指引
iOS	IM SDK iOS 无 UI 集成
Android	IM SDK Android 无 UI 集成
Web	IM SDK Web 集成
Flutter	IM SDK Flutter 集成

字段	说明
`src=2`	AI 流式回复
`src=22`	中断 AI 生成（用户可发送此消息停止 AI 回复）
`isFinished=1`	回复生成完成

平台	集成指引
iOS	TRTC iOS 无 UI 集成
Android	TRTC Android 无 UI 集成
Web	TRTC Web 集成
Flutter	TRTC Flutter 集成

state 值	含义
1	聆听中
2	思考中
3	说话中
4	被打断
5	说完了

维度	IM 文字记忆	TRTC 短期记忆	TRTC 长期记忆
技术方案	腾讯云 IM 原生	LLMConfig.UserMessages 注入 IM 历史	LLMConfig.SystemPrompt 注入 LLM 摘要
覆盖范围	最近 50 条	最近 N 条（可配置）	全量历史（压缩摘要）
精度	高（原文）	高（原文）	中（摘要）

错误	错误码	描述
ERR_TRTC_USER_SIG_CHECK_FAILED	-100018	UserSig 校验失败，检查签名是否正确或已过期
ERR_TRTC_CONNECT_SERVER_TIMEOUT	-3308	进房超时，检查网络连接
ERR_TRTC_INVALID_SDK_APPID	-3317	SDKAppID 错误
ERR_MIC_NOT_AUTHORIZED	-1317	麦克风未授权

系统层级	产品名称	场景用途
接入层	即时通信 IM	提供登录鉴权、好友关系链、单聊消息、AI 聊天机器人能力
接入层	实时音视频 TRTC	提供低延迟音频通话和 AI 实时对话能力（STT + LLM + TTS）

快速接入指引

本页目录：

概述

前提条件

接入步骤

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

步骤2：搭建业务服务端

2.1 UserSig 签发

2.2 发起 AI 语音通话

2.3 停止 AI 语音通话

2.4 好友关系管理

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

步骤3：开发客户端

3.1 集成 IM SDK

3.2 集成 TRTC SDK

步骤4：验证与测试

高级功能

远场人声抑制

AI 记忆能力

服务端回调

常见问题

方案配套产品

结语