# 事件类型 (/zh-CN/ai/reference/event-types) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 开通声网消息通知后，声网通知服务器以 HTTPS POST 请求方法向你的服务器发送频道事件通知回调。 数据格式为 JSON，字符编码为 UTF-8，签名算法为 HMAC/SHA1 或 HMAC/SHA256。 本页介绍频道事件回调中返回的各事件类型及含义。 ## 请求 Header [#请求-header] 消息通知回调的请求 Header 中包含以下字段： | 字段名 | 值 | | :------------------- | :----------------------------------------------------------- | | `Content-Type` | application/json | | `Agora-Signature` | 声网用客户密钥和 HMAC/SHA1 算法生成的签名值。你需要使用客户密钥和 HMAC/SHA1 算法来验证该签名值。详见[验证签名](/zh-CN/ai/build/handle-runtime-events/webhooks#验证签名)。 | | `Agora-Signature-V2` | 声网用客户密钥和 HMAC/SHA256 算法生成的签名值。你需要使用客户密钥和 HMAC/SHA256 算法来验证该签名值。详见[验证签名](/zh-CN/ai/build/handle-runtime-events/webhooks#验证签名)。 | ## 请求 Body [#请求-body] 消息通知回调的请求 Body 包含以下字段： | 字段 | 类型 | 描述 | | :---------- | :---------- | :----------------------------------------------------------- | | `noticeId` | String | 通知 ID，标识来自声网业务服务器的一次事件通知。 | | `productId` | Number | 业务 ID。值为 `17` 表示对话式 AI 引擎业务。 | | `eventType` | Number | 通知的事件类型。详见[事件类型](#eventtype)。 | | `notifyMs` | Number | 声网消息服务器向你的服务器发送事件通知的 Unix 时间戳 (ms)。通知**重试**时该值会更新。 | | `payload` | JSON Object | 通知事件的具体内容。`payload` 因 `eventType` 而异，详见[事件类型](#eventtype)。 | 消息通知回调的请求 Body 示例： ```json { "noticeId": "2000001428:4330:107", "productId": 17, "eventType": 101, "notifyMs": 1611566412672, "payload": {...} } ``` ## 事件类型 [#事件类型] 声网消息通知服务可以通知对话式 AI 引擎服务中的以下事件： | eventType | event_name | 事件描述 | | --- | --- | --- | | [101](#101) | `agent joined` | 智能体加入频道。 | | [102](#102) | `agent left` | 智能体离开频道。 | | [103](#103) | `agent history` | [ncs-events-html-0-3-2 details](#table-slot-ncs-events-html-0-3-2) | | [104](#104) | `agent expire` | RTC Token 即将过期预警。 | | [110](#110) | `agent error` | 智能体错误。 | | [111](#111) | `agent metrics` | 智能体性能指标。 | | [112](#112) | `turns finished` | 会话结束后批量回调对话轮次数据。 | **ncs-events-html-0-3-2 details** 智能体停止后回调其储存的短期记忆（最大条数由[创建智能体](/zh-CN/api-reference/api-ref/conversational-ai/join#llm-max_history)时传入的 `llm.max_history` 参数决定，默认为 32 条），包括以下信息： - 用户和智能体对话消息 - 智能体创建和停止的时间戳 ### 101 agent joined [#101-agent-joined] `eventType` 为 `101` 表示智能体加入频道，`payload` 中包含以下字段： | 字段 | 数据类型 | 含义 | | :------------ | :------- | :-------------------------------------------------- | | `agent_id` | String | 智能体 ID。 | | `name` | String | 智能体名称。 | | `start_ts` | Number | 智能体创建并加入频道的时间戳。 | | `channel` | String | 智能体所在频道名。 | | `labels` | Object | 自定义标签。仅在创建智能体时传入了 `labels` 字段才会返回。 | `payload` 示例： ```json { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "name": "support_agent_001", "start_ts": 1737111452, "channel": "xxxxx", "labels": { "campaign_id": "test_campaign", "customer_group": "vip" } } ``` ### 102 agent left [#102-agent-left] `eventType` 为 `102` 表示智能体离开频道，`payload` 中包含以下字段： | 字段 | 数据类型 | 含义 | | :------------ | :------- | :-------------------------------------------------- | | `agent_id` | String | 智能体 ID。 | | `name` | String | 智能体名称。 | | `start_ts` | Number | 智能体创建并加入频道的时间戳。 | | `stop_ts` | Number | 智能体停止并离开频道的时间戳。 | | `channel` | String | 智能体所在频道名。 | | `status` | String | 智能体状态。 | | `message` | String | 智能体离开频道的原因。 | | `labels` | Object | 自定义标签。仅在创建智能体时传入了 `labels` 字段才会返回。 | 智能体因不同原因离开频道的 `payload` 示例： ```json tab="手动停止智能体" tabGroup="102" { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "name": "support_agent_001", "start_ts": 1737111452, "stop_ts": 1737111455, "channel": "xxxxx", "status": "STOPPED", "message": "OK" } ``` ```json tab="智能体空闲超时" tabGroup="102" { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "name": "support_agent_001", "start_ts": 1737111452, "stop_ts": 1737111455, "channel": "xxxxx", "status": "STOPPED", "message": "Idle for too long" } ``` ```json tab="任务存活超限" tabGroup="102" { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "name": "support_agent_001", "start_ts": 1737111452, "stop_ts": 1737111455, "channel": "xxxxx", "status": "STOPPED", "message": "Task lifetime limit exceeded" } ``` ```json tab="智能体出错" tabGroup="102" { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "name": "support_agent_001", "start_ts": 1737111452, "stop_ts": 1737111455, "channel": "xxxxx", "status": "FAILED", "message": "Connecting for too long" } ``` ```json tab="RTC 连接出错" tabGroup="102" { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "name": "support_agent_001", "start_ts": 1737111452, "stop_ts": 1737111455, "channel": "xxxxx", "status": "FAILED", "message": "RTC connection error" } ``` ### 103 agent history [#103-agent-history] `eventType` 为 `103` 表示用户和智能体对话的短期记忆，`payload` 中包含以下字段： | 字段 | 数据类型 | 含义 | | --- | --- | --- | | `agent_id` | String | 智能体 ID。 | | `name` | String | 智能体名称。 | | `channel` | String | 智能体所在频道名。 | | `start_ts` | Number | 智能体创建并加入频道的时间戳。 | | `stop_ts` | Number | 智能体停止并离开频道的时间戳。 | | `contents` | Array[Object] | [ncs-events-html-1-6-2 details](#table-slot-ncs-events-html-1-6-2) | | `labels` | Object | 自定义标签。仅在创建智能体时传入了 `labels` 字段才会返回。 | **ncs-events-html-1-6-2 details** 用户和智能体对话的短期记忆。包含以下字段： - `role`：消息发送角色，包括以下值： - `user`：用户。 - `assistant`：智能体。 - `content`：消息内容。 - `speech_start_ms`：用户说话或 TTS 播报开始时间戳，单位为毫秒（Unix 时间戳）。 - `speech_end_ms`：用户说话或 TTS 播报完成或被打断，单位为毫秒（Unix 时间戳）。 - `speech_algorithmic_delay`：算法处理时延，单位为毫秒。 - 仅当 `contents[].role = user` 且存在实际语音输入时返回。 - 表示音频从用户设备麦克风采集后，经过降噪、背景人声消除、声纹锁定等算法处理引入的总延迟，可用于进一步对齐云录制原始音频的时间戳。 :::info[信息] `speech_start_ms`、`speech_end_ms` 和 `speech_algorithmic_delay` 仅在 `llm.vendor = custom` 的 `103` agent history 事件中返回。 ::: `payload` 示例： 默认示例 llm.vendor = custom ```json { "agent_id": "xxxx", "name": "support_agent_001", "channel": "xxxx", "start_ts": 123, "stop_ts": 123, "contents": [ { "role": "user", "content": "hello." }, { "role": "assistant", "content": "hi, how can I help you?", } ], "labels": { "campaign_id": "test_campaign", "customer_group": "vip" } } ``` 当 `llm.vendor = custom` 时，`contents` 中的消息对象可能额外包含语音时间相关字段，示例如下： ```json { "agent_id": "xxxx", "name": "support_agent_001", "channel": "xxxx", "start_ts": 1715000000, "stop_ts": 1715000060, "contents": [ { "role": "assistant", "content": "Hello, welcome to the AI customer service. How can I help you?", "speech_start_ms": 1715000001200, // TTS 第一帧推流时刻（ms） "speech_end_ms": 1715000004800 // TTS 播报完成推算时刻（ms） }, { "role": "user", "content": "", // ASR 文本为空，但用户确实发声 "speech_start_ms": 1715000004900, // 用户实际开口时刻（ms） "speech_end_ms": 1715000005100, // 用户实际停口时刻（ms） "speech_algorithmic_delay": 120 // 算法处理时延（ms），仅 role=user，用于进一步对齐云录制原始音频时间戳 }, { "role": "user", "content": "I'd like to check the status of my package, tracking number 12345.", "speech_start_ms": 1715000005200, // 用户实际开口时刻（ms） "speech_end_ms": 1715000007600, // 用户实际停口时刻（ms） "speech_algorithmic_delay": 120 // 算法处理时延（ms），仅 role=user，用于进一步对齐云录制原始音频时间戳 }, { "role": "assistant", "content": "Your package with tracking number 12345 is currently out for delivery.", "speech_start_ms": 1715000009500, // TTS 第一帧推流时刻（ms） "speech_end_ms": 1715000013200 // 被打断时刻（ms） }, { "role": "user", "content": "[think API injected] User level: VIP" // think 类消息：无 speech_* 字段 } ], "labels": { "campaign_id": "test_campaign" } } ``` ### 104 agent expire [#104-agent-expire] `eventType` 为 `104` 表示智能体使用的 RTC Token 即将过期，`payload` 中包含以下字段： | 字段 | 数据类型 | 含义 | | :------------ | :------- | :-------------------------------------------------- | | `agent_id` | String | 智能体任务唯一 ID。 | | `name` | String | 创建任务时传入的 `name` 参数。 | | `start_ts` | Number | 任务启动时间戳。 | | `channel` | String | 智能体所在 RTC 频道名。 | | `message` | String | RTC token 即将过期提醒。固定值：`Token will expire!`。 | `payload` 示例： ```json { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "name": "support_agent_001", "start_ts": 1737111452, "channel": "xxxxx", "message": "Token will expire!" } ``` :::info[信息] 当智能体使用的 RTC Token 即将过期时，平台会主动向开发者服务器推送 `104` 事件。该事件仅用于预警，智能体不会退出频道，也不会中断服务。收到该事件后，你可以立即调用 [POST 更新智能体配置](/zh-CN/api-reference/api-ref/conversational-ai/update) 接口，并传入新的 `properties.token` 完成 Token 刷新。 ::: ### 110 agent error [#110-agent-error] `eventType` 为 `110` 表示智能体出错，`payload` 中包含以下字段： | 字段 | 数据类型 | 含义 | | --- | --- | --- | | `agent_id` | String | 智能体 ID。 | | `name` | String | 智能体名称。 | | `start_ts` | Number | 智能体创建并加入频道的时间戳。 | | `channel` | String | 智能体所在频道名。 | | `turn_id` | String | 字幕对话轮次，详见[实时字幕 API 参考](/zh-CN/ai/build/transcripts#api-参考)。 | | `errors` | Array | [ncs-events-html-2-6-2 details](#table-slot-ncs-events-html-2-6-2) | | `labels` | Object | 自定义标签。仅在创建智能体时传入了 `labels` 字段才会返回。 | **ncs-events-html-2-6-2 details** 错误信息。包含以下字段： - `module`：错误发生的模块。 - `turn_id`：字幕对话轮次。 - `code`：错误码。你可以前往错误模块对应供应商的错误码文档查看详细信息。 - `message`：错误信息。 智能体出错时返回的 `payload` 示例： default 录音开场白异常 ```json { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "name": "support_agent_001", "start_ts": 1737111452, "channel": "xxxxx", "turn_id": 2, "errors": [{"module": "llm", "turn_id":2, "code":503, "message": "Insufficient balance."}], } ``` 录音开场白下载失败、超时、格式不支持或解码失败时，也会通过 `110 agent error` 事件上报错误信息。此类错误中，`errors[].module` 为 `agent`，你可以结合 `message` 中的具体原因判断是否发生了录音开场白回退。 ```json { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "name": "outbound_voice_agent", "start_ts": 1737111452, "channel": "outbound_call_channel_001", "turn_id": 0, "errors": [ { "module": "agent", "turn_id": 0, "code": 4001, "message": "Greeting audio URL unreachable, fallback to TTS. audio_url: https://cdn.example.com/audio/welcome.mp3" } ], "labels": {} } ``` 上述 `110 agent error` 为服务端 Webhook / RTM 错误事件。如果你在创建智能体时同时开启了 `parameters.enable_error_message = true`，相关异常还会额外通过 RTM 消息错误事件下发到客户端组件的 `onMessageError` 回调中，便于你在端侧记录日志、展示错误提示或触发自定义降级逻辑。 ### 111 agent metrics [#111-agent-metrics] `eventType` 为 `111` 表示智能体性能指标，`payload` 中包含以下字段： | 字段 | 数据类型 | 含义 | | --- | --- | --- | | `agent_id` | String | 智能体 ID。 | | `name` | String | 智能体名称。 | | `start_ts` | Number | 智能体创建并加入频道的时间戳。 | | `stop_ts` | Number | 智能体停止并离开频道的时间戳。 | | `channel` | String | 智能体所在频道名。 | | `metrics` | Array[Object] | [ncs-events-html-3-6-2 details](#table-slot-ncs-events-html-3-6-2) | | `labels` | Object | 自定义标签。仅在创建智能体时传入了 `labels` 字段才会返回。 | **ncs-events-html-3-6-2 details** 性能指标数组。每个对象包含以下字段： - `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 Sentence）指标，表示从 LLM 请求开始到收到第一个完整句子的响应所经过的时间（ms）。 - `tts_ttfb`：TTS 模块的 ttfb（Time To First Byte）指标，表示从 TTS 请求开始到收到第一个字节的响应延迟时间（ms）。 `payload` 示例： ```json { "agent_id": "A42AC47Hxxxxxxxx4PK27ND25E", "name": "support_agent_001", "start_ts": 1000, "stop_ts": 1672531200, "channel": "test-channel", "metrics": [ { "turn_id": 1, "tts_ttfb": 61 }, { "turn_id": 2, "asr_ttlw": 141, "llm_ttfb": 270, "llm_ttfs": 482, "tts_ttfb": 90, }, { "turn_id": 3, "asr_ttlw": 103, "llm_ttfb": 306, "llm_ttfs": 948, "tts_ttfb": 106, } ], "labels": { "campaign_id": "test_campaign", "customer_group": "vip" } } ``` ### 112 turns finished [#112-turns-finished] `eventType` 为 `112` 表示会话结束后批量回调对话轮次数据。该事件用于在单次回调中返回当前会话的对话轮次集合，便于你在会话结束后统一进行分析、归档或离线处理。 单包 `turns` 数量阈值建议设置为 `200`。当单次回调未返回完整轮次数据时，可通过 `is_truncated` 字段判断当前回调结果是否被截断。 `payload` 中包含以下字段： | 字段 | 数据类型 | 含义 | | --- | --- | --- | | `agent_id` | String | 智能体 ID。 | | `name` | String | 智能体名称。 | | `channel` | String | 频道名。 | | `start_ts` | Number | 智能体加入频道的时间戳。 | | `stop_ts` | Number | 智能体离开频道的时间戳。 | | `total_turn_count` | Number | 该会话的对话轮次总数。 | | `is_truncated` | Boolean | 当前回调中的 `turns` 数据是否被截断。为 `true` 时表示本次回调未返回全部轮次。 | | `labels` | Object | 自定义标签。仅在创建智能体时传入了 `labels` 字段才会返回。 | | `turns` | Array[Object] | 对话轮次列表。 | | `turn_id` | Number | `turns` 数组中单个对话轮次的 ID，严格整形，频道内递增唯一标识。 | | `start` | Object | [ncs-events-html-4-11-2 details](#table-slot-ncs-events-html-4-11-2) | | `end` | Object | [ncs-events-html-4-12-2 details](#table-slot-ncs-events-html-4-12-2) | | `metrics` | Object | [ncs-events-html-4-13-2 details](#table-slot-ncs-events-html-4-13-2) | **ncs-events-html-4-11-2 details** `turns` 数组中单个对话轮次开始的相关信息。包含以下字段： - `start_at`：Unix 时间戳，精确到毫秒，UTC 时区。 - `type`：对话轮次开始类型，包括以下值： - `greeting`：问候语。 - `silence_timeout`：静音超时。 - `api_speak`：API 调用说话。 - `api_think`：API 调用思考。 - `voice_input`：语音输入。 - `metadata`：元数据对象，包含以下字段： - `speech_duration_ms`：语音时长（ms）。 - `interrupt_duration_ms`：打断时长（ms）。 **ncs-events-html-4-12-2 details** `turns` 数组中单个对话轮次结束的相关信息。包含以下字段： - `end_at`：Unix 时间戳，精确到毫秒，UTC 时区。 - `type`：对话轮次结束类型，包括以下值： - `ok`：正常结束。 - `error`：错误结束。 - `ignored`：被忽略。 - `interrupted`：被中断。 - `metadata`：元数据对象。根据 `type` 字段的不同，包含以下字段： - `ok`：包含 `playback_duration_ms`，表示语音播放时长（ms）。 - `interrupted`：包含以下字段： - `playback_duration_ms`：中断发生时，当前轮次已实际播放的 PCM 音频时长（ms），不大于 `intended_playback_duration_ms`。 - `intended_playback_duration_ms`：当前轮次中引擎已接收并计划播放的 PCM 音频总时长（ms），包含尚未播放完的排队音频。 - `caused_by`：轮次中断原因，包括以下值： - `start_of_speech`：新一条语音请求开始。 - `api_speak`：API 调用说话。 - `api_think`：API 调用思考。 - `api_interrupt`：调用打断智能体接口。 - `api_leave`：调用停止对话式智能体接口离开频道。 - `user_no_longer_present`：智能体检测不到可订阅用户。 - `ignored`：包含 `caused_by`，表示轮次忽略原因，包括以下值： - `semantic`：语义规则判断无需响应。 - `keywords`：未命中轮次开始检测关键词。 - `disable`：对话轮次检测功能设置为不可打断。 - `no_asr_result`：未识别到 ASR 结果。 - `error`：包含 `reason`，表示错误类型，可能包含以下值： - `LLM_REQUEST_ERR`：LLM 请求错误。 - `TTS_REQUEST_ERR`：TTS 请求错误。 - `INTERNAL_ERR`：内部错误。 **ncs-events-html-4-13-2 details** `turns` 数组中单个对话轮次的统计指标。包含以下字段： - `e2elatencyms`：端到端延迟（ms），代表从用户说话结束到听到智能体开口说话的延迟时间。 - `segmentedlatencyms`：分段延迟数组。数组中的每个对象包含 `name`（指标名称）和 `latency`（延迟，单位为 ms）字段。`name` 可能为： - `algorithm_processing`：算法处理时间，代表从用户说话结束的实际时间到判定出用户说话结束的延迟时间。 - `asr_ttlw`：ASR 模块的 ttlw（Time To Last Word）指标，表示从检测到用户说话结束到 ASR 输出最后一个词的延迟时间。 - `llm_ttft`：LLM 模块的 ttft（Time To First Token）指标，表示从 LLM 收到请求到输出第一个 token 的延迟时间。 - `llm_ftfs`：LLM 模块的 ftfs（First token To First Sentence）指标，表示从 LLM 输出第一个 token 到输出第一个完整句子的延迟时间。 - `tts_ttfb`：TTS 模块的 ttfb（Time To First Byte）指标，表示从 TTS 模块收到文本请求开始到 TTS 输出第一个音频字节的延迟时间。 - `transport`：网络传输延迟。目前，当用户使用 RTC Web SDK 时，不返回该指标。 `payload` 示例： ```json { "agent_id": "xxxx", "name": "support_agent_001", "channel": "xxxx", "start_ts": 1715000000000, "stop_ts": 1715000015000, "total_turn_count": 250, "is_truncated": true, "labels": { "campaign_id": "test_campaign", "customer_group": "vip" }, "turns": [ { "agent_id": "xxxx", "channel": "xxxx", "turn_id": 1, "start": { "start_at": 1774579820147, "type": "voice_input" }, "end": { "end_at": 1774579822412, "type": "ok" }, "metrics": { "e2elatencyms": 940, "segmentedlatencyms": [ {"name": "algorithm_processing", "latency": 100}, {"name": "asr_ttlw", "latency": 180}, {"name": "llm_ttft", "latency": 200}, {"name": "llm_ftfs", "latency": 60}, {"name": "tts_ttfb", "latency": 300}, {"name": "transport", "latency": 100} ] } } ] } ``` 轮次被打断时，`end` 示例： ```json { "end_at": 1774579822412, "type": "interrupted", "metadata": { "caused_by": "api_interrupt", "playback_duration_ms": 1200, "intended_playback_duration_ms": 2400 } } ```