Agent Instance SDK Callbacks
AI Agent provides rich status information. This status information can be obtained through the ZEGOCLOUD Express SDK experimental API callbacks, making it convenient to implement status switching UI effects on the client side, such as "listening", "thinking", "speaking" and other states.
For detailed usage instructions, refer to Display User and Agent Instance Status > Listen to ZEGOCLOUD Express SDK Experimental API Callbacks.
Features
- Real-time: Status changes can be delivered to all participants in real-time.
- Flexibility: Uses custom message format for easy integration and extension.
- Multi-state support: Includes multiple states such as listening, thinking, speaking, and being interrupted.
Message Format
The status callback custom message uses JSON format, and the status information is included in the content.msgContent field, as follows:
| Parameter | Type | Description |
|---|---|---|
| Timestamp | int64 | Second-level timestamp. |
| TimestampMs | int64 | Millisecond-level timestamp. |
| SeqId | int64 | Packet sequence number, ensures order but not continuity |
| Round | int64 | Conversation round. Increases each time the user actively speaks. Ensures order but not continuity |
| Cmd | Int | 1: User speaking status 3: Recognized ASR text 4: LLM response text (incremental delivery) 6: Agent instance status |
| Data | Object | Specific content. See Data |
Example Message
{
"method": "liveroom.room.on_recive_room_channel_message",
"params": {
"msg_content": "{\"Timestamp\":1765510379,\"TimestampMs\":1765510379113,\"SeqId\":278800715,\"Round\":510359002,\"Cmd\":1,\"Legacy\":false,\"Data\":{\"SpeakStatus\":1,\"UserId\":\"38475\"}}",
"msg_type": 1,
"roomid": "ir_20p158E0",
"send_idname": "@RBT#38475_xiaozhi-sx_174722027",
"send_nickname": ""
}
}Data
The Data structure varies depending on the Cmd value, as follows:
Cmd=1, User Speaking Status
| Parameter | Type | Description |
|---|---|---|
| SpeakStatus | int | 1: Speaking started, 2: Speaking ended |
| UserId | string | User ID of the speaker |
Example Message
{
"method": "onRecvRoomChannelMessage",
"content": {
"roomID": "wr_1765790410771",
"sendIDName": "38597_xiaozhi_437354554567",
"sendNickName": "Jack",
"msgType": 1,
"msgContent": "{\"Timestamp\":1765790413,\"TimestampMs\":1765790413102,\"SeqId\":558853066,\"Round\":790411001,\"Cmd\":1,\"Legacy\":false,\"Data\":{\"SpeakStatus\":1,\"UserId\":\"38597\"}}"
}
}Cmd=3, Recognized ASR (User Speaking) Text
| Parameter | Type | Description |
|---|---|---|
| Text | string | User speech recognition result text Each delivery contains the full recognized text (whether the sentence is complete is determined by the EndFlag), supports text correction |
| MessageId | string | Message ID. Unique for each round of ASR text messages |
| UserId | string | User ID of the speaker |
| StartFlag | bool | Start flag. true indicates that the current round of ASR text has started sending |
| EndFlag | bool | End flag. true indicates this round of ASR text has been sent completely, false indicates more recognition data will follow |
Example Message
{
"method": "onRecvRoomChannelMessage",
"content": {
"roomID": "wr_1765790410771",
"sendIDName": "38597_xiaozhi_437354554567",
"sendNickName": "Jack",
"msgType": 1,
"msgContent": "{\"Timestamp\":1765790414,\"TimestampMs\":1765790414021,\"SeqId\":558853290,\"Round\":790411001,\"Cmd\":3,\"Legacy\":false,\"Data\":{\"MessageId\":\"1036791849\",\"UserId\":\"38597\",\"Text\":\"你好。\",\"StartFlag\":false,\"EndFlag\":true}}"
}
}Cmd=4, Agent Response Text
| Parameter | Type | Description |
|---|---|---|
| Text | string | Response text, each delivery contains incremental text answer |
| MessageId | string | Message ID. Unique for each round of response text messages |
| EndFlag | bool | End flag. true indicates this round of LLM text has been sent completely. |
Example Message
{
"method": "onRecvRoomChannelMessage",
"content": {
"roomID": "wr_1765790410771",
"sendIDName": "38597_xiaozhi_437354554567",
"sendNickName": "Jack",
"msgType": 1,
"msgContent": "{\"Timestamp\":1765790415,\"TimestampMs\":1765790415245,\"SeqId\":558855367,\"Round\":790411001,\"Cmd\":4,\"Legacy\":false,\"Data\":{\"MessageId\":\"1037244923\",\"UserId\":\"38597_xiaozhi_437354554567\",\"Text\":\"你好呀！\",\"StartFlag\":true,\"EndFlag\":false}}"
}
}Cmd=6, Agent Instance Status
| Parameter | Type | Description |
|---|---|---|
| Status | int | Agent instance status. 0: Idle; 1: Listening; 2: Thinking; 3: Speaking |
| OldStatus | int | Previous agent instance status. Values have the same meaning as Status |
| Reason | string | Reason for status change. |
Example Message
{
"method": "onRecvRoomChannelMessage",
"content": {
"roomID": "wr_1765790410771",
"sendIDName": "38597_xiaozhi_437354554567",
"sendNickName": "Jack",
"msgType": 1,
"msgContent": "{\"Timestamp\":1765790414,\"TimestampMs\":1765790414022,\"SeqId\":558853069,\"Round\":0,\"Cmd\":6,\"Legacy\":false,\"Data\":{\"OldStatus\":1,\"Status\":2,\"Reason\":\"llm_begin\"}}"
}
}