在与 AI 通话过程中，可随时传入自定义文本让 AI 播报，并支持设置播报优先级来精确控制是立即插播，还是等待后播报。该功能可用于引导用户互动、提醒用户注意事项、或系统延迟时安抚用户等场景。 ## 应用场景 |场景 |描述 |示例 | |---|---|---| |AI 陪练 |用户长时间不说话时， AI 播放内容吸引用户继续互动。 |"我注意到你有一会儿没说话了，需要我解释一下刚才的内容吗？" | |桌游主持 |AI 扮演主持人角色，引导用户完成游戏流程。 |“现在轮到玩家 A 发言，请开始。” | |安全监管 |用户问题或大模型生成内容不合规时，引导用户调整会话内容。 |"抱歉，对话内容不符合社区规范。" | |延迟安抚 |触发 Function Calling 或联网造成 AI 回答延迟偏大时，引导用户耐心等待。 |"正在处理，请稍等。" | ## 实现方法

Warning

建议传入完整分句或整句进行播放，高频送入碎片化文本可能会导致播放顺序错乱。

### 通过服务端实现调用 `UpdateVoiceChat` 接口传入要播报的内容，并控制 AI 的播报行为： > 参数详细说明参见接口文档：[AI 音视频互动方案-UpdateVoiceChat（2025-06-01）](https://www.volcengine.com/docs/6348/2123350)、[实时对话式 AI-UpdateVoiceChat（2024-12-01）](https://www.volcengine.com/docs/6348/2011497)。 ```JSON { "AppId": "YOUR_AppId", // 与 StartVoiceChat 的一致 "RoomId": "YOUR_RoomId", // 与 StartVoiceChat 的一致 "TaskId": "YOUR_TaskId", // 与 StartVoiceChat 的一致 "Command": "ExternalTextToSpeech", //必须为该值 "Message": "你刚才的故事讲得真棒，能再讲一个吗。", // 要播报的文本内容，长度不超过 200 个字符。 "InterruptMode": 1 // 按需选择播放优先级，可为 1、2、3 } ``` ### 通过客户端实现在客户端调用 RTC SDK 接口 [sendUserBinaryMessage](https://www.volcengine.com/docs/6348/70080#senduserbinarymessage)（以 Android 端为例）发送需要播报的自定义文本给指定 AI。其中， * `userId`：填入Bot 的 ID（即 `StartVoiceChat` 配置的 `AgentConfig.UserId`）。 * `buffer`：需遵循如下格式： ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b4a02712cb19cb1191a8d5f4d9130b98.jpg) |参数名 |类型 |描述 | |---|---|---| |magic number |binary |消息格式，此处填入 `ctrl`。 | |length |binary |自定义文本消息长度，单位为 bytes。存放方式为大端序。 | |control_message |binary |自定义文本配置信息。 | **control_message** ** ** |参数名 |类型 |描述 | |---|---|---| |Command |String |控制命令，此处填入 `ExternalTextToSpeech`。 | |Message |String |自定义文本内容，长度不超过 200 个字符。 | |InterruptMode |Int |文本内容播报的优先级。

* `1`：高优先级。系统会终止当前交互，直接播放传入的文本内容。

* `2`：中优先级。系统会在当前交互结束后，播放传入的文本内容。

