# Webhook 事件 (/zh-CN/realtime-media/speech-to-text/reference/ncs-events) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 开通声网消息通知后,声网通知服务器以 HTTPS POST 请求方法向你的服务器发送频道事件通知回调。 数据格式为 JSON,字符编码为 UTF-8,签名算法为 HMAC/SHA1 或 HMAC/SHA256。 本页是实时转录翻译消息通知事件的参考,介绍请求结构、事件类型、字段含义和 `payload` 示例。如果你需要开通消息通知服务、配置 Webhook URL、接收回调或验证签名,请参考[接收 Webhook 事件](/zh-CN/realtime-media/speech-to-text/build/monitor-events/receive-webhook)。 ## 请求 Body [#请求-body] 消息通知回调的请求 Body 包含以下字段: | 字段 | 类型 | 描述 | | ---------- | ---------- | ----------------------------------------------------------- | | `sid` | String | 服务 ID。 | | `noticeId` | String | 通知 ID,标识来自声网业务服务器的一次事件通知。 | | `productId` | Number | 业务 ID。`20` 表示实时转录翻译业务。 | | `eventType` | Number | 通知的事件类型。详见[事件类型](#eventtype)。 | | `notifyMs` | Number | 声网消息服务器向你的服务器发送事件通知的 Unix 时间戳 (ms)。 | | `payload` | JSON Object | 通知事件的具体内容。`payload` 因 `eventType` 而异,详见[事件类型](#eventtype)。 | 消息通知回调的请求 Body 示例: ```json { "sid": "agent_id", "noticeId": "e94f5b6fd69446ea9d75da90a59ca8a2", "productId": 20, "eventType": 101, "notifyMs": 1750235972193, "payload": {...} } ``` ## 事件类型 [#事件类型] 声网消息通知服务可以通知实时转录翻译服务中的以下事件: | `eventType` | `event_name` | 触发时机 | 事件描述 | | :--- | :--- | :--- | :--- | | [101](#101) | `agent joined` | 实时转录翻译引擎加入成功时发送。 | 服务加入频道。 | | [102](#102) | `agent left` | 实时转录翻译引擎离开成功时发送。 | 服务离开频道。 | | [104](#104) | `token will expire` | 实时转录翻译引擎使用的 RTC Token 即将过期时发送。 | RTC Token 即将过期预警。 | | [200](#200) | `M3U8 file upload succeed` | 单个 M3U8 索引文件创建并上传完成时发送。若上传多个 M3U8 文件,则会多次回调。 | 单个 M3U8 索引文件上传成功。 | | [201](#201) | `transcript upload succeed` | 所有 M3U8 和 VTT 文件上传完成时发送。 | 所有 M3U8 和 VTT 文件上传成功。 | | [202](#202) | `transcript upload failed` | M3U8 或 VTT 文件上传完成,但部分或全部文件上传失败时发送。 | M3U8 或 VTT 文件上传失败。 | ### 101 agent joined [#101-agent-joined] `eventType` 为 `101` 表示服务加入频道。实时转录翻译引擎加入成功后,会发送该事件。`payload` 中包含以下字段: | 字段 | 数据类型 | 含义 | | :------------ | :------- | :-------------------------------------------------- | | `agent_id` | String | 实时转录翻译智能体 ID。 | | `start_ts` | Number | 任务创建的时间戳(毫秒)。 | | `channel` | String | 频道名称。 | `payload` 示例: ```json { "agent_id": "agent_id", "channel": "stt_ncs93369", "start_ts": 1750235971 } ``` ### 102 agent left [#102-agent-left] `eventType` 为 `102` 表示服务离开频道。实时转录翻译引擎离开成功后,会发送该事件。`payload` 中包含以下字段: | 字段 | 数据类型 | 含义 | | --- | --- | --- | | `agent_id` | String | 实时转录翻译智能体 ID。 | | `start_ts` | Number | 任务开始的时间戳(毫秒)。 | | `stop_ts` | Number | 任务结束的时间戳(毫秒)。 | | `channel` | String | 频道名称。 | | `status` | String | [ncs-events-html-0-5-2 details](#table-slot-ncs-events-html-0-5-2) | | `message` | String | [ncs-events-html-0-6-2 details](#table-slot-ncs-events-html-0-6-2) | **ncs-events-html-0-5-2 details** 任务状态: - `STOPPED`:正常停止或空闲超时。 - `FAILED`:失败。 **ncs-events-html-0-6-2 details** 表示服务退出频道的具体原因: - `OK`:服务正常退出频道。 - `Idle for too long`:由于任务长时间无活动而超时退出。 - `Task exceeded maximum lifetime`:由于任务达到最长运行时长上限而退出。 - `RTC connection error`:由于 RTC 连接异常导致退出。 - `Fatal ASR error`:ASR 模块错误导致退出。 - `Fatal Translation error`:翻译模块错误导致退出。 服务因不同原因离开频道的 `payload` 示例: ```json tab="正常停止" tabGroup="102" { "agent_id": "agent_id", "channel": "stt_ncs93369", "message": "OK", "start_ts": 1750235971, "status": "STOPPED", "stop_ts": 1750235984 } ``` ```json tab="超时退出" tabGroup="102" { "agent_id": "agent_id", "channel": "stt_ncs93369", "message": "Idle for too long", "start_ts": 1750235971, "status": "STOPPED", "stop_ts": 1750235984 } ``` ```json tab="任务运行超限" tabGroup="102" { "agent_id": "agent_id", "channel": "stt_ncs93369", "message": "Task exceeded maximum lifetime", "start_ts": 1750235971, "status": "STOPPED", "stop_ts": 1750495171 } ``` ```json tab="RTC 连接错误" tabGroup="102" { "agent_id": "agent_id", "channel": "stt_ncs93369", "message": "RTC connection error", "start_ts": 1750235971, "status": "FAILED", "stop_ts": 1750235984 } ``` ```json tab="ASR 模块错误" tabGroup="102" { "agent_id": "agent_id", "channel": "stt_ncs93369", "message": "Fatal ASR error", "start_ts": 1750235971, "status": "FAILED", "stop_ts": 1750235984 } ``` ```json tab="翻译模块错误" tabGroup="102" { "agent_id": "agent_id", "channel": "stt_ncs93369", "message": "Fatal Translation error", "start_ts": 1750235971, "status": "FAILED", "stop_ts": 1750235984 } ``` ### 104 token will expire [#104-token-will-expire] `eventType` 为 `104` 表示实时转录翻译引擎使用的 RTC Token 即将过期。当 RTC Token 距离过期还有 30 秒时,消息通知服务会向你的业务服务器发送该事件。如果 RTC Token 的有效期小于或等于 30 秒,平台不会发送该事件。`payload` 中包含以下字段: | 字段 | 数据类型 | 含义 | | :--- | :--- | :--- | | `agent_id` | String | 实时转录翻译智能体 ID。 | | `name` | String | 创建任务时传入的服务唯一标识。 | | `start_ts` | Number | 任务创建的时间戳(秒)。 | | `channel` | String | 频道名称。 | | `message` | String | RTC Token 即将过期提醒。固定值:`token will expire!`。 | `payload` 示例: ```json { "agent_id": "agent_id", "name": "agora-test", "start_ts": 1750235971, "channel": "stt_ncs93369", "message": "token will expire!" } ``` :::info[信息] `104` 事件仅用于提前通知 RTC Token 即将过期,不会触发任务结束,不会改变任务的最终状态,也不替代现有 RTC 连接错误处理链路。 ::: ### 200 M3U8 file upload succeed [#200-m3u8-file-upload-succeed] `eventType` 为 `200` 表示单个 M3U8 索引文件上传成功。单个 M3U8 索引文件创建并上传完成后,会发送该事件。若上传多个 M3U8 文件,则会多次回调。`payload` 中包含以下字段: | 字段 | 数据类型 | 含义 | | :--- | :--- | :--- | | `agent_id` | String | 实时转录翻译智能体 ID。 | | `channel` | String | 频道名称。 | | `file_name` | String | M3U8 文件名称。 | | `file_creation_ts` | Int64 | M3U8 文件创建时间的 Unix 时间戳(毫秒)。 | | `message` | String | `A 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 [#201-transcript-upload-succeed] `eventType` 为 `201` 表示所有 M3U8 和 VTT 文件上传成功。所有 M3U8 和 VTT 文件上传完成后,会发送该事件。`payload` 中包含以下字段: | 字段 | 数据类型 | 含义 | | :--- | :--- | :--- | | `agent_id` | String | 实时转录翻译智能体 ID。 | | `channel` | String | 频道名称。 | | `file_name` | String | M3U8 文件名称。 | | `file_creation_ts` | Int64 | M3U8 文件创建时间的 Unix 时间戳(毫秒)。 | | `message` | String | `STT 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 [#202-transcript-upload-failed] `eventType` 为 `202` 表示 M3U8 或 VTT 文件上传失败。M3U8 或 VTT 文件上传完成,但部分或全部文件上传失败时,会发送该事件。 | 字段 | 数据类型 | 含义 | | --- | --- | --- | | `agent_id` | String | 实时转录翻译智能体 ID。 | | `channel` | String | 频道名称。 | | `succeed_file_list` | `Array` | [ncs-events-html-1-3-2 details](#table-slot-ncs-events-html-1-3-2) | | `failed_file_list` | `Array` | [ncs-events-html-1-4-2 details](#table-slot-ncs-events-html-1-4-2) | | `message` | String | `STT transcript upload failed.`,表示存在 M3U8 或 VTT 文件上传失败。 | **ncs-events-html-1-3-2 details** 上传成功的文件列表。每个对象包含以下字段: - `file_name`:文件名称。 - `file_creation_ts`:文件创建时间的 Unix 时间戳(毫秒)。 **ncs-events-html-1-4-2 details** 上传失败的文件列表。每个对象包含以下字段: - `file_name`:文件名称。 - `file_creation_ts`:文件创建时间的 Unix 时间戳(毫秒)。 - `message`:具体失败原因。 `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." } ```