> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp 消息定价接入指南

> 了解 YCloud Webhook 中的 WhatsApp 消息计费字段、扣费规则以及最终计费价格确认。

YCloud 通过 WhatsApp 消息更新 Webhook 提供单条消息计费信息。本指南介绍了订阅事件、计费字段、扣费规则以及消息价格何时最终确定。

YCloud 仅对出站 WhatsApp 消息（从您的企业发送给用户的消息）收费。入站消息是免费的。

## 1. 订阅事件

YCloud 通过 `whatsapp.message.updated` 事件发送消息状态和计费更新。您可以在 YCloud 控制台的 **开发者 → Webhook** 下进行订阅。

以下请求通过 API 创建订阅。有关端点参考，请参阅[创建 Webhook 端点](/api-reference/webhook-endpoints/create-a-webhook-endpoint)：

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://api.ycloud.com/v2/webhookEndpoints
Content-Type: application/json
X-API-Key: YOUR_YCLOUD_API_KEY
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": ["whatsapp.message.updated"],
  "status": "active"
}
```

`url` 指定了 Webhook 接收端点。事件处理和签名验证请参见 [Webhook 集成指南](/zh/api-reference/guides/api-fundamentals/configure-webhooks)。

## 2. 计费字段

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

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

其他字段请参见[检索消息](/api-reference/whatsapp-messages/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`。根据自 2026 年 10 月 1 日起生效的 [WhatsApp 定价更新](/zh/documentation/pricing-and-billing/whatsapp-pricing-and-billing)，每个商业电话号码每月可获得 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 示例](/zh/api-reference/guides/examples/webhook-examples/whatsapp-message-updated-webhook-examples)。

### 4.1 营销消息：计费

已送达的营销消息采用 `regular` 定价。示例最终金额为 `0.05 USD`。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000004",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "free_entry_point",
    "pricingCategory": "referral_conversion",
    "totalPrice": 0,
    "currency": "USD"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.