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

Webhook 事件

更新时间不可用

查看实时转录翻译的消息通知事件类型，了解关键概念、参数说明、使用限制和接入注意事项。

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

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

本页是实时转录翻译消息通知事件的参考，介绍请求结构、事件类型、字段含义和 payload 示例。如果你需要开通消息通知服务、配置 Webhook URL、接收回调或验证签名，请参考接收 Webhook 事件。

请求 Body

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

字段类型描述
sidString服务 ID。
noticeIdString通知 ID，标识来自声网业务服务器的一次事件通知。
productIdNumber业务 ID。20 表示实时转录翻译业务。
eventTypeNumber通知的事件类型。详见事件类型。
notifyMsNumber声网消息服务器向你的服务器发送事件通知的 Unix 时间戳 (ms)。
payloadJSON Object通知事件的具体内容。payload 因 eventType 而异，详见事件类型。
表格内容超出当前宽度，可横向滚动查看更多列。

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

JSON
{
    "sid": "agent_id",
    "noticeId": "e94f5b6fd69446ea9d75da90a59ca8a2",
    "productId": 20,
    "eventType": 101,
    "notifyMs": 1750235972193,
    "payload": {...}
}

事件类型

声网消息通知服务可以通知实时转录翻译服务中的以下事件：

eventTypeevent_name触发时机事件描述
101agent joined实时转录翻译引擎加入成功时发送。服务加入频道。
102agent left实时转录翻译引擎离开成功时发送。服务离开频道。
104token will expire实时转录翻译引擎使用的 RTC Token 即将过期时发送。RTC Token 即将过期预警。
200M3U8 file upload succeed单个 M3U8 索引文件创建并上传完成时发送。若上传多个 M3U8 文件，则会多次回调。单个 M3U8 索引文件上传成功。
201transcript upload succeed所有 M3U8 和 VTT 文件上传完成时发送。所有 M3U8 和 VTT 文件上传成功。
202transcript upload failedM3U8 或 VTT 文件上传完成，但部分或全部文件上传失败时发送。M3U8 或 VTT 文件上传失败。
表格内容超出当前宽度，可横向滚动查看更多列。

101 agent joined

eventType 为 101 表示服务加入频道。实时转录翻译引擎加入成功后，会发送该事件。payload 中包含以下字段：

字段数据类型含义
agent_idString实时转录翻译智能体 ID。
start_tsNumber任务创建的时间戳（毫秒）。
channelString频道名称。
表格内容超出当前宽度，可横向滚动查看更多列。

payload 示例：

JSON
{
    "agent_id": "agent_id",
    "channel": "stt_ncs93369",
    "start_ts": 1750235971
}

102 agent left

eventType 为 102 表示服务离开频道。实时转录翻译引擎离开成功后，会发送该事件。payload 中包含以下字段：

字段数据类型含义
agent_idString实时转录翻译智能体 ID。
start_tsNumber任务开始的时间戳（毫秒）。
stop_tsNumber任务结束的时间戳（毫秒）。
channelString频道名称。
statusString

任务状态：

  • STOPPED：正常停止或空闲超时。
  • FAILED：失败。
messageString

表示服务退出频道的具体原因：

  • OK：服务正常退出频道。
  • Idle for too long：由于任务长时间无活动而超时退出。
  • Task exceeded maximum lifetime：由于任务达到最长运行时长上限而退出。
  • RTC connection error：由于 RTC 连接异常导致退出。
  • Fatal ASR error：ASR 模块错误导致退出。
  • Fatal Translation error：翻译模块错误导致退出。
表格内容超出当前宽度，可横向滚动查看更多列。

服务因不同原因离开频道的 payload 示例：

JSON
{
    "agent_id": "agent_id",
    "channel": "stt_ncs93369",
    "message": "OK",
    "start_ts": 1750235971,
    "status": "STOPPED",
    "stop_ts": 1750235984
}

104 token will expire

eventType 为 104 表示实时转录翻译引擎使用的 RTC Token 即将过期。当 RTC Token 距离过期还有 30 秒时，消息通知服务会向你的业务服务器发送该事件。如果 RTC Token 的有效期小于或等于 30 秒，平台不会发送该事件。payload 中包含以下字段：

字段数据类型含义
agent_idString实时转录翻译智能体 ID。
nameString创建任务时传入的服务唯一标识。
start_tsNumber任务创建的时间戳（秒）。
channelString频道名称。
messageStringRTC Token 即将过期提醒。固定值：token will expire!。
表格内容超出当前宽度，可横向滚动查看更多列。

