> ## 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.

# Max Price 集成指南

<Note>
  此功能目前处于 Beta 测试阶段。如需申请访问权限，请联系 YCloud。
</Note>

## 1. 概述

为了帮助企业更好地掌控并优化其 WhatsApp 营销消息支出，YCloud 支持 Meta 于 2026 年为 Marketing Messages API 推出的全新定价功能，包括 **Max Price** 和 **Reach Estimation Tool（触达估算工具）**。

借助 YCloud API，企业可以设置愿意为每条成功送达的 WhatsApp 营销消息支付的最高价格，并根据活动成本和送达目标调整定价策略。设置 Max Price 后，Meta 对每条送达消息收取的费用将等于或低于该价格。在发送前，企业还可以使用触达估算工具了解在不同 Max Price 水平下的预计送达量和成本。

本指南将介绍如何使用 YCloud API 执行以下操作：

1. 在营销消息模板上设置 **Max Price** 和 **国家/地区乘数（Country multiplier）**
2. 发送消息时可选择应用 **单条消息乘数（per-message multiplier）**
3. 通过 **消息状态 Webhook 获取最终扣费**
4. 在发送前估算不同 **Max Price** 水平下的送达量和成本

## 2. 核心概念

### 2.1 什么是 Max Price？

Max Price 是企业 **愿意为每条成功送达的 WhatsApp 营销消息支付的最高金额**。设置 Max Price 后，Meta 收取的送达费用将等于或低于该价格。实际费用不会超过设定的价格上限。

根据营销活动的目标，企业可以将 Max Price 设置为等于、低于或高于 Meta 公布的费率：

| 定价策略 | 目标 | 预期结果 |
| - | - | - |
| 与公布费率相同 | 控制成本的同时保持与现有 WhatsApp 活动相当的送达率 | 在保持相似送达水平的同时可能降低成本 |
| 低于公布费率 | 以更低的成本触达合适的客户群 | 降低每条消息可接受的最高价格，但送达量可能会相应变化 |
| 高于公布费率 | 在节假日、大型促销或销售旺季提高送达率 | 提高竞争力，增加更多消息被成功送达的机会 |

**Max Price 是价格上限，而非固定费用。** 设置 Max Price 并不意味着每条送达的消息都会按该价格计费。每条消息的价格是动态计算的，可能等于或低于配置的 Max Price。

### 2.2 如何设置 Max Price

**2.2.1 在模板上设置最高价格**

您可以为模板设置固定的 Max Price（`maxBid`），并针对不同国家或地区配置不同的乘数（`countryPriceAdjustments.multiplier`）。例如，假设 `maxBid` 设置为 0.10 美元，印度的乘数为 0.8×，马来西亚的乘数为 1.3×：

* 当使用该模板向印度发送消息时，模板级别的 Max Price 为 0.10 USD × 0.8 = 0.08 USD。
* 当使用该模板向马来西亚发送消息时，模板级别的 Max Price 为 0.10 USD × 1.3 = 0.13 USD。
* 当向任何其他国家/地区发送该模板时，模板级别的 Max Price 为 0.10 USD。

**2.2.2 发送模板消息时调整乘数**

使用 Max Price 模板发送消息时，您可以应用大于 0 的单条消息乘数，以提高或降低单条消息的有效 Max Price。

**2.2.3 计算有效 Max Price**

<Note>
  有效 Max Price = 模板 maxBid x 模板 countryPriceAdjustments.multiplier x 单条消息出价乘数（per\_message\_bid\_multiplier）
</Note>

示例：

您创建了一个模板，模板级别的 Max Price 设置如下：

* maxBid：0.1 USD，
* countryPriceAdjustments.multiplier：
  * IN: 0.8x
  * MY: 1.3x

假设有 4 位收件人；您在发送时应用了不同的单条消息乘数\*\*，\*\* 有效 Max Price 的计算如下：