* `3`：低优先级。如果此时正在交互，系统会直接丢弃传入的文本内容。如果未在交互，系统会播放传入的文本内容。 | 你可参看以下示例传入自定义文本内容进行播放： C++ ```C++ // 发送文本转语音（TTS）指令，让智能体播报指定的文本内容。 void sendTTSMessage(const std::string &uid, const std::string& content) { nlohmann::json json_data; json_data["Command"] = "ExternalTextToSpeech"; json_data["Message"] = content; json_data["InterruptMode"] = 1; // InterruptMode 可选值1,2,3 sendUserBinaryMessage(uid, json_data.dump()); } void buildBinaryMessage(const std::string& magic_number, const std::string& message, size_t& binary_message_length, std::shared_ptr& binary_message) { auto magic_number_length = magic_number.size(); auto message_length = message.size(); binary_message_length = magic_number_length + 4 + message_length; binary_message = std::shared_ptr(new uint8_t[binary_message_length]); std::memcpy(binary_message.get(), magic_number.data(), magic_number_length); binary_message[magic_number_length] = static_cast((message_length >> 24) & 0xFF); binary_message[magic_number_length+1] = static_cast((message_length >> 16) & 0xFF); binary_message[magic_number_length+2] = static_cast((message_length >> 8) & 0xFF); binary_message[magic_number_length+3] = static_cast(message_length & 0xFF); std::memcpy(binary_message.get()+magic_number_length+4, message.data(), message_length); } int sendUserBinaryMessage(const std::string &uid, const std::string& message) { if (rtcRoom_ != nullptr) { size_t length = 0; std::shared_ptr binary_message = nullptr; buildBinaryMessage("ctrl", message, length, binary_message); return rtcRoom_->sendUserBinaryMessage(uid.c_str(), static_cast(length), binary_message.get()); } return -1; } ``` Java ```Java // 发送文本转语音（TTS）指令，让智能体播报指定的文本内容。 public void sendTTSMessage(String userId, String content) { JSONObject json = new JSONObject(); try { json.put("Command", "ExternalTextToSpeech"); json.put("Message", content); json.put("InterruptMode", 1); // InterruptMode 可选值1,2,3 } catch (JSONException e) { throw new RuntimeException(e); } String jsonString = json.toString(); byte[] buildBinary = buildBinaryMessage("ctrl", jsonString); sendUserBinaryMessage(userId, buildBinary); } private byte[] buildBinaryMessage(String magic_number, String content) { byte[] prefixBytes = magic_number.getBytes(StandardCharsets.UTF_8); byte[] contentBytes = content.getBytes(StandardCharsets.UTF_8); int contentLength = contentBytes.length; ByteBuffer buffer = ByteBuffer.allocate(prefixBytes.length + 4 + contentLength); buffer.order(ByteOrder.BIG_ENDIAN); buffer.put(prefixBytes); buffer.putInt(contentLength); buffer.put(contentBytes); return buffer.array(); } public void sendUserBinaryMessage(String userId, byte[] buffer) { if (rtcRoom_ != null) { rtcRoom_.sendUserBinaryMessage(userId, buffer, MessageConfig.RELIABLE_ORDERED); } } ``` TypeScript ```TypeScript import VERTC from '@volcengine/rtc'; const BotName = 'RobotMan_'; // 自定义智能体名称 const CommandKey = 'ctrl'; const engine = VERTC.createEngine('Your AppID'); // 你的 RTC 应用 APPId /** * @brief 指令类型 */ enum COMMAND { /** * @brief 发送文本转语音（TTS）指令，让智能体播报指定的文本内容。 */ EXTERNAL_TEXT_TO_SPEECH = 'ExternalTextToSpeech', }; /** * @brief 打断的类型 */ enum INTERRUPT_PRIORITY { /** * @brief 占位 */ NONE, /** * @brief 高优先级。智能体会终止当前交互，直接播放传入的文本内容。 */ HIGH, /** * @brief 中优先级。智能体会在当前交互结束后，播放传入的文本内容。 */ MEDIUM, /** * @brief 低优先级。如果此时智能体正在交互，智能体会直接丢弃传入的文本内容。如果未在交互，智能体会播放传入的文本内容 */ LOW, }; /** * @brief 将字符串包装成 TLV */ function stringToTLV(inputString: string, type = '') { const typeBuffer = new Uint8Array(4); for (let i = 0; i < type.length; i++) { typeBuffer[i] = type.charCodeAt(i); } const lengthBuffer = new Uint32Array(1); const valueBuffer = new TextEncoder().encode(inputString); lengthBuffer[0] = valueBuffer.length; const tlvBuffer = new Uint8Array(typeBuffer.length + 4 + valueBuffer.length); tlvBuffer.set(typeBuffer, 0); tlvBuffer[4] = (lengthBuffer[0] >> 24) & 0xff; tlvBuffer[5] = (lengthBuffer[0] >> 16) & 0xff; tlvBuffer[6] = (lengthBuffer[0] >> 8) & 0xff; tlvBuffer[7] = lengthBuffer[0] & 0xff; tlvBuffer.set(valueBuffer, 8); return tlvBuffer.buffer; }; /** * @brief 发送文本转语音（TTS）指令，让智能体播报指定的文本内容 */ engine.sendUserBinaryMessage( BotName, stringToTLV( JSON.stringify({ Command: COMMAND.EXTERNAL_TEXT_TO_SPEECH, Message: '自定义文本内容', InterruptMode: INTERRUPT_PRIORITY.HIGH, }), CommandKey, ) ); ``` ## FAQ * Q1：**如果设置 AI 支持语音打断，自定义文本内容不打断 AI 输出。本次交互被语音打断时，自定义文本内容何时播放？** A1：此时自定义文本内容会被丢弃。 * Q2：**播放的自定义文本内容是否会放入历史对话？** A2：会。 * Q3：**如果设置 AI 支持语音打断，自定义文本内容不打断 AI 输出。自定义文本内容播放时被打断，该文本内容是否会放在历史对话中？** A3：已输出的内容会放入历史对话中。

实时音视频