English / 简体中文
YCloud 通过 WhatsApp 消息更新 Webhook 提供逐条消息的计费信息。本文介绍相关订阅事件、价格字段、收费规则及最终价格的确认时机。
YCloud 的 WhatsApp 消息费用仅针对下行消息（企业发送给用户的消息），上行消息不收费。
1. 订阅事件
YCloud 通过 whatsapp.message.updated 事件发送消息状态及价格更新通知。该事件可在 YCloud 用户后台的 Developers → Webhook 中订阅。
通过 API 创建订阅的请求示例如下，接口说明见 Create a webhook endpoint：
POST https://api.ycloud.com/v2/webhookEndpoints
Content-Type: application/json
X-API-Key: YOUR_YCLOUD_API_KEY{
"url": "https://example.com/webhooks/ycloud",
"enabledEvents": ["whatsapp.message.updated"],
"status": "active"
}url 为 Webhook 接收地址。事件接收与验签方式见 Webhook Integration Guide。
2. 计费字段
价格信息位于回调的 whatsappMessage 对象中：
| 字段 | 说明 |
|---|---|
pricingModel | 固定为 PMP，表示按消息计费。 |
pricingType | 计费类型，标识消息的收费或免费类型。 |
pricingCategory | 消息的计费类别，例如 marketing（营销）、utility（实用）、authentication（身份验证）、service（服务）、referral_conversion（免费入口）。当 pricingType=free_entry_point 时，此字段为 referral_conversion。 |
totalPrice | YCloud 返回的该条消息金额。 |
currency | 金额的币种，例如 USD，取自租户的币种。 |
其他字段说明见 Retrieve a message。
3. 计费规则
3.1 价格确认时机
YCloud 返回的消息价格分为预估价格和最终价格，其含义由消息状态确定：
| 消息状态 | 价格含义 |
|---|---|
accepted / sent | 预估价格。 |
delivered / read | 最终价格，计费处理以此阶段返回的 totalPrice 和 currency 为准。 |
failed | 发送失败，YCloud 不收费。 |
3.2 收费与免费类型
YCloud 通过 pricingType 标识以下三种计费类型：
pricingType | 含义 |
|---|---|
regular | 常规计费类型，YCloud 返回的实际金额见 totalPrice。 |
free_customer_service | 客服窗口内的免费消息，YCloud 返回的金额为 0。根据 WhatsApp 定价更新，自 2026 年 10 月 1 日起，每个企业号码每月前 1,000 条已送达的 Service 消息免费，额度内的单聊 Service 消息仍使用此类型。 |
free_entry_point | 免费入口消息，适用 72 小时免费入口规则，pricingCategory 为 referral_conversion，YCloud 返回的金额为 0。 |
自 2026 年 10 月 1 日起，Service 免费额度按企业号码每月重置，未使用的额度不结转至下月，单聊与群聊的 Service 消息共享该额度。额度用尽后，不适用免费入口规则的单聊 Service 消息按 regular 类型计费。
同日起，客服窗口内的 Utility 模板消息不再仅因处于该窗口而免费，也不适用上述 Service 免费额度；符合免费入口条件的消息仍适用 free_entry_point。
免费入口窗口的开启条件为：用户通过 Android 或 iOS 版 WhatsApp，从 WhatsApp 直达广告或 Facebook 主页上的 WhatsApp 按钮向企业发送消息，且企业在 24 小时内回复。窗口从企业回复时起持续 72 小时；桌面版和网页版 WhatsApp 不适用该入口规则。
4. 回调数据示例
以下为单聊消息的回调片段，ID 和收费金额均为演示数据，不代表实际费率。完整载荷见 WhatsApp Message Updated Webhook Examples。
4.1 Marketing 消息：收费
已送达的 Marketing 消息按 regular 类型计费，示例最终金额为 0.05 USD。
{
"type": "whatsapp.message.updated",
"whatsappMessage": {
"id": "66eb00000000000000000001",
"status": "delivered",
"pricingModel": "PMP",
"pricingType": "regular",
"pricingCategory": "marketing",
"totalPrice": 0.05,
"currency": "USD"
}
}4.2 Service 消息：收费
自 2026 年 10 月 1 日起，企业号码当月的 1,000 条 Service 免费额度已用尽，且该消息不适用免费入口规则时，YCloud 返回 pricingType=regular，示例最终金额为 0.01 USD。
{
"type": "whatsapp.message.updated",
"whatsappMessage": {
"id": "66eb00000000000000000002",
"status": "delivered",
"pricingModel": "PMP",
"pricingType": "regular",
"pricingCategory": "service",
"totalPrice": 0.01,
"currency": "USD"
}
}4.3 Service 消息：免费额度内
自 2026 年 10 月 1 日起，消息属于企业号码当月的 1,000 条 Service 免费额度时，YCloud 返回 pricingType=free_customer_service，最终金额为 0。
{
"type": "whatsapp.message.updated",
"whatsappMessage": {
"id": "66eb00000000000000000003",
"status": "delivered",
"pricingModel": "PMP",
"pricingType": "free_customer_service",
"pricingCategory": "service",
"totalPrice": 0,
"currency": "USD"
}
}4.4 免费入口消息
消息在 72 小时免费入口窗口内送达时，YCloud 返回 pricingType=free_entry_point、pricingCategory=referral_conversion，最终金额为 0。
{
"type": "whatsapp.message.updated",
"whatsappMessage": {
"id": "66eb00000000000000000004",
"status": "delivered",
"pricingModel": "PMP",
"pricingType": "free_entry_point",
"pricingCategory": "referral_conversion",
"totalPrice": 0,
"currency": "USD"
}
}