需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

事件类型

更新时间不可用

查看对话式 AI 引擎的事件类型，了解关键概念、参数说明、使用限制和接入注意事项。

开通声网消息通知后，声网通知服务器以 HTTPS POST 请求方法向你的服务器发送频道事件通知回调。

数据格式为 JSON，字符编码为 UTF-8，签名算法为 HMAC/SHA1 或 HMAC/SHA256。

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

请求 Header

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

字段名值
Content-Typeapplication/json
Agora-Signature声网用客户密钥和 HMAC/SHA1 算法生成的签名值。你需要使用客户密钥和 HMAC/SHA1 算法来验证该签名值。详见验证签名。
Agora-Signature-V2声网用客户密钥和 HMAC/SHA256 算法生成的签名值。你需要使用客户密钥和 HMAC/SHA256 算法来验证该签名值。详见验证签名。
表格内容超出当前宽度，可横向滚动查看更多列。

请求 Body

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

字段类型描述
noticeIdString通知 ID，标识来自声网业务服务器的一次事件通知。
productIdNumber业务 ID。值为 17 表示对话式 AI 引擎业务。
eventTypeNumber通知的事件类型。详见事件类型。
notifyMsNumber声网消息服务器向你的服务器发送事件通知的 Unix 时间戳 (ms)。通知重试时该值会更新。
payloadJSON Object通知事件的具体内容。payload 因 eventType 而异，详见事件类型。
表格内容超出当前宽度，可横向滚动查看更多列。

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

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

事件类型

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

eventTypeevent_name事件描述
101agent joined智能体加入频道。
102agent left智能体离开频道。
103agent history

智能体停止后回调其储存的短期记忆（最大条数由创建智能体时传入的 llm.max_history 参数决定，默认为 32 条），包括以下信息：

  • 用户和智能体对话消息
  • 智能体创建和停止的时间戳
104agent expireRTC Token 即将过期预警。
110agent error智能体错误。
111agent metrics智能体性能指标。
112turns finished会话结束后批量回调对话轮次数据。
表格内容超出当前宽度，可横向滚动查看更多列。

101 agent joined

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

字段数据类型含义
agent_idString智能体 ID。
nameString智能体名称。
start_tsNumber智能体创建并加入频道的时间戳。
channelString智能体所在频道名。
labelsObject自定义标签。仅在创建智能体时传入了 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

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

字段数据类型含义
agent_idString智能体 ID。
nameString智能体名称。
start_tsNumber智能体创建并加入频道的时间戳。
stop_tsNumber智能体停止并离开频道的时间戳。
channelString智能体所在频道名。
statusString智能体状态。
messageString智能体离开频道的原因。
labelsObject自定义标签。仅在创建智能体时传入了 labels 字段才会返回。
表格内容超出当前宽度，可横向滚动查看更多列。

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

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

103 agent history

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

字段数据类型含义
agent_idString智能体 ID。
nameString智能体名称。
channelString智能体所在频道名。
start_tsNumber智能体创建并加入频道的时间戳。
stop_tsNumber智能体停止并离开频道的时间戳。
contentsArray[Object]

用户和智能体对话的短期记忆。包含以下字段：

  • role：消息发送角色，包括以下值：
    • user：用户。
    • assistant：智能体。
  • content：消息内容。
  • speech_start_ms：用户说话或 TTS 播报开始时间戳，单位为毫秒（Unix 时间戳）。
  • speech_end_ms：用户说话或 TTS 播报完成或被打断，单位为毫秒（Unix 时间戳）。
  • speech_algorithmic_delay：算法处理时延，单位为毫秒。
    • 仅当 contents[].role = user 且存在实际语音输入时返回。
    • 表示音频从用户设备麦克风采集后，经过降噪、背景人声消除、声纹锁定等算法处理引入的总延迟，可用于进一步对齐云录制原始音频的时间戳。

信息

speech_start_ms、speech_end_ms 和 speech_algorithmic_delay 仅在 llm.vendor = custom 的 103 agent history 事件中返回。

labelsObject自定义标签。仅在创建智能体时传入了 labels 字段才会返回。
表格内容超出当前宽度，可横向滚动查看更多列。

payload 示例：

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

eventType 为 104 表示智能体使用的 RTC Token 即将过期，payload 中包含以下字段：

字段数据类型含义
agent_idString智能体任务唯一 ID。
nameString创建任务时传入的 name 参数。
start_tsNumber任务启动时间戳。
channelString智能体所在 RTC 频道名。
messageStringRTC token 即将过期提醒。固定值：Token will expire!。
表格内容超出当前宽度，可横向滚动查看更多列。

payload 示例：

JSON
{
  "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
  "name": "support_agent_001",
  "start_ts": 1737111452,
  "channel": "xxxxx",
  "message": "Token will expire!"
}

信息

当智能体使用的 RTC Token 即将过期时，平台会主动向开发者服务器推送 104 事件。该事件仅用于预警，智能体不会退出频道，也不会中断服务。收到该事件后，你可以立即调用 POST 更新智能体配置 接口，并传入新的 properties.token 完成 Token 刷新。

110 agent error

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

字段数据类型含义
agent_idString智能体 ID。
nameString智能体名称。
start_tsNumber智能体创建并加入频道的时间戳。
channelString智能体所在频道名。
turn_idString字幕对话轮次，详见实时字幕 API 参考。
errorsArray

错误信息。包含以下字段：

  • module：错误发生的模块。
  • turn_id：字幕对话轮次。
  • code：错误码。你可以前往错误模块对应供应商的错误码文档查看详细信息。
  • message：错误信息。
labelsObject自定义标签。仅在创建智能体时传入了 labels 字段才会返回。
表格内容超出当前宽度，可横向滚动查看更多列。

智能体出错时返回的 payload 示例：

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

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

字段数据类型含义
agent_idString智能体 ID。
nameString智能体名称。
start_tsNumber智能体创建并加入频道的时间戳。
stop_tsNumber智能体停止并离开频道的时间戳。
channelString智能体所在频道名。
metricsArray[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 Sentence）指标，表示从 LLM 请求开始到收到第一个完整句子的响应所经过的时间（ms）。
  • tts_ttfb：TTS 模块的 ttfb（Time To First Byte）指标，表示从 TTS 请求开始到收到第一个字节的响应延迟时间（ms）。
labelsObject自定义标签。仅在创建智能体时传入了 labels 字段才会返回。
表格内容超出当前宽度，可横向滚动查看更多列。

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

eventType 为 112 表示会话结束后批量回调对话轮次数据。该事件用于在单次回调中返回当前会话的对话轮次集合，便于你在会话结束后统一进行分析、归档或离线处理。

单包 turns 数量阈值建议设置为 200。当单次回调未返回完整轮次数据时，可通过 is_truncated 字段判断当前回调结果是否被截断。

payload 中包含以下字段：

字段数据类型含义
agent_idString智能体 ID。
nameString智能体名称。
channelString频道名。
start_tsNumber智能体加入频道的时间戳。
stop_tsNumber智能体离开频道的时间戳。
total_turn_countNumber该会话的对话轮次总数。
is_truncatedBoolean当前回调中的 turns 数据是否被截断。为 true 时表示本次回调未返回全部轮次。
labelsObject自定义标签。仅在创建智能体时传入了 labels 字段才会返回。
turnsArray[Object]对话轮次列表。
turn_idNumberturns 数组中单个对话轮次的 ID，严格整形，频道内递增唯一标识。
startObject

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）。
endObject

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：内部错误。
metricsObject

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
    }
}

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利