sms.message.updated

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

触发条件

当 SMS 消息状态发生更新且状态变更为 delivered 或 undelivered 时触发。在您配置 Webhook 端点时订阅 sms.message.updated。

语法

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

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

参数

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

事件外层封装

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

事件有效载荷

参数	类型	是否必填	描述
`sms`	object	否	特定于事件的 `sms` 载荷。

四个通用的外层封装字段为必填项。Payload 字段取决于事件变体。在每个对象表格中， 是否必填 仅在其父对象存在时适用。可选字段可以省略；示例并不代表字段是必填的。

sms

参数	类型	是否必填	描述
`id`	string	是	对象的唯一标识。最小长度：`6`。最大长度：`128`。
`to`	string	是	采用 E.164 格式的接收者电话号码。
`text`	string	否	此消息的文本内容。
`senderId`	string	否	所使用的 Sender ID。
`regionCode`	string	否	ISO 3166-1 alpha-2 国家/地区代码
`totalSegments`	integer (int32)	否	消息分段数。更多信息请参见 SMS 字符编码。最小值：`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 Endpoints。
`bizType`	string	否	可以为空，也可以是 `sms` 或 `verify` 之一。默认值为 `sms`。 `sms`：表示消息通过 SMS 产品发送。 `verify`: 表示消息通过 Verify 产品发送。
`verificationId`	string	否	验证 ID。仅当 `bizType` 为 `verify` 时包含。

示例

以下 JSON 是传递给接收方的请求体。其中的 ID、电话号码以及其他账户数值仅作示例说明。

{
  "id": "evt_example_sms_message_updated",
  "type": "sms.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "sms": {
    "id": "sms_12345678",
    "to": "+12025550123",
    "status": "delivered",
    "externalId": "order_123"
  }
}

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

HTTP/1.1 200 OK

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

开始使用

指南

接口

Webhook reference

触发条件

语法

参数

事件外层封装

事件有效载荷

sms

示例

​触发条件

​语法

​参数

​事件外层封装

​事件有效载荷

​sms

​示例

触发条件

语法

参数

事件外层封装

事件有效载荷

sms

示例