| 收件人 | 应用的单条消息乘数 | 国家/地区 | **有效 Max Price** |
| - | - | - | - |
| Mike | 1.2 | IN | 0.1(maxBid) x 0.8(IN 乘数) x 1.2(单条消息乘数) = 0.096 USD |
| Bob | 0.5 | MY | 0.1(maxBid) \* 1.3(**MY** 乘数) \* 0.5(单条消息乘数)= 0.065 USD |
| Jane | 0.7 | SG | 0.1(maxBid) x 1(默认倍数) x 0.7(单条消息倍数) = 0.07 USD |
| Jack | 无 | IN | 0.1(maxBid) \* 0.8(**IN** 倍数) \* 1(默认倍数)= 0.08 USD |

### 2.3 动态计费规则

每条成功送达消息的价格均针对其接收者动态计算：

* 在模板上配置的最高出价（Max Price）仅代表企业愿意支付的最高金额。
* 送达消息的最终扣费是动态的；Meta 将按该最高出价或更低的价格进行送达扣费。
* 同一批次发送中，不同接收者的实际消息价格可能有所不同。
* 未送达的消息不会产生送达费用。
* 最高出价会影响竞价和送达机会，但不能保证送达。实际结果还可能受到实时竞价、接收者状态以及 Meta 资格审查的影响。

### 2.4 什么是触达预估工具？

触达预估工具可帮助企业选择合适的最高出价。在发送之前，企业可以使用预估端点查看不同最高出价水平下的预估送达量和成本范围，然后根据其营销活动目标和预算选择定价策略。

预估数据仅供规划参考，不能保证实际送达效果或最终账单金额。实际结果可能会受到实时竞价、接收者状态和 Meta 资格审查的影响。

## 3. 推荐接入流程

1. 在发送前调用 `reachEstimate` 以比较不同价格水平下的预估表现。
2. 创建营销模板时，通过 `bidSpec` 配置模板级别的最高出价。
3. 发送消息时，可选择性传递 `per_message_bid_multiplier` 以调整单个接收者的最高出价。

## 4. 创建带最高出价的模板

### 4.1 端点

创建营销消息模板时添加 `bidSpec` 对象。

