实时音视频
实时音视频
文档指南
请输入
实时音视频
快速入门
场景方案
开发指南
Token 鉴权
音频管理
视频管理
屏幕共享
SDK 升级指南
客户端 API 参考
服务端 API 参考
房间管理
转推直播
输入在线媒体流
WTN 流（原公共流）
实时数据监控
历史数据查询
业务标识管理
实时消息通信
历史版本（文档停止维护）
2023-08-01
2023-06-01
转推直播
2022-06-01
2020-12-01
转推直播
输入在线媒体流
获取数据指标
常见问题
集成相关
质量相关
AI 音视频互动方案
开始使用
开发指南
API 参考
硬件对话智能体
用户指南
服务端 API
智能体
实时信令
互动白板
客户端 API 参考
服务端 API 参考
- 文档首页
实时音视频AI 音视频互动方案开发指南获取 AI 状态
复制全文
下载 pdf获取 AI 状态
文档反馈
问问助手支持通过回调机制来实时获取 AI 状态，如聆听中、思考中、说话中、被中断或发生错误。您可以将这些状态信息在客户端实时展示，或在服务端进行持久化存储与分析。
- 通过客户端实现：延迟更低、可靠性更高，适用于需要在终端（App、Web）实时展示 AI 状态的场景。
- 通过服务端实现：适用于需要将状态持久化存储、进行二次分析，或客户端不便处理实时二进制消息的场景。
通过客户端实现
实现方式
- 在服务端开启回调：调用 StartVoiceChat 接口时，将 AgentConfig.EnableConversationStateCallback 设置为 true。
- 在客户端监听回调消息：在客户端监听 RTC SDK 回调 onRoomBinaryMessageReceived（以 Android 端为例）。
- 解析消息：当 AI 状态发生变化时，客户端会通过上述回调收到二进制 message。解析该消息后，即可获取具体的状态信息。解析方式，参见下方的消息解析示例。
消息解析示例
TypeScript
Java
C++
Objective-C
C
import VERTC from '@volcengine/rtc';
/**
* @brief TLV 数据格式转换成字符串
* @note TLV 数据格式
* | magic number | length(big-endian) | value |
* @param {ArrayBufferLike} tlvBuffer
* @returns
*/
function tlv2String(tlvBuffer: ArrayBufferLike) {
const typeBuffer = new Uint8Array(tlvBuffer, 0, 4);
const lengthBuffer = new Uint8Array(tlvBuffer, 4, 4);
const valueBuffer = new Uint8Array(tlvBuffer, 8);
let type = '';
for (let i = 0; i < typeBuffer.length; i++) {
type += String.fromCharCode(typeBuffer[i]);
}
const length =
(lengthBuffer[0] << 24) | (lengthBuffer[1] << 16) | (lengthBuffer[2] << 8) | lengthBuffer[3];
const value = new TextDecoder().decode(valueBuffer.subarray(0, length));
return { type, value };
};
/**
* @brief Room Message Handler
*/
function handleRoomBinaryMessageReceived(
event: {
userId: string;
message: ArrayBuffer;
},
) {
const { message } = event;
const { type, value } = tlv2String(message);
const data = JSON.parse(value);
const { EventTime, RoundID, Stage, TaskId, UserID, ErrorInfo } = data || {};
const { Code, Description } = Stage || {};
// 对 type、data 进行业务处理
console.log(type, EventTime, RoundID, TaskId, UserID, Code, Description);
if (ErrorInfo) {
const { Code, Reason } = ErrorInfo;
console.log('Error Occurred:', Code, Reason);
}
// ...
}
/**
* @brief 监听房间内二进制消息
*/
this.engine.on(VERTC.events.onRoomBinaryMessageReceived, handleRoomBinaryMessageReceived);
//智能体状态结构体
import com.google.gson.annotations.SerializedName;
class ErrorDetail {
@SerializedName("Code")
int errorCode;
@SerializedName("Reason")
String reason;
}
class Stage {
@SerializedName("Code")
/**
* 0: errorOccurred
* 1: listening
* 2: thinking
* 3: answering
* 4: interrupted
* 5: answerFinish
*/
int code;
@SerializedName("Description")
String description;
}
public class conversationStatusMessage {
@SerializedName("TaskId")
String taskId;
@SerializedName("UserID")
String userID;
@SerializedName("RoundID")
long roundID;
@SerializedName("EventTime")
long eventTime;
@SerializedName("Stage")
Stage stage;
@SerializedName("ErrorInfo")
ErrorDetail errorInfo;
public String toString() {
String string = "taskId:" + taskId + ", " +
"userID:" + userID + ", " +
"roundID:" + roundID + ", " +
"eventTime:" + eventTime + ", " +
"stage:" + stage.code + " - " + stage.description;
if (errorInfo != null) {
string += ", errorCode:" + errorInfo.errorCode + ", reason:" + errorInfo.reason;
}
System.out.println(string);
return string;
}
}
//解析消息
public void onRoomBinaryMessageReceived(String uid, ByteBuffer buffer) {
byte[] prefixBytes = new byte[4];
buffer.get(prefixBytes);
String prefix = new String(prefixBytes, StandardCharsets.UTF_8);
if (prefix.equals("conv")) {
int length = buffer.getInt();
byte[] jsonBytes = new byte[length];
buffer.get(jsonBytes);
String jsonContent = new String(jsonBytes, StandardCharsets.UTF_8);
conversationStatusMessage statusMessage = new Gson().fromJson(jsonContent, conversationStatusMessage.class);
System.out.println("Unpack_conv length:" + length + " " + statusMessage.toString());
} else {
System.out.println("Invalid message prefix:" + prefix);
}
}
struct ErrorDetail {
int errorCode;
std::string reason;
};
struct conversationStatusMessage
{
struct Stage
{
int code;
std::string description;
};
std::string taskId;
std::string userID;
int64_t roundID;
int64_t eventTime;
Stage stage;
std::optional<ErrorDetail> errorInfo;
};
void onRoomBinaryMessageReceived(const char *uid, int size, const uint8_t *message)
{
static const int headerSize = 8;
if (size < headerSize)
{
return;
}
uint32_t header = messageHeader(message);
if (header == 0x636F6E76U) // magic number "conv"
{
std::string strMessage = unpack(message, size);
if (!strMessage.empty())
{
unpackConversationStage(strMessage);
}
}
else
{
LOG_E << "unknown message header: " << header;
return;
}
}
void unpackConversationStage(const std::string &message)
{
// 解析 JSON 字符串
nlohmann::json json_data = nlohmann::json::parse(message);
// 存储解析后的数据
conversationStatusMessage conversationStatusMessage;
conversationStatusMessage.taskId = json_data["TaskId"];
conversationStatusMessage.userID = json_data["UserID"];
conversationStatusMessage.roundID = json_data["RoundID"];
conversationStatusMessage.eventTime = json_data["EventTime"];
conversationStatusMessage::Stage stage;
stage.code = json_data["Stage"]["Code"];
stage.description = json_data["Stage"]["Description"];
conversationStatusMessage.stage = stage;
if (json_data.contains("ErrorInfo") && !json_data["ErrorInfo"].is_null()) {
ErrorDetail errorDetail;
errorDetail.code = json_data["ErrorInfo"]["Code"];
errorDetail.reason = json_data["ErrorInfo"]["Reason"];
conversationStatusMessage.errorInfo = errorDetail;
}
}
#import <Foundation/Foundation.h>
typedef struct {
int errorCode;
NSString *reason;
} ErrorDetail;
typedef struct {
int code;
NSString *description;
} Stage;
@interface conversationStatusMessage : NSObject
@property (nonatomic, copy) NSString *taskId;
@property (nonatomic, copy) NSString *userID;
@property (nonatomic, assign) int64_t roundID;
@property (nonatomic, assign) int64_t eventTime;
@property (nonatomic, assign) Stage stage;
@property (nonatomic, assign) ErrorDetail errorInfo;
@property (nonatomic, assign) BOOL hasErrorInfo;
@end
@implementation conversationStatusMessage
@end
//回调
- (void)rtcRoom:( ByteRTCRoom *_Nonnull)rtcRoom onRoomBinaryMessageReceived:(NSString *_Nonnull)uid message:(NSData *_Nonnull)message {
NSString *strMessage = unpack(message);
if (strMessage) {
parseData(strMessage);
}
}
NSString *unpack(NSData *data) {
const int headerSize = 8;
NSUInteger size = data.length;
if (size < headerSize) {
return nil;
}
const uint8_t *message = data.bytes;
// Check magic number "conv"
uint32_t magic = (message[0] << 24) | (message[1] << 16) | (message[2] << 8) | message[3];
if (magic != 0x636F6E76) {
return nil;
}
// Get length
uint32_t length = (message[4] << 24) | (message[5] << 16) | (message[6] << 8) | message[7];
if (size - headerSize != length) {
return nil;
}
// Get conversationStatusMessage
NSString *conversationStatusMessage = nil;
if (length > 0) {
conversationStatusMessage = [[NSString alloc] initWithBytes:message + headerSize length:length encoding:NSUTF8StringEncoding];
} else {
conversationStatusMessage = @"";
}
return conversationStatusMessage;
}
void parseData(NSString *message) {
NSError *error = nil;
NSDictionary *json_data = [NSJSONSerialization JSONObjectWithData:[message dataUsingEncoding:NSUTF8StringEncoding] options:0 error:&error];
if (error || json_data == nil) {
NSLog(@"JSON parse error: %@", error);
return;
}
conversationStatusMessage *statusMsg = [[conversationStatusMessage alloc] init];
statusMsg.taskId = json_data[@"TaskId"];
statusMsg.userID = json_data[@"UserID"];
statusMsg.roundID = [json_data[@"RoundID"] longLongValue];
statusMsg.eventTime = [json_data[@"EventTime"] longLongValue];
Stage stage;
stage.code = [json_data[@"Stage"][@"Code"] intValue];
stage.description = json_data[@"Stage"][@"Description"];
statusMsg.stage = stage;
if (json_data[@"ErrorInfo"] && json_data[@"ErrorInfo"] != [NSNull null]) {
ErrorDetail errorDetail;
errorDetail.code = [json_data[@"ErrorInfo"][@"Code"] intValue];
errorDetail.reason = json_data[@"ErrorInfo"][@"Reason"];
statusMsg.errorInfo = errorDetail;
statusMsg.hasErrorInfo = YES;
} else {
statusMsg.hasErrorInfo = NO;
}
}
#define CONVERSATION_MAGIC_HEADER_SIZE 8
#define CONVERSATION_MAGIC_STATUS_STR "conv"
static bool _is_target_message(const uint8_t* message, const char* target) {
if (message == NULL || target == NULL) {
return false;
}
// Check if the first 4 bytes match the magic number for "conv"
if (*(const uint32_t*)message != *(const uint32_t*)target) {
return false;
}
return true;
}
static void on_conversation_status_message_received(byte_rtc_engine_t engine, const cJSON* root) {
cJSON* stage_obj = cJSON_GetObjectItem(root, "Stage");
if (stage_obj != NULL) {
cJSON* code_obj = cJSON_GetObjectItem(stage_obj, "Code");
if (code_obj != NULL) {
printf("conversation status message, code: %d\\n", (int)cJSON_GetNumberValue(code_obj));
}
cJSON* description_obj = cJSON_GetObjectItem(stage_obj, "Description");
if (description_obj != NULL) {
printf("conversation status message, description: %s\\n", cJSON_GetStringValue(description_obj));
}
}
cJSON* task_id_obj = cJSON_GetObjectItem(root, "TaskId");
if (task_id_obj != NULL) {
printf("conversation status message, task_id: %s\\n", cJSON_GetStringValue(task_id_obj));
}
cJSON* user_id_obj = cJSON_GetObjectItem(root, "UserID");
if (user_id_obj != NULL) {
printf("conversation status message, user_id: %s\\n", cJSON_GetStringValue(user_id_obj));
}
cJSON* round_id_obj = cJSON_GetObjectItem(root, "RoundID");
if (round_id_obj != NULL) {
printf("conversation status message, round_id: %d\\n", (int)cJSON_GetNumberValue(round_id_obj));
}
cJSON* event_time_obj = cJSON_GetObjectItem(root, "EventTime");
if (event_time_obj != NULL) {
printf("conversation status message, event_time: %lld\\n", (long long)cJSON_GetNumberValue(event_time_obj));
}
cJSON* error_info_obj = cJSON_GetObjectItem(root, "ErrorInfo");
if (error_info_obj != NULL && cJSON_IsObject(error_info_obj)) {
cJSON* error_code_obj = cJSON_GetObjectItem(error_info_obj, "Code");
if (error_code_obj != NULL) {
printf("error info, code: %d\\n", (int)cJSON_GetNumberValue(error_code_obj));
}
cJSON* reason_obj = cJSON_GetObjectItem(error_info_obj, "Reason");
if (reason_obj != NULL) {
printf("error info, reason: %s\\n", cJSON_GetStringValue(reason_obj));
}
}
}
// 回调函数
static void on_message_received(byte_rtc_engine_t engine, const char* room, const char* src, const uint8_t* message, int size, bool binary) {
cJSON* root = NULL;
if (size < CONVERSATION_MAGIC_HEADER_SIZE) {
return;
}
if (!_is_target_message(message, CONVERSATION_MAGIC_STATUS_STR)) {
// 非智能体状态消息
return;
}
root = cJSON_Parse((const char*)(message + CONVERSATION_MAGIC_HEADER_SIZE));
if (NULL == root) {
return;
}
on_conversation_status_message_received(engine, root);
cJSON_Delete(root);
}
通过服务端实现
实现方式
- 配置回调：调用 StartVoiceChat 接口时，通过以下参数配置回调服务器：
- "AgentConfig": {"EnableConversationStateCallback": true, //必须设置为 true// 1. 您的回调服务地址。系统会将状态消息 POST 到这里。需满足以下要求：// - 必须为公网可访问的域名地址。若使用 HTTPS，请确保 SSL 证书合法且完整。// - 请确保该 URL 指向的服务端能够正常处理无 Content-Type 的 POST 请求。"ServerMessageURLForRTS": "https://your-server.com/example_domain/vertc/cstage",// 2. 认证密钥。由您自定义，平台只是在回调中原样返回，供您在服务端做合法性校验。"ServerMessageSignatureForRTS": "your_custom_secure_signature" }
- 接收、校验并解析回调消息。
- 接收回调消息：当 AI 状态发生变化时，配置的 URL 会收到 HTTP POST 请求，请求体格式如下：
- {"message": "Y29udgAAAKV7Cg...=","binary": true,"signature": "your_custom_secure_signature"}
- message：Base64 编码的二进制消息内容。具体格式参见二进制消息格式。
- signature：平台原样回传的签名字符串，即您在 StartVoiceChat 中配置 AgentConfig.ServerMessageSignatureForRTS。
- 校验回调签名：将 signature 的值与 AgentConfig.ServerMessageSignatureForRTS 进行比对。
- 解析消息：签名校验通过后，对 message 进行 Base64 解码，再按照二进制消息格式解析状态信息。
消息解析示例
以下 Go 语言为例，展示如何解析消息。
package main
import (
"encoding/base64"
"encoding/binary"
"encoding/json"
"fmt"
"github.com/gin-gonic/gin"
)
// --- 1. 需要您修改的配置 ---
const (
conversationStageHeader = "conv"
exampleSignature = "your_custom_secure_signature" // 替换为您在 StartVoiceChat 中配置的真实密钥
)
type RtsMessage struct {
Message string `json:"message"`
Signature string `json:"signature"`
}
type Conv struct {
TaskID string `json:"TaskId"`
UserID string `json:"UserID"`
RoundID int64 `json:"RoundID"`
EventTime int64 `json:"EventTime"`
Stage StageInfo `json:"Stage"`
}
type StageInfo struct {
Code stageCode `json:"Code"`
Description string `json:"Description"`
}
type stageCode int
const (
_ stageCode = iota
listening
thinking
answering
interrupted
answerFinish
)
var (
stageListening = StageInfo{Code: listening, Description: "listening"}
stageThinking = StageInfo{Code: thinking, Description: "thinking"}
stageAnswering = StageInfo{Code: answering, Description: "answering"}
stageInterrupted = StageInfo{Code: interrupted, Description: "interrupted"}
stageAnswerFinish = StageInfo{Code: answerFinish, Description: "answerFinish"}
)
func HandleConversationStageMsg(c *gin.Context) {
msg := &RtsMessage{}
if err := c.BindJSON(&msg); err != nil {
fmt.Printf("BindJson failed,err:%v\n", err)
return
}
if msg.Signature != exampleSignature {
fmt.Printf("Signature not match\n")
return
}
conv, err := Unpack(msg.Message)
if err != nil {
fmt.Printf("Unpack failed,err:%v\n", err)
return
}
fmt.Println(conv)
//业务逻辑
c.String(200, "ok")
}
func Unpack(msg string) (*Conv, error) {
data, err := base64.StdEncoding.DecodeString(msg)
if err != nil {
return nil, fmt.Errorf("DecodeString failed,err:%v", err)
}
if len(data) < 8 {
return nil, fmt.Errorf("Data invalid")
}
dataHeader := string(data[:4])
if dataHeader != conversationStageHeader {
return nil, fmt.Errorf("Header not match")
}
dataSize := binary.BigEndian.Uint32(data[4:8])
if dataSize+8 != uint32(len(data)) {
return nil, fmt.Errorf("Size not match")
}
subData := data[8:]
conv := &Conv{}
err = json.Unmarshal(subData, conv)
if err != nil {
return nil, fmt.Errorf("Unmarshal failed,err:%v\n", err)
}
return conv, nil
}
func main() {
r := gin.Default()
// --- 2. 需要您修改的配置 ---
// 回调路径：这里的路径 ("/example_domain/vertc/cstage") 必须与您在 StartVoiceChat 中配置的 ServerMessageURLForRTS 的路径部分完全一致。
// 例如，如果您的回调 URL 是 "https://my-service.com/api/rtc/status"，
// 那么这里的路径就必须是 "/api/rtc/status"。
r.POST("/example_domain/vertc/cstage", HandleConversationStageMsg)
r.Run()
}
解析结果示例：
&{ChatTask01 Huoshan01 16 1765787330849 {1 listening}}
附录
二进制消息格式
参数名 | 类型 | 描述 |
参数名 | 类型 | 描述 |
magic number | binary | 消息格式，固定为 conv。 |
length | binary | 消息长度，单位为 bytes。存放方式为大端序。 |
conversation_status_message | binary |
conversation_status_message
Stage
参数名 | 类型 | 描述 |
参数名 | 类型 | 描述 |
Code | Int | 状态码。
|
Description | String | 任务状态描述。 |
ErrorInfo
参数名 | 类型 | 描述 |
参数名 | 类型 | 描述 |
Code | Int | |
Reason | String | 错误详细原因。 |
最近更新时间：2026.11.05 15:12:20
这个页面对您有帮助吗？
有用
有用
无用
无用