WhatsApp 消息定价接入指南

YCloud 通过 WhatsApp 消息更新 Webhook 提供单条消息计费信息。本指南介绍了订阅事件、计费字段、扣费规则以及消息价格何时最终确定。 YCloud 仅对出站 WhatsApp 消息（从您的企业发送给用户的消息）收费。入站消息是免费的。

1. 订阅事件

YCloud 通过 whatsapp.message.updated 事件发送消息状态和计费更新。您可以在 YCloud 控制台的 开发者 → Webhook 下进行订阅。以下请求通过 API 创建订阅。有关端点参考，请参阅创建 Webhook 端点：

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 集成指南。

2. 计费字段

计费信息包含在回调的 whatsappMessage 对象中：

字段	描述
`pricingModel`	始终为 `PMP`，表示按消息计费。
`pricingType`	消息的计费或免费定价类型。
`pricingCategory`	消息的计费类别，例如 `marketing`、`utility`、`authentication`、`service` 或 `referral_conversion`（免费入口点）。当为 `pricingType=free_entry_point` 时，此字段为 `referral_conversion`。
`totalPrice`	YCloud 为此消息报告的金额。
`currency`	金额的币种，例如 `USD`，取自租户的币种设置。

其他字段请参见检索消息。

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`。根据自 2026 年 10 月 1 日起生效的 WhatsApp 定价更新，每个商业电话号码每月可获得 1,000 条免费送达的服务消息。该额度内的一对一服务消息将继续使用此计费类型。
`free_entry_point`	受 72 小时免费切入点规则涵盖的免费切入点消息。其 `pricingCategory` 为 `referral_conversion`，且 YCloud 报告的金额为 `0`。

自 2026 年 10 月 1 日起，每个商业电话号码的服务配额每月重置。未使用的配额不会结转，且一对一服务消息与群组服务消息共用同一配额。配额用尽后，一对一服务消息将按 regular 定价计费，除非适用免费入口点规则。自同一日期起，客服窗口内的效用类模板将不再仅仅因为窗口处于开启状态而免费，也不再计入服务额度中。符合免费入口点计费条件的消息将继续使用 free_entry_point。当用户在 Android 或 iOS 版 WhatsApp 上通过点击跳转至 WhatsApp 的广告（Click to WhatsApp Ads）或 Facebook 公共主页上的 WhatsApp 按钮向商家发送消息，且商家在 24 小时内进行了回复时，即可开启免费入口点窗口。该窗口从商家回复之时起持续 72 小时。WhatsApp 桌面端和网页端客户端不适用于此入口点规则。

4. Webhook 负载示例

以下回调摘要代表一对一消息。ID 和扣费金额仅用于说明，并非实际费率报价。有关完整的有效载荷，请参阅 WhatsApp 消息更新 Webhook 示例。

4.1 营销消息：计费

已送达的营销消息采用 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 服务消息：计费

自 2026 年 10 月 1 日起，当商业电话号码用尽每月 1,000 条免费服务消息的额度，且该消息不符合免费接入点计费条件时，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 服务消息：在免费额度内

自 2026 年 10 月 1 日起，对于包含在商业电话号码每月 1,000 条免费服务消息额度内的消息，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"
  }
}

开始使用

指南

接口

Webhooks

WhatsApp 消息定价接入指南

1. 订阅事件

2. 计费字段

3. 定价规则

3.1 价格确定性

3.2 计费与免费计费类型

4. Webhook 负载示例

4.1 营销消息：计费

4.2 服务消息：计费

4.3 服务消息：在免费额度内

4.4 免费入口点消息

​1. 订阅事件

​2. 计费字段

​3. 定价规则

​3.1 价格确定性

​3.2 计费与免费计费类型

​4. Webhook 负载示例

​4.1 营销消息：计费

​4.2 服务消息：计费

​4.3 服务消息：在免费额度内

​4.4 免费入口点消息

1. 订阅事件

2. 计费字段

3. 定价规则

3.1 价格确定性

3.2 计费与免费计费类型

4. Webhook 负载示例

4.1 营销消息：计费

4.2 服务消息：计费

4.3 服务消息：在免费额度内

4.4 免费入口点消息