事件类型

开通声网消息通知后，声网通知服务器以 HTTPS POST 请求方法向你的服务器发送频道事件通知回调。数据格式为 JSON，字符编码为 UTF-8，签名算法为 HMAC/SHA1 或 HMAC/SHA256。

本页介绍频道事件回调中返回的各事件类型及含义。

请求的 Header

消息通知回调的 header 中包含以下字段：

字段名	值
Content-Type	Application/json
Agora-Signature	声网用客户密钥和 HMAC/SHA1 算法生成的签名值。你需要使用客户密钥和 HMAC/SHA1 算法来验证该签名值。详见验证签名。
Agora-Signature-V2	声网用客户密钥和 HMAC/SHA256 算法生成的签名值。你需要使用客户密钥和 HMAC/SHA256 算法来验证该签名值。详见验证签名。

请求的 Body

消息通知回调的请求包体包含以下字段：

字段	类型	描述
noticeId	String	通知 ID，标识来自声网业务服务器的一次事件通知。
productId	Number	业务 ID。值为 17 表示对话式 AI 引擎业务。
eventType	Number	通知的事件类型。详见事件类型。
notifyMs	Number	声网消息服务器向你的服务器发送事件通知的 Unix 时间戳 (ms)。通知重试时该值会更新。
payload	JSON Object	通知事件的具体内容。payload 因 eventType 而异，详见事件类型。

消息通知回调的请求包体示例：

JSON

{
    "noticeId": "2000001428:4330:107",
    "productId": 17,
    "eventType": 101,
    "notifyMs": 1611566412672,
    "payload": {...}
}

事件类型

声网消息通知服务可以通知对话式 AI 引擎服务中的以下事件：

eventType	event_name	事件描述
101	agent joined	智能体加入频道。
102	agent left	智能体离开频道。
103	agent history	智能体停止后回调其储存的短期记忆（最大条数由创建智能体时传入的 llm.max_history 参数决定，默认为 32 条），包括以下信息： 用户和智能体对话消息 智能体创建和停止的时间戳
110	agent error	智能体错误。
111	agent metrics	智能体性能指标。
201	inbound call state	呼入电话状态变化。
202	outbound call state	呼出电话状态变化。

101 agent joined

eventType 为 101 表示智能体加入频道，payload 中包含以下字段：

字段	数据类型	含义
agent_id	String	智能体 ID。
start_ts	Number	智能体创建并加入频道的时间戳。
channel	String	智能体所在频道名。

payload 示例：

JSON

{
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "start_ts": 1737111452,
    "channel": "xxxxx"
}

102 agent left

eventType 为 102 表示智能体离开频道，payload 中包含以下字段：

字段	数据类型	含义
agent_id	String	智能体 ID。
start_ts	Number	智能体创建并加入频道的时间戳。
stop_ts	Number	智能体停止并离开频道的时间戳。
channel	String	智能体所在频道名。
status	String	智能体状态。
message	String	智能体离开频道的原因。

智能体因不同原因离开频道的 payload 示例：

手动停止智能体

JSON

{
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "start_ts": 1737111452,
    "stop_ts": 1737111455,
    "channel": "xxxxx",
    "status": "STOPPED",
    "message": "OK"
}

智能体空闲超时

JSON

{
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "start_ts": 1737111452,
    "stop_ts": 1737111455,
    "channel": "xxxxx",
    "status": "STOPPED",
    "message": "Idle for too long"
}

智能体出错

JSON

{
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "start_ts": 1737111452,
    "stop_ts": 1737111455,
    "channel": "xxxxx",
    "status": "FAILED",
    "message": "Connecting for too long"
}

RTC 连接出错

JSON

{
   "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
   "start_ts": 1737111452,
   "stop_ts": 1737111455,
   "channel": "xxxxx",
   "status": "FAILED",
   "message": "RTC connection error"
}

103 agent history

eventType 为 103 表示用户和智能体对话的短期记忆，payload 中包含以下字段：

字段	数据类型	含义
agent_id	String	智能体 ID。
channel	String	智能体所在频道名。
start_ts	Number	智能体创建并加入频道的时间戳。
stop_ts	Number	智能体停止并离开频道的时间戳。
contents	Array[Object]	用户和智能体对话的短期记忆。包含以下字段： role：消息发送角色，包括以下值： user：用户。 assistant：智能体。 content：消息内容。

