跳转到主要内容

功能简介

WhatsApp Messages API 用于通过已连接的 WhatsApp 商业电话号码发送模板、文本、图片、视频、音频、文档、贴纸、位置、交互式、联系人和反应消息。

准备工作

  • 将您的 YCloud API 密钥存入 YCLOUD_API_KEY。
  • 将 WhatsApp 商业账户和电话号码连接至 YCloud。
  • 收集采用 E.164 格式的发送方电话号码,以及接收方电话 号码、BSUID 或父级 BSUID。
  • 常规模板发送请使用 APPROVED 模板。
  • 若消息引用了 YCloud 媒体 ID,请先上传媒体。

工作原理

根据 YCloud 应在何时将消息提交至 WhatsApp Business API 来选择端点。 两个端点均返回 YCloud 消息对象。初始响应并不确认最终送达。后续状态变更将通过 whatsapp.message.updated Webhook 送达。

发送您的第一条消息

选择已连接 WABA 所拥有的已获批模板。将发送方、接收方、模板名称和语言替换为您自己的值,然后发送:
保存返回的 id 并关注其 whatsapp.message.updated 事件。accepted 响应表示请求已进入处理流程,并不意味着客户已接收。当您需要跟踪送达情况和接收回复时,请同时配置 whatsapp.message.updated 和 whatsapp.inbound_message.received。

选择模板消息或会话消息

在客户服务窗口之外发送常规商家发起的沟通时,请使用已获批的模板。在开启的窗口期内,可以使用受支持的自由格式消息类型,例如文本、媒体或交互式回复。 在发送时检查 客户服务窗口规则。计费窗口不能替代消息发送资格。有关当前费用和接入点条件,请参阅 WhatsApp 定价。

实用和验证内容的直接发送

直接发送支持企业主动发起的实用型和身份验证类消息,无需先创建消息模板。YCloud 也支持转换现有的实用型模板。直接发送可与任一发送端点配合使用。sendDirectly 端点控制同步提交;它本身不会启用直接发送。对于身份验证,直接发送接受文本或显式交互式 OTP 按钮。身份验证模板无法转换为直接发送消息。 遵循 Direct Send 最佳实践,了解资格要求、请求、模板转换、限制和账户事件。

选择最佳发送时间

使发送时间与消息目的以及接收方的本地时间相匹配。
  • 立即发送 OTP 和其他时效性消息。当您的工作流需要 在继续之前获得提交结果时,请使用 POST /whatsapp/messages/sendDirectly 。
  • 在相关事件发生时发送事务性动态,例如付款、 物流或预约变更。
  • 将营销消息安排在接收方时区的合理时段。 利用您自己的送达率、阅读率和转化率数据为每个受众群体测试不同的时间段, 而不是假定存在一个通用的最佳时间段。
  • 先对小规模接收方群体启动定时活动。在向其余受众发送之前, 检查送达、回复和退订结果。
  • 当消息延迟时,避免重复发送。在决定是否重试之前,请保存 externalId 并处理 whatsapp.message.updated Webhook。

请求

对于最高价格(Max Price)营销模板,任一发送端点均接受 bidSpec.per_message_bid_multiplier。省略整个 bidSpec 对象将使用乘数 1。有关国家/地区乘数、出价上限和最终费用 Webhook,请参阅 Max Price 集成指南。 选择上述任一端点,然后使用与消息类型匹配的请求体。from 值为您已连接的 WhatsApp 商业电话号码。使用 E.164 格式的 to 或设置为 BSUID 或父级 BSUID 的 recipient 来指定接收方。

通用请求字段

filterUnsubscribed 和 filterBlocked 仅适用于 POST /whatsapp/messages;它们不适用于 sendDirectly。筛选后的 已排队的消息失败并返回 RECIPIENT_UNSUBSCRIBED,或 RECIPIENT_IN_BLOCK_LIST 在其状态 Webhook 中。对于同步发送, 在你的应用中强制执行同意、退订和屏蔽检查。
请至少提供 to 或 recipient 中的一项。如果同时包含两者,YCloud 将使用 to 并忽略 recipient。
一键、零点击和复制验证码认证模板需要电话号码 号码。显式 Direct Send OTP 也需要电话号码:使用 to,而不是 仅使用 recipient。

用于 OTP 的显式认证直接发送

