Max Price 集成指南

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

1. 概述

为了帮助企业更好地掌控并优化其 WhatsApp 营销消息支出，YCloud 支持 Meta 于 2026 年为 Marketing Messages API 推出的全新定价功能，包括 Max Price 和 Reach Estimation Tool（触达估算工具）。借助 YCloud API，企业可以设置愿意为每条成功送达的 WhatsApp 营销消息支付的最高价格，并根据活动成本和送达目标调整定价策略。设置 Max Price 后，Meta 对每条送达消息收取的费用将等于或低于该价格。在发送前，企业还可以使用触达估算工具了解在不同 Max Price 水平下的预计送达量和成本。本指南将介绍如何使用 YCloud API 执行以下操作：

在营销消息模板上设置 Max Price 和 国家/地区乘数（Country multiplier）
发送消息时可选择应用 单条消息乘数（per-message multiplier）
通过 消息状态 Webhook 获取最终扣费
在发送前估算不同 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

有效 Max Price = 模板 maxBid x 模板 countryPriceAdjustments.multiplier x 单条消息出价乘数（per_message_bid_multiplier）

示例：您创建了一个模板，模板级别的 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. 推荐接入流程

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

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

4.1 端点

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

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

4.2 请求参数

bidSpec 对象包含以下字段：

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

4.3 请求示例

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 配置。

{
  "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}
使用场景：调整最高出价

5.2 请求参数与示例

请参阅创建带最高出价的模板

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

5.3 规则

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

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

6.1 端点

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

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

6.2 请求参数

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

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

6.3 请求示例

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 是预估价格，而非最终扣费。

{
  "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 载荷示例

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 天）。默认值 `L28D`

请求示例：

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 响应示例

{
  "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
    }
  ]
}

结果说明：

当每条消息的最高价格为 395 / 1000 USD = USD 0.395 时，1,000 位接收者的预估送达率范围为 4.8% to 23.4%，预估费用范围约为 USD 344.46 to USD 396。
当每条消息的最高价格为 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 返回的是预估价格而非最终费用。

​1. 概述

​2. 核心概念

​2.1 什么是 Max Price？

​2.2 如何设置 Max Price

​2.3 动态计费规则

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

​3. 推荐接入流程

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

​4.1 端点

​4.2 请求参数

​4.3 请求示例

​4.4 规则

​4.5 响应示例

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

​5.1 端点

​5.2 请求参数与示例

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

​5.3 规则

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

​6.1 端点

​6.2 请求参数

​6.3 请求示例

​6.4 规则

​6.5 响应

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

​7.1 Webhook 事件

​7.2 Webhook 载荷示例

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

​8.1 端点

​8.2 请求参数

​8.3 响应结构

​8.4 响应示例

​常见问题

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

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

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

1. 概述

2. 核心概念

2.1 什么是 Max Price？

2.2 如何设置 Max Price

2.3 动态计费规则

2.4 什么是触达预估工具？

3. 推荐接入流程

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

4.1 端点

4.2 请求参数

4.3 请求示例

4.4 规则

4.5 响应示例

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

5.1 端点

5.2 请求参数与示例

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

5.3 规则

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

6.1 端点

6.2 请求参数

6.3 请求示例

6.4 规则

6.5 响应

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

7.1 Webhook 事件

7.2 Webhook 载荷示例

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

8.1 端点

8.2 请求参数

8.3 响应结构

8.4 响应示例

常见问题

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

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

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