最高出价（Max Price）集成指南

1. 概述

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

在营销消息模板上设置 最高出价（Max Price） 和 国家/地区系数（Country multiplier）
在发送消息时可选应用 单条消息系数（per-message multiplier）
通过 消息状态 Webhook 获取最终扣费金额
在发送前评估不同 最高出价（Max Price） 水平下的送达量和成本

2. 核心概念

2.1 什么是最高出价（Max Price）？

最高出价是企业 愿意为每条成功送达的 WhatsApp 营销消息支付的最高金额。设置最高出价后，Meta 的送达收费将等于或低于该价格。实际扣费不会超过配置的价格上限。根据营销活动的目标，企业可以将最高出价设置为等于、低于或高于 Meta 的官方公布费率：

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

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

2.2 如何设置最高出价

2.2.1 在模板上设置最高出价 您可以为模板设置固定的最高出价（maxBid），并为不同国家或地区配置不同的系数（countryPriceAdjustments.multiplier）。例如，假设 maxBid 设置为 0.10 美元，印度系数为 0.8×，马来西亚系数为 1.3×：

使用该模板向印度发送消息时，模板级最高出价为 0.10 美元 × 0.8 = 0.08 美元。
使用该模板向马来西亚发送消息时，模板级最高出价为 0.10 美元 × 1.3 = 0.13 美元。
将该模板发送到任何其他国家/地区时，模板级最高出价为 0.10 美元。

2.2.2 发送模板消息时调整系数 使用配置了最高出价的模板发送消息时，您可以应用大于 0 的单条消息系数，以提高或降低单条消息的有效最高出价。 2.2.3 计算有效最高出价

有效最高出价 = 模板 maxBid x 模板 countryPriceAdjustments.multiplier x per_message_bid_multiplier

示例：您创建了一个模板，模板级最高出价设置如下：

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

如果有 4 位收件人，您在发送时指定了不同的单条消息系数**，** 则有效最高出价计算如下：

收件人	应用的单条消息系数	国家/地区	有效最高出价
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*******"
    }
  }'

在此示例中：

由于消息状态为 delivered 或 read，因此 totalPrice 为最终费用。
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
    }
  ]
}

解读：

当每条消息的最高限价（Max Price）为 395 / 1000 USD = USD 0.395 时，1,000 个接收者的预计送达率区间为 4.8% to 23.4%，预计费用区间约为 USD 344.46 to USD 396。
当每条消息的最高限价（Max Price）为 495 / 1000 USD = USD 0.495 时，1,000 个接收者的预计送达率区间为 6.3% to 26.3%，预计费用区间约为 USD 353.067 to USD 429.597。

常见问题

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

不能。每个接收者的送达价格是动态的，无法提前预知。企业只需设置愿意支付的最高限价（Max Price）。成功送达的消息将按其实际送达价格扣费，且不会超过生效的最高限价。

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

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

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

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

​1. 概述

​2. 核心概念

​2.1 什么是最高出价（Max Price）？

​2.2 如何设置最高出价

​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 如何设置最高出价

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

常见问题

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

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

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