Meta 正在逐步推出 Authentication Direct Send,目前处于 Alpha 阶段。发送方 WABA 必须 具备通过 Authentication Direct Send 发送交互式 OTP 的权限。纯文本 Authentication Direct Send 请求成功,并不能证明该 WABA 已有使用 OTP 按钮的权限。
使用相同的请求体,通过 POST /v2/whatsapp/messages/sendDirectly 进行同步提交,或通过 POST /v2/whatsapp/messages 进行排队提交。将 type 设置为 interactive,将 category 设置为 authentication,将 interactive.type 设置为 button,并提供恰好一个带有 type: "otp" 的按钮。将 interactive.action.buttons[0].otp.code 设置为由 4–10 个 ASCII 字母或数字组成的字符串。在 interactive.body.text 中将同一验证码作为独立值包含在内。 在 iOS 26 及更高版本中,复制验证码消息和一键消息可为 4–8 位数字验证码提供键盘建议。必须在收件人设备上启用 WhatsApp 通知和安全码自动填充。这不需要额外的 iOS 应用集成;零点击仍仅适用于 Android。请参阅 Meta 的 OTP 体验。 复制代码:
一键自动填充:
零点击自动填充:
对于一键式和零点击式,请提供 1–5 个具有唯一包名的 Android 应用,并为每个应用提供 11 个字符的签名密钥哈希。将示例包名和哈希替换为您应用的值。包名最多可包含 224 个字符,并且必须至少有两个以点分隔的段;每个段以字母开头,且仅包含字母、数字或下划线。在请求验证码之前,请配置您应用的 WhatsApp OTP 握手。有关设置和设备要求,请参阅 Meta 的 OTP 体验指南。 在每个零点击请求中将 zero_tap_terms_accepted 设置为 true,以代表您的企业确认 Meta 零点击条款。对于一键和复制代码,请省略该字段。对于 复制代码,还需省略 supported_apps 和 autofill_text。 按钮的可选字段 text 和 autofill_text 限制为 25 个字符,且不得为空,也不得包含变量、换行符、格式、URL 或表情符号。code_expiration_minutes 指定验证码过期时间,范围为 1–90 分钟(Meta 默认为 10)。你的应用仍必须验证验证码并强制执行其过期时间。单独的 ttlSeconds 字段控制消息投递有效期:Authentication Direct Send 接受 30–900 秒,默认值为 600 秒。请参阅 Direct Send TTL 限制。 查看 whatsapp.message.updated 以了解送达状态,并在符合条件的设备上验证自动填充。仅凭消息已送达并不能确认自动填充握手已成功。

请求示例

添加模板变量

将模板名称、语言和参数顺序与已批准的模板保持一致。 对于包含客户姓名和订单参考参数的正文,发送:
请参阅 消息模板示例 了解其他组件和消息类型。

回复特定消息

将 context.message_id 设置为原始 WhatsApp 消息 ID(wamid),以创建引用回复。仍需检查客服窗口是否处于开启状态。

应用退订和屏蔽过滤条件

对于 POST /whatsapp/messages,当需要应用 YCloud 抑制列表时,请设置 filterUnsubscribed: true 和 filterBlocked: true。两者均默认为 false,且不适用于 sendDirectly。 在状态 Webhook 中检查 whatsappMessage.errorCode,以查找 RECIPIENT_UNSUBSCRIBED 或 RECIPIENT_IN_BLOCK_LIST。不要期望出现单独的 filtered 状态。在使用 sendDirectly 之前,请在应用中执行屏蔽。 使用 externalId 将消息与订单或其他内部记录关联。 它是关联字段,而不是服务器端幂等键。

响应

成功的响应会返回 YCloud 消息对象。初始的 status: accepted 表示 YCloud 已接受该发送请求。这并不表示消息已由 Meta 发送或已送达 WhatsApp 用户。

示例响应

响应字段

送达状态

订阅 whatsapp.message.updated Webhook 以接收后续状态变更,例如 sent、failed、delivered 或 read。 当您需要直接获取消息时,请使用 GET /whatsapp/messages/{id}。
对于媒体消息,请先使用 POST /whatsapp/media/{phoneNumber}/upload 上传文件,然后在消息载荷中使用返回的媒体 ID。

限制与故障排查

  • 普通模板发送需要 APPROVED 模板;ARCHIVED 模板 无法作为普通模板消息发送。
  • 如果没有幂等策略,请勿重试已接受的请求。重复的 请求可能会发送重复的消息。
  • 在以下情况下使用 YCloud 的 id、wamid、externalId 和 Webhook 状态 排查投递情况。
  • 当直接请求到达 Meta 且 Meta 拒绝时,请检查 whatsappApiError 它。
有关吞吐量限制,请参阅 速率限制。

直接发送最佳实践

发送实用型内容、转换模板,并监控类别和限制事件。

生产环境最佳实践

设计状态同步、有界重试、同意校验、媒体复用, 以及生产集成的吞吐量控制。

使用业务范围内的用户 ID

按 BSUID 发送消息和通话、请求电话号码、管理 Meta 联系人 通讯录条目,并处理 BSUID Webhook 字段。

完整集成示例

有关完整的模板创建和变量绑定流程,请参阅 模板创建示例 和 消息发送示例。 使用 WhatsApp 错误处理 区分请求被拒绝与后续的投递失败,并使用 Webhook 接收端实现 验证签名并持久接收状态更新。