* 端点：[https://api.ycloud.com/v2/whatsapp/templates](https://api.ycloud.com/v2/whatsapp/templates)
* 使用场景：创建营销模板时设置模板级别的最高出价

### 4.2 请求参数

`bidSpec` 对象包含以下字段：

| 字段 | 类型 | 是否必填 | 说明 |
| - | - | - | - |
| `maxBid` | string | 如果提供了 `bidSpec` 则必填 | 模板允许的最高价格。币种默认为您的 YCloud 结算币种。<br /> |
| `countryPriceAdjustments` | string | 否 | 目的地国家/地区与出价倍数的映射关系。未列出的国家/地区将使用倍数 `1.0`（即未修改的 `maxBid`）。<br />最多 50 个条目。<br />最多 50 个条目。 |
| `countryPriceAdjustments.countryCode` | string | 如果提供了 `countryPriceAdjustments` 则必填 | 键必须是有效的 ISO 3166-1 alpha-2 国家/地区代码（例如 `MX`、`IN`、`BR`）。 |
| `countryPriceAdjustments.multiplier` | string | 如果提供了 `countryPriceAdjustments` 则必填 | 每个倍数必须大于 `0` 且最多为 `10`。 |

### 4.3 请求示例

```bash highlight={11-23} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  --url 'https://api.ycloud.com/v2/whatsapp/templates' \
  --header 'X-API-Key: {{YOUR_API_KEY}}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "category": "MARKETING",
    "wabaId": "{{YOUR_WABA_ID}}",
    "name": "market",
    "language": "en",
    "bidSpec": {
      "maxBid": "0.123",
      "countryPriceAdjustments": [
        {
          "countryCode": "CN",
          "multiplier": "1.9"
        },
        {
          "countryCode": "ID",
          "multiplier": "1.3"
        }
      ]
    },
    "components": [
      {
        "type": "BODY",
        "text": "Hi, Black Friday is coming!"
      }
    ]
  }'
```

### 4.4 规则

* `maxBid` 必须大于 `0`，且可以低于公开费率。
* 如果省略 `bidSpec`，模板将使用标准公开费率定价。

### 4.5 响应示例

模板创建后，响应将包含模板对象及其 `bidSpec` 配置。

```json highlight={6-18} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "officialTemplateId": "1763024734605057",
  "wabaId": "{{YOUR_WABA_ID}}",
  "name": "marketing_friday",
  "language": "en",
  "bidSpec": {
    "maxBid": "0.123",
    "countryPriceAdjustments": [
        {
          "countryCode": "CN",
          "multiplier": "1.9"
        },
        {
          "countryCode": "ID",
          "multiplier": "1.3"
        }
      ]
  },
  "messageSendTtlSeconds": -1,
  "components": [
    {
      "type": "BODY",
      "text": "Hi, Black Friday is coming!"
    }
  ],
  "category": "MARKETING",
  "status": "PENDING",
  "qualityRating": "UNKNOWN",
  "createTime": "2026-08-12T15:18:42.356Z",
  "updateTime": "2026-08-12T15:18:42.356Z",
  "ctaUrlLinkTrackingOptedOut": true
}
```

## 5. 更新模板上的最高出价

### 5.1 端点

更新营销消息模板时添加 `bidSpec` 对象。

* 端点：[https://api.ycloud.com/v2/whatsapp/templates/\{wabaId}/\{name}/\{language}](https://docs.ycloud.com/reference/whatsapp_template-edit-by-name-and-language)
* 使用场景：调整最高出价

### 5.2 请求参数与示例

请参阅 [创建带最高出价的模板](#4-create-a-template-with-max-price)

## 4. 创建带最高出价的模板

### 5.3 规则

* 您不能向创建时未包含 `bidSpec` 的现有模板添加该字段。您必须创建一个包含 `bidSpec` 的新模板。
* **已审核通过的模板**：每小时最多编辑 100 次，每天最多编辑 2,400 次。内容编辑仍遵循每天 1 次、每 30 天 10 次的现有上限。
* **已拒绝或已暂停的模板**：编辑次数无限制

## 6. 发送消息时设置单条消息出价倍数

### 6.1 端点

直接发送消息时添加 `bidSpec` 对象。

* 端点：[https://api.ycloud.com/v2/whatsapp/messages/sendDirectly](https://api.ycloud.com/v2/whatsapp/messages/sendDirectly)
* 使用场景：调整单个接收者的实际有效最高出价

### 6.2 请求参数

消息级别的 `bidSpec` 对象包含以下字段：

| 字段 | 类型 | 是否必填 | 说明 |
| - | - | - | - |
| `per_message_bid_multiplier` | string | 条件必填 | 应用于该消息模板级有效最高价格（Max Price）的乘数。必须大于 0 且最多支持三位小数。如果请求中包含 `bidSpec`，则此字段为必填项。若要使用默认乘数 `1`，请省略整个 `bidSpec` 对象。 |

### 6.3 请求示例

```bash highlight={8-9} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  --url 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
  --header 'X-API-Key: {{YOUR_API_KEY}}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "template",
    "bidSpec": {
      "per_message_bid_multiplier": "1.2"
    },
    "template": {
      "language": {
        "code": "en"
      },
      "name": "marketing_friday"
    },
    "from": "+1555*****",
    "to": "+62*****"
  }'
```

### 6.4 规则

* `per_message_bid_multiplier` 必须大于 0 且最多支持三位小数。大于 1 的值会提高有效最高价格（Max Price），而介于 0 和 1 之间的值会降低它。

* 该乘数仅适用于通过 `bidSpec` 启用了最高价格（Max Price）的营销模板。

* 如果消息请求包含 `bidSpec` 对象，则 `per_message_bid_multiplier` 为必填项。若要使用默认乘数 `1`，请省略整个 `bidSpec` 对象。

### 6.5 响应

发送端点继续使用标准 WhatsApp 消息响应。传递 `bidSpec` 不会引入单独的响应结构。

当返回的状态为 `accepted` 时，`totalPrice` 是预估价格，而非最终扣费。

```json highlight={18} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "6a7c922697330900cf11ca2f",
  "wamid": "wamid.HBgNODYxNTA2NzExMDI0NBUCABEYEkE1REJGMkIzOTMwQ0VENUIyMAA=",
  "status": "accepted",
  "from": "+1555*****",
  "to": "+62*****",
  "wabaId": "{{YOUR_WABA_ID}}",
  "type": "template",
  "template": {
    "name": "marketing_friday",
    "language": {
      "code": "en"
    }
  },
  "createTime": "2026-08-12T15:32:54.571Z",
  "updateTime": "2026-08-12T15:32:55.228Z",
  "totalPrice": 0.1845,
  "pricingCategory": "marketing_lite_bidding",
  "currency": "USD",
  "regionCode": "ID",
  "bizType": "whatsapp"
}
```

## 7. 最终扣费与消息状态 Webhook

### 7.1 Webhook 事件

当 WhatsApp 消息的状态发生变化时，YCloud 会发送 `whatsapp.message.updated` Webhook 事件。对于使用最高价格（Max Price）发送的消息，Webhook 会标识计费模式，并在消息送达后提供最终扣费。

| 字段 | 新增字段/值 | 描述 |
| - | - | - |
| `bidPricingFlag` | 新增字段 | 布尔值。`true` 表示消息是使用最高价格（Max Price）计费发送的；`false` 表示标准公开费率计费 |
| `pricingCategory` | 新增值 | 最高价格（Max Price）营销消息使用 `marketing_lite_bidding` |
| `totalPrice` | 现有字段 | 动态消息价格。不同收件人的值可能有所不同。当消息状态为 `delivered` 或 `read` 时，它将成为最终扣费 |

### 7.2 Webhook 载荷示例

```bash highlight={28-30} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "evt_6a7d30d9c038963ead5945f3",
    "type": "whatsapp.message.updated",
    "apiVersion": "v2",
    "createTime": "2026-08-13T02:50:01.057Z",
    "whatsappMessage": {
      "id": "6a7d30c92733962aed9f0fda",
      "wamid": "wamid.HBgLNTE5OTc5NTMwOTQVAgARGBI5MUJBNTE0Qjk4Q0E5NTIzMDgA",
      "status": "read",
      "from": "+1555***",
      "to": "+62***",
      "wabaId": "{{YOUR_WABA_ID}}",
      "recipient": "ID.12*******",
      "type": "template",
      "template": {
        "name": "marketing_friday",
        "language": {
          "code": "en"
        },
        "components": []
      },
      "createTime": "2026-08-13T02:49:45.403Z",
      "sendTime": "2026-08-13T02:49:50.000Z",
      "deliverTime": "2026-08-13T02:49:50.000Z",
      "readTime": "2026-08-13T02:50:00.000Z",
      "totalPrice": 0.0703,
      "pricingCategory": "marketing_lite_bidding",
      "bidPricingFlag": true,
      "pricingType": "regular",
      "pricingModel": "PMP",
      "currency": "USD",
      "regionCode": "ID",
      "bizType": "whatsapp",
      "recipientUserId": "ID.12*******"
    }
  }'
```

在此示例中：

* `totalPrice` 是最终扣费，因为消息状态为 `delivered` 或 `read`。
* `pricingCategory: marketing_lite_bidding` 标识最高价格（Max Price）计费类别。
* `bidPricingFlag: true` 确认消息是使用最高价格（Max Price）计费发送的。

## 8. 发送前预估送达率与成本

### 8.1 端点

* 端点：`GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate`
* 使用场景：在发送前使用触达预估端点，查看不同价格水平下的预估送达率和成本范围。

### 8.2 请求参数

| 参数 | 类型 | 必填 | 描述 |
| - | - | - | - |
| `wabaId` | string | 是 | WhatsApp 商业账户 ID |
| `targetCountry` | string | 是 | 目标国家/地区代码。键必须是有效的 ISO 3166-1 alpha-2 国家/地区代码（例如 `MX`、`IN`、`BR`）.. 键必须是有效的 ISO 3166-1 alpha-2 国家/地区代码（例如 `MX`、`IN`、`BR`）。 |
| `dateInterval` | string | 否 | 用于生成预估的历史数据回溯期。可选值之一：`L1D`（过去 1 天）、`L7D`（过去 7 天）、`L14D`（过去 14 天）、`L28D`（过去 28 天）。<br />默认值 `L28D` |

请求示例：

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate?targetCountry=MX&dateInterval=L7D
```

### 8.3 响应结构

| 字段 | 类型 | 描述 |
| - | - | - |
| `waba_currency` | string | WABA 的币种 |
| `estimates` | array | 预估价格水平列表 |
| `dateInterval` | string | 用于生成预估的历史数据回溯期 |

`estimates` 中的每项包含：

| 字段 | 类型 | 描述 |
| - | - | - |
| `bid_amount` | number | 企业愿意为每批 1,000 个收件人支付的最高金额 |
| `users` | number | 目标收件人数量；目前固定为 `1000` |
| `deliveries_lower_bound` | string | 每 1,000 个收件人的预估最低送达消息数 |
| `deliveries_upper_bound` | string | 每 1,000 个收件人的预估最高送达消息数 |
| `cost_lower_bound` | number | 该批次的预估最低成本 |
| `cost_upper_bound` | number | 该批次的预估最高成本 |

### 8.4 响应示例

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "waba_currency": "USD",
  "dateInterval": "L7D",
  "estimates": [
    {
      "bid_amount": 395,
      "users": 1000,
      "deliveries_lower_bound": 48,
      "deliveries_upper_bound": 234,
      "cost_lower_bound": 344.46,
      "cost_upper_bound": 396
    },
    {
      "bid_amount": 495,
      "users": 1000,
      "deliveries_lower_bound": 63,
      "deliveries_upper_bound": 263,
      "cost_lower_bound": 353.067,
      "cost_upper_bound": 429.597
    }
  ]
}
```

结果说明：

1. 当每条消息的最高价格为 `395 / 1000 USD = USD 0.395` 时，1,000 位接收者的预估送达率范围为 `4.8% to 23.4%`，预估费用范围约为 `USD 344.46 to USD 396`。
2. 当每条消息的最高价格为 `495 / 1000 USD = USD 0.495` 时，1,000 位接收者的预估送达率范围为 `6.3% to 26.3%`，预估费用范围约为 `USD 353.067 to USD 429.597`。

## 常见问题

### 我可以在发送前知道特定接收者的实际送达价格吗？

不能。每个接收者的送达价格是动态的，无法提前获知。商家只需设置愿意支付的最高价格即可。成功送达的消息将按其实际送达价格计费，且不会超过生效的最高价格。

### 为什么实际送达结果与预估不同？

预估接口仅提供参考值。实际结果可能会受到实时竞价、接收者状态以及 Meta 资格审查的影响。如果差异显著，请联系 YCloud 寻求支持。

### 消息送达后会返回实际费用吗？

会。当消息状态为 `delivered` 或 `read` 时，`totalPrice` 表示基于接收者实际送达价格计算出的最终费用。当消息最初被受理或其状态为 `sent` 时，YCloud 返回的是预估价格而非最终费用。


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