跳转到主要内容

1. 概述

为了帮助企业更好地控制并优化其 WhatsApp 营销消息支出,YCloud 支持 Meta 于 2026 年为营销消息 API 推出的新定价功能,包括 最高出价(Max Price) 和 覆盖面预估工具(Reach Estimation Tool)。 借助 YCloud API,企业可以设置愿意为每条成功送达的 WhatsApp 营销消息支付的最高价格,并根据营销活动成本和送达目标调整其定价策略。设置最高出价后,Meta 对每条送达的消息按该价格或更低价格计费。在发送前,企业还可以使用覆盖面预估工具来了解不同最高出价水平下的预估送达量和成本。 本指南介绍如何使用 YCloud API 执行以下操作:
  1. 在营销消息模板上设置 Max Price 和 国家/地区倍数(Country multiplier)
  2. 在发送消息时,可选择应用 单条消息倍数(per-message multiplier)
  3. 通过 消息状态 Webhook 获取最终计费金额
  4. 在发送前预估不同 Max Price 水平下的送达量和成本

2. 核心概念

2.1 什么是最高出价(Max Price)?

最高出价是指 企业愿意为每条成功送达的 WhatsApp 营销消息支付的最高金额。设置最高出价后,Meta 对送达的消息按该价格或更低价格计费。实际费用不会超过所配置的价格上限。 根据营销活动的目标,企业可以将其最高出价设置为等于、低于或高于 Meta 的公开费率: 最高出价是价格上限,而非固定费用。 设置最高出价并不意味着每条送达的消息都会按该价格计费。每条消息的价格是动态计算的,可能等于或低于配置的最高出价。

2.2 如何设置最高出价

2.2.1 在模板上设置最高出价 您可以为模板设置固定的最高出价(maxBid),并为不同国家或地区配置不同的倍数(countryPriceAdjustments.multiplier)。例如,假设 maxBid 设置为 0.10 USD,印度的倍数为 0.8×,马来西亚的倍数为 1.3×:
  • 当使用该模板向印度发送消息时,模板层级的最高出价为 0.10 USD × 0.8 = 0.08 USD。
  • 当使用该模板向马来西亚发送消息时,模板层级的最高出价为 0.10 USD × 1.3 = 0.13 USD。
  • 当向任何其他国家/地区发送该模板时,模板层级的最高出价为 0.10 USD。
2.2.2 发送模板消息时调整倍数 在使用最高出价模板发送消息时,您可以应用大于 0 的单条消息倍数,以提高或降低单条消息的有效最高出价。 2.2.3 计算有效最高出价
有效最高出价 = 模板 maxBid x 模板 countryPriceAdjustments.multiplier x per_message_bid_multiplier
示例: 对于 maxBid: "0.1"(以 USD 计)的模板,印度国家倍数为 0.8,马来西亚国家倍数为 1.3,会产生以下有效价格上限: 金额均使用您的 YCloud 结算币种。未配置覆盖的国家/地区将使用 1 的乘数。省略整个消息级 bidSpec 对象即可使用单条消息乘数 1。

2.3 动态计费规则

每条成功送达的消息价格均针对其接收者动态计算:
  • 在模板上配置的 Max Price 仅代表商家愿意支付的最高金额。
  • 送达消息的最终费用是动态的;Meta 会按等于或低于该最高价格的标准收取送达费用。
  • 同一次发送中,不同的接收者其实际消息价格可能不同。
  • 未送达的消息不会产生送达费用。
  • Max Price 会影响竞价和送达机会,但并不保证消息一定送达。实际结果还可能受到实时竞价、接收者状态以及 Meta 资格检查的影响。

2.4 什么是触达预估工具?

触达预估工具可帮助商家选择合适的 Max Price。在发送前,商家可以使用预估接口查看不同 Max Price 水平下的预计送达量和成本范围,然后根据营销目标和预算选择定价策略。 预估数据仅供规划参考,不保证实际送达结果或最终账单金额。实际结果可能会受到实时竞价、接收者状态以及 Meta 资格检查的影响。

3. 推荐集成流程

  1. 发送前调用 reachEstimate,比较不同价格水平下的预估效果。
  2. 创建营销模板时,通过 bidSpec 配置模板级 Max Price。
  3. 发送消息时,可选择性传递 per_message_bid_multiplier 来为单个接收者调整 Max Price。

