voice.message.updated

使用 voice.message.updated 在您的 Webhook 端点处理此事件。

触发条件

在语音消息状态更新且状态变为 delivered 或 undelivered 时触发。配置您的 Webhook 端点时，请订阅 voice.message.updated。

语法

YCloud 会向您配置的 Webhook URL 发送 HTTP POST 请求。以下结构展示了其中一种有效负载变体。尖括号中的值为占位符；其类型列在参数下。可选字段和其他变体在下文说明。

{
  "id": "<ID>",
  "type": "voice.message.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "voice": {
    "id": "<ID>",
    "to": "<TO>",
    "status": "<STATUS>",
    "externalId": "<EXTERNAL_ID>"
  }
}

参数

在处理 JSON 请求体之前，请先验证 YCloud-Signature HTTP 请求头。参见签名验证。

事件外层结构

参数	类型	是否必填	描述
`id`	string	是	事件的唯一 ID。最小长度：`6`。最大长度：`128`。
`type`	string	是	始终为 `voice.message.updated`。
`apiVersion`	string	是	用于呈现此事件的 API 版本。
`createTime`	string (date-time)	是	创建此事件的时间，采用 RFC 3339 格式。例如 `2022-06-01T12:00:00.000Z`。

事件有效负载

参数	类型	是否必填	描述
`voice`	object	否	特定于事件的 `voice` 有效负载。

四个通用外层字段均为必填。有效负载字段取决于具体的事件变体。在每个对象表格中， 是否必填 适用于其父对象存在的情况。可选字段可省略；示例中出现并不意味着字段必填。

voice

参数	类型	是否必填	描述
`id`	string	是	对象的唯一 ID。最小长度：`6`。最大长度：`128`。
`to`	string	是	采用 E.164 格式的接收者电话号码。
`verificationCode`	string	否	要发送的验证码，4 到 6 位数字。
`language`	string	否	ISO 639 语言代码。
`regionCode`	string	否	ISO 3166-1 alpha-2 国家/地区代码。
`totalSegments`	integer (int32)	否	消息条数。语音通话始终为 1。最小值：`1`。
`totalPrice`	number (double)	否	此消息的总价格。
`currency`	string	否	价格币种。ISO 4217 货币代码。
`status`	string	否	送达状态。取值为 `accepted`、`sent`、`delivered`、`undelivered` 或 `failed` 之一。 `accepted`：系统已接受消息发送请求。 `failed`：消息未能从我们的系统发出。 `sent`：消息已从我们的系统发出。 `delivered`：我们的系统已收到指示消息已送达的送达回执。 `undelivered`：我们的系统已收到指示消息未送达的送达回执。
`errorCode`	string	否	消息无法送达时的错误代码。
`createTime`	string (date-time)	否	创建此消息的时间，采用 RFC 3339 格式。例如 `2022-03-01T12:00:00.000Z`。
`updateTime`	string (date-time)	否	此消息送达报告更新的时间，格式遵循 RFC 3339。例如：`2022-03-01T12:00:00.000Z`。
`externalId`	string	否	用于引用该对象的唯一（推荐）字符串。可以为订单号或类似标识，可用于将该对象与您的内部系统进行对账。
`callbackUrl`	string	否	送达报告 URL。您可以提供一个 URL，我们将及时向您的服务器推送更新后的状态报告。例如：https://httpbin.org/anything?tag=api. 注意：建议改用配置 Webhook 端点。
`bizType`	string	否	可以为空，也可以是 `voice` 或 `verify` 之一。默认为 `voice`。 `voice`：表示消息是通过 Voice 产品发送的。 `verify`：表示消息是通过 Verify 产品发送的。
`verificationId`	string	否	验证 ID。仅当 `bizType` 为 `verify` 时包含。

示例

以下 JSON 是传递给您的接收端的主体内容。ID、电话号码和其他账户值仅供说明使用。

{
  "id": "evt_example_voice_message_updated",
  "type": "voice.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "voice": {
    "id": "voice_12345678",
    "to": "+12025550123",
    "status": "delivered",
    "externalId": "verification_123"
  }
}

在验证签名并持久接收事件后，返回 2xx 响应。请异步处理耗时任务。

HTTP/1.1 200 OK

有关场景演练，请参阅带注释的示例。

开始使用

指南

接口

Webhook reference

voice.message.updated

触发条件

语法

参数

事件外层结构

事件有效负载

voice

示例

​触发条件

​语法

​参数

​事件外层结构

​事件有效负载

​voice

​示例

触发条件

语法

参数

事件外层结构

事件有效负载

voice

示例