payload 示例：

JSON
{
    "agent_id": "agent_id",
    "name": "agora-test",
    "start_ts": 1750235971,
    "channel": "stt_ncs93369",
    "message": "token will expire!"
}

信息

104 事件仅用于提前通知 RTC Token 即将过期，不会触发任务结束，不会改变任务的最终状态，也不替代现有 RTC 连接错误处理链路。

200 M3U8 file upload succeed

eventType 为 200 表示单个 M3U8 索引文件上传成功。单个 M3U8 索引文件创建并上传完成后，会发送该事件。若上传多个 M3U8 文件，则会多次回调。payload 中包含以下字段：

字段数据类型含义
agent_idString实时转录翻译智能体 ID。
channelString频道名称。
file_nameStringM3U8 文件名称。
file_creation_tsInt64M3U8 文件创建时间的 Unix 时间戳（毫秒）。
messageStringA STT transcript m3u8 file was successfully generated & uploaded，表示 M3U8 文件已成功生成并上传。
表格内容超出当前宽度，可横向滚动查看更多列。

payload 示例：

JSON
{
    "agent_id": "agent_id",
    "channel": "stt_ncs93369",
    "file_name": "prefix/1NT29X0TOHQVO6JL1HJE118VBLXNS4SD_agora_rtc_test.m3u8",
    "file_creation_ts": 1234567891000,
    "message": "A STT transcript m3u8 file was successfully generated & uploaded"
}

201 transcript upload succeed

eventType 为 201 表示所有 M3U8 和 VTT 文件上传成功。所有 M3U8 和 VTT 文件上传完成后，会发送该事件。payload 中包含以下字段：

字段数据类型含义
agent_idString实时转录翻译智能体 ID。
channelString频道名称。
file_nameStringM3U8 文件名称。
file_creation_tsInt64M3U8 文件创建时间的 Unix 时间戳（毫秒）。
messageStringSTT transcript upload succeeded.，表示 M3U8 和 VTT 文件已全部上传成功。
表格内容超出当前宽度，可横向滚动查看更多列。

payload 示例：

JSON
{
    "agent_id": "agent_id",
    "channel": "stt_ncs93369",
    "file_name": "prefix/1NT29X0TOHQVO6JL1HJE118VBLXNS4SD_agora_rtc_test.m3u8",
    "file_creation_ts": 1234567891000,
    "message": "STT transcript upload succeeded."
}

202 transcript upload failed

eventType 为 202 表示 M3U8 或 VTT 文件上传失败。M3U8 或 VTT 文件上传完成，但部分或全部文件上传失败时，会发送该事件。

字段数据类型含义
agent_idString实时转录翻译智能体 ID。
channelString频道名称。
succeed_file_listArray<Object>

上传成功的文件列表。每个对象包含以下字段：

  • file_name：文件名称。
  • file_creation_ts：文件创建时间的 Unix 时间戳（毫秒）。
failed_file_listArray<Object>

上传失败的文件列表。每个对象包含以下字段：

  • file_name：文件名称。
  • file_creation_ts：文件创建时间的 Unix 时间戳（毫秒）。
  • message：具体失败原因。
messageStringSTT transcript upload failed.，表示存在 M3U8 或 VTT 文件上传失败。
表格内容超出当前宽度，可横向滚动查看更多列。

payload 示例：

JSON
{
    "agent_id": "xxx",
    "channel": "xxx",
    "succeed_file_list": [
        {
            "file_name": "prefix/1NT29X0TOHQVO6JL1HJE118VBLXNS4SD_agora_rtc_test.m3u8",
            "file_creation_ts": 1234567891000
        },
        {
            "file_name": "prefix/zh-CN_1NT29X0TOHQVO6JL1HJE118VBLXNS4SD_agora_rtc_test.m3u8",
            "file_creation_ts": 1234567891001
        }
    ],
    "failed_file_list": [
        {
            "file_name": "prefix/ja-JP_1NT29X0TOHQVO6JL1HJE118VBLXNS4SD_agora_rtc_test.m3u8",
            "file_creation_ts": 1234567891001,
            "message": "last failed reason xxx"
        },
        {
            "file_name": "prefix/fr-FH_1NT29X0TOHQVO6JL1HJE118VBLXNS4SD_agora_rtc_test.m3u8",
            "file_creation_ts": 1234567891001,
            "message": "last failed reason xxx"
        }
    ],
    "message": "STT transcript upload failed."
}

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利