4. 创建带 Max Price 的模板

4.1 接口端点

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

4.2 请求参数

bidSpec 对象包含以下字段:

4.3 请求示例

4.4 规则

  • 仅 MARKETING 模板支持 Max Price。
  • maxBid 可以低于公开刊例价。金额和乘数须作为十进制字符串传递,不能使用 JSON 数字。
  • 如果省略 bidSpec,模板将使用标准公开刊例价计费。
  • 使用 bidSpec: {} 创建模板是无效的。在使用 bidSpec 创建时,请提供有效的 maxBid。

4.5 响应示例

模板创建成功后,响应中会包含模板对象及其 bidSpec 配置。

5. 添加、更新或清除 Max Price

5.1 接口端点

使用 PATCH /v2/whatsapp/templates/{wabaId}/{name}/{language} 编辑营销模板,包括创建时未设置 Max Price 的模板。

5.2 选择编辑行为

属性全为 null 的对象(例如 {"maxBid": null, "countryPriceAdjustments": null})也会清除设置。空字符串、空数组以及其他非 null 属性不算作空配置。例如,包含 {"countryPriceAdjustments": []} 但没有有效 maxBid 是无效的。 若要添加或更新 Max Price,请使用 创建带 Max Price 的模板 中的字段。请包含您希望存储的完整国家/地区列表。提交的列表将替换本地存储的列表;省略该列表或发送空列表并不会显式清除 Meta 已存储的国家/地区覆盖设置。若要移除所有竞价设置,请发送 bidSpec: {}。 包含您希望保留的每个组件。以下示例清除了出价配置并保留了正文(body):

5.3 规则

  • 添加、更新和清除 Max Price 遵循现有的模板编辑流程和 Meta 验证。只有处于 APPROVED、REJECTED 或 PAUSED 状态的模板才能被编辑。
  • 即使您仅更改定价,也请提供您希望保留的组件。成功的编辑将遵循现有的审核与状态同步流程。
  • 成功清除后,模板响应中将不再包含 bidSpec 对象。如果 Meta 或本地持久化失败,端点将返回错误。

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

6.1 端点

向任一发送端点添加消息级别的 bidSpec 对象:
  • POST /v2/whatsapp/messages/sendDirectly 同步提交消息。
  • POST /v2/whatsapp/messages 将消息加入队列以进行异步处理。
将该乘数与通过 Marketing Messages Lite 发送的 Max Price 营销模板结合使用。仅调用 sendDirectly 端点本身不会选择独立的 Utility 或 Authentication Direct Send 产品。

6.2 请求参数

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

6.3 请求示例

6.4 规则

  • per_message_bid_multiplier 必须大于 0 且最多为 999.999,最多保留三位小数。大于 1 的值会增加有效 Max Price,而介于 0 和 1 之间的值会降低它。
  • 该乘数仅适用于通过 bidSpec 启用了 Max Price 的营销模板。
  • 如果消息请求包含 bidSpec 对象,则 per_message_bid_multiplier 为必填项。与模板编辑不同,消息 bidSpec: {} 是无效的。要使用默认乘数 1,请省略整个 bidSpec 对象。

6.5 响应

发送端点继续使用标准的 WhatsApp 消息响应。传入 bidSpec 不会引入单独的响应结构。 当返回的状态为 accepted 时,totalPrice 为预估价格。在此示例中,美国接收者没有国家覆盖配置,因此 0.05 x 1 x 1.1 = 0.055 USD。请使用 delivered/read Webhook 获取最终费用。

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

7.1 Webhook 事件

当 WhatsApp 消息的状态发生变化时,YCloud 会发送 whatsapp.message.updated Webhook 事件。对于使用 Max Price 发送的消息,Webhook 会标明定价模式,并在消息送达后提供最终扣费。

7.2 Webhook payload 示例

在此示例中:
  • totalPrice 是最终扣费,因为消息状态为 delivered 或 read。
  • pricingCategory: marketing_lite_bidding 标识 Max Price 定价类别。
  • bidPricingFlag: true 确认消息是使用 Max Price 定价发送的。

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

8.1 端点

  • 端点:GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate
  • 使用场景:在发送前使用覆盖面预估端点,查看不同价格水平下的预估送达量和成本范围。

8.2 请求参数

请求示例:

8.3 响应结构

estimates 中的每一项包含:

8.4 响应示例

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