payload 示例：

JSON

{
    "agent_id": "xxxx",
    "channel": "xxxx",
    "start_ts": 123,
    "stop_ts": 123,
    "contents": [
        {
            "role": "user",
            "content": "hello."
        },
        {
            "role": "assistant",
            "content": "hi, how can I help you?",
        }
    ]
}

110 agent error

eventType 为 110 表示智能体出错，payload 中包含以下字段：

字段	数据类型	含义
agent_id	String	智能体 ID。
start_ts	Number	智能体创建并加入频道的时间戳。
channel	String	智能体所在频道名。
turn_id	String	字幕对话轮次，详见实时字幕 API 参考。
errors	Array	错误信息。包含以下字段： module：错误发生的模块。 turn_id：字幕对话轮次。 code：错误码。你可以前往错误模块对应供应商的错误码文档查看详细信息。 message：错误信息。

智能体因不同模块出错的 payload 示例：

LLM 模块错误

JSON

{
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "start_ts": 1737111452,
    "channel": "xxxxx",
    "turn_id": 2,
    "errors": [{"module": "llm", "turn_id":2, "code":503, "message": "Insufficient balance."}],
}

SIP 模块错误

JSON

{
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "start_ts": 1737111452,
    "channel": "xxxxx",
    "turn_id": "",
    "errors": [{"module": "sip", "turn_id": "", "code":50, "message": "Insufficient balance."}],
}

111 agent metrics

eventType 为 111 表示智能体性能指标，payload 中包含以下字段：

字段	数据类型	含义
agent_id	String	智能体 ID。
start_ts	Number	智能体创建并加入频道的时间戳。
stop_ts	Number	智能体停止并离开频道的时间戳。
channel	String	智能体所在频道名。
metrics	Array[Object]	性能指标数组。每个对象包含以下字段： turn_id：对话轮次 ID。 asr_ttlw：ASR 模块的 ttlw（Time To Last Word）指标，表示从用户说话结束到 ASR 输出最后一个词的延迟时间（ms）。 llm_ttfb：LLM 模块的 ttfb（Time To First Byte）指标，表示从 LLM 请求开始到收到第一个字节的响应延迟时间（ms）。 llm_ttfs：LLM 模块的 ttfs（Time To First Sample）指标，表示从 LLM 请求开始到收到第一个完整句子的响应所经过的时间（ms）。 tts_ttfb：TTS 模块的 ttfb（Time To First Byte）指标，表示从 TTS 请求开始到收到第一个字节的响应延迟时间（ms）。

payload 示例：

JSON

{
    "agent_id": "A42AC47Hxxxxxxxx4PK27ND25E",
    "start_ts": 1000,
    "stop_ts": 1672531200,
    "channel": "test-channel",
    "metrics": [
        {
            "turn_id": 1,
            "asr_ttlw": 503,
            "llm_ttfb": 1104
        },
        {
            "turn_id": 2,
            "asr_ttlw": 2385,
            "llm_ttfs": 392
        }
    ]
}

201 inbound call state

eventType 为 201 表示呼入电话状态变化，payload 中包含以下字段：

字段	数据类型	含义
agent_id	String	智能体 ID。
channel	String	智能体所在频道名。
state	String	呼入电话状态，包括以下值： START：收到呼叫。 ANSWERED：接听呼叫。 TRANSFERED：转接人工。 HANGUP：挂断。
report_ms	Number	状态变化的时间戳（毫秒）。

payload 示例：

JSON

{
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "channel": "xxxxx",
    "state": "START",
    "report_ms": 1737111452000
}

202 outbound call state

eventType 为 202 表示呼出电话状态变化，payload 中包含以下字段：

字段	数据类型	含义
agent_id	String	智能体 ID。
channel	String	智能体所在频道名。
state	String	呼出电话状态，包括以下值： START：呼叫开始。 CALLING：拨打电话。 RINGING：电话振铃。 ANSWERED：电话接通。 HANGUP：挂断。
report_ms	Number	状态变化的时间戳（毫秒）。

payload 示例：

JSON

{
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "channel": "xxxxx",
    "state": "CALLING",
    "report_ms": 1737111452000
}