Direct Send 的工作原理
Direct Send 在后台使用模板机制。您只需提交最终文本或受支持的交互式内容,而无需在发送前预先创建模板。 Meta 会将您的消息内容与现有模板进行匹配。若未找到匹配项,Meta 会移除个人身份信息、检测语言,并在后台生成一个新模板以供后续匹配的消息复用。 例如,“Your order A123456 has shipped”和“Your order B789012 has shipped”具有相同的结构。后续通知便可以复用相匹配的生成模板。 生成的模板会保留类别、质量和性能信息。这样即使您没有亲自创建该模板,也能识别哪些内容表现良好,或哪些内容导致了送达问题。支持的功能与限制
使用资格与发送范围
消息发送上限为 100,000 或无限制的商业投资组合(Business portfolio)通常具备使用 Utility Direct Send 的资格。 将您的 WABA 和商业电话号码连接到 YCloud。在 Meta WhatsApp 管理工具 → 消息模板 中,检查您的业务是否符合 Direct Send 资格。如果您的 WABA 无法使用该功能,请使用已获批的 Utility 模板,或联系 YCloud 查询资格。 Utility Direct Send 可以在 24 小时客户服务窗口之外发起用户预期的通知。请务必获取客户许可,并确保内容与他们的请求、交易、账户或符合条件的重要基本信息紧密相关。营销推广和验证码不属于此类 Utility 工作流程。消息长度与按钮
以下发送示例均使用文本标头。文本消息不会显示 URL 预览。账户限制和吞吐量控制仍然适用。
对于自定义
interactive Direct Send 请求,请使用文本标头。
送达生命周期 (TTL)
ttlSeconds 用于设置消息保持可送达状态的时长。如果在该期限内无法送达,消息将被丢弃。已送达的消息在其 TTL 到期时不会被删除。
默认值与允许的自定义范围有所不同。对于仅在 30 分钟内有效的配送更新通知,请设置
ttlSeconds: 1800,不要保留默认值。
语言支持
Direct Send 支持 WhatsApp 模板语言,但以下语言除外:
请在 Direct Send 工作流程中使用受支持的语言。
支持的消息类型
以下格式涵盖通过 YCloud 发送文本通知、链接以及处理客户回复。
URL 按钮用于打开网站。回复按钮会将所选的回复发送回您的业务系统,以便您的应用程序继续后续工作流。
处理回复按钮响应
虽然您发送的是interactive 请求,但 Direct Send 会以模板形式送达内容。因此,客户点击回复按钮时使用的是模板快速回复格式:type: button,包含 button.payload 和 button.text。
YCloud 入站消息事件中的相关字段:
button.payload 识别动作,使用 context.id 将回复与原始消息的 wamid 进行关联。切勿从 interactive.button_reply 读取此响应,后者是普通的自由格式回复按钮格式。
通过 YCloud 发送
准备好服务端 API Key 以及采用 E.164 格式的发送方和接收方号码。仅当您选择提交消息示例时,才需要 WABA ID。1. 选择提交模式
sendDirectly 端点名称描述了提交时序。要使用 Direct Send,您的 WABA 必须拥有访问权限,且请求必须包含下方的 Direct Send 字段。
2. 构建请求
这些示例同步提交完整内容。您也可以使用排队发送。在发送前,请替换电话号码占位符和示例 URL。
- 文本
- URL 按钮
- 回复按钮
3. 追踪送达状态
保存返回的消息id、您的 externalId 以及在可用时的 wamid。通过 whatsapp.message.updated 接收更新,或查询 GET /v2/whatsapp/messages/{id}。
在 accepted 之后,发送结果为 sent 或 failed。发送成功的消息可推进至 delivered 和 read。请求被接收并不代表送达回执。
对于同步提交错误,请检查 error.whatsappApiError(如果存在)。对于排队消息,请检查后续状态更新。如果请求超时,请在重试前先对原始消息进行对账。
为 Utility Direct Send 模板命名
当您希望 Meta 为 Utility Direct Send 模板复用易于识别的名称时,请设置templateName。该字段为可选字段,单独设置并不会启用 Direct Send。您还必须设置 useDirectSend: true 或 category: "utility"。
400,target 为 templateName,消息为 A template with the same name already exists.。请在更换其他名称后再重试。
Authentication Direct Send 不支持 templateName。对于排队的 Utility Direct Send 消息,YCloud 会返回校验错误而不返回消息 ID;在其他情况下,会将该名称转发给 Meta,而不会将其存储在消息记录中。对于不使用 Direct Send 的消息,YCloud 会忽略该字段。
在 YCloud 中查看由 Direct Send 生成的模板
- 在 YCloud 控制台中打开 WhatsApp 管理工具 → 模板 。
- 选择用于发送该消息的 WABA。
- 将筛选条件设置为 创建者 → 自动生成。使用 类别 → Utility 将列表缩小至 Utility 模板。
- 查看模板的名称、类别、语言、状态和最后更新时间。点击其名称或 Insights 打开其预览和表现详情。

Set Creator to Auto generated. This test WABA has no matching generated templates.
auto_generated 开头。请使用 Auto generated 筛选器来识别它们,而不是仅依赖其名称。
数据分析页面显示所选时间段内的消息预览以及可用的送达、失败、已读和互动统计数据。在排查警告或已暂停的模板时,请将模板的状态和内容结合起来查看。
生成的模板无法手动编辑或删除。如需更改通知,请修改发送请求中的内容;Meta 随后会针对该内容匹配或生成模板。
合规性与内容指南
保持 Utility 内容明确且非促销性
Utility 消息应当跟进客户预期的操作,或提供符合要求的必要信息。请明确说明相关的订单、预约、账户或交易。
将
category 更改为 utility 并不会改变内容的含义。Meta 在发送后仍会继续评估生成的模板。发送之前,您可以使用消息样本检查存在实质差异的使用场景。
使用消息样本检查新使用场景(可选)
POST /v2/whatsapp/messages/{wabaId}/messageSamples 向 Meta 提交一个示例,并返回 Meta 检测到的类别。它不会向客户发送消息。此项检查为可选项;您无需对每条消息或在使用 Direct Send 之前都调用它。对于新的 Utility 使用场景,我们建议检查 3 到 4 个具有代表性的样本,每次请求提交一个样本。
将 WABA_ID 替换为您的 WhatsApp 商业账户 ID,并在您的环境中设置 YCLOUD_API_KEY。样本中请使用虚构的客户详细信息:
category。如果 Meta 检测到 MARKETING 或 AUTHENTICATION,请修改内容或使用相应的消息发送工作流。对于按钮样本,请提交上述发送示例中的 type 和 interactive 字段;省略接收者和发送字段。
区分已暂停的模板与账户受限
模板可能会因质量过低而被暂停。与该模板匹配或非常相似的消息随后可能会发送失败,并返回 Meta 错误132015。请在 YCloud 中找到受影响的模板,检查其内容和状态,并在恢复该通知发送之前解决相应问题。
屡次误用类别可能会限制整个 WABA 的 Direct Send 功能:
请按照账户通知了解当前的限制情况和到期时间。单个模板审核申诉成功并不会自动解除账户层级的限制。
接收 YCloud 通知
如果您希望接收类别检测通知,请通过您的 Webhook 端点 订阅
whatsapp.template.correct_category_detection。它不是对 messageSamples 的响应,也不会对每条消息都触发。在事件的 whatsappTemplate 中,比对 previousCategory 与 category。例如,previousCategory: "UTILITY" 和 category: "MARKETING" 意味着 Meta 在 Utility Direct Send 模板中识别出了营销内容。在再次发送类似消息之前,请审查相关内容。请使用 whatsapp.message.updated 单独追踪送达情况。
YCloud 账户受限事件中的相关字段:
violationType 获取原因,如果提供,查看 restrictions[].expiration 获取其到期时间。
有关 Direct Send 特定的违规类型以及警告、限制和恢复有效负载,请参阅 Meta 的 账户限制 Webhook。
申请对类别判定进行审核
如果您认为内容被错误标记,请打开 Meta 业务支持中心 → WhatsApp 账户 → Direct Send 模板更新 → 可申请审核。选择受影响的模板并选择 申请审核。 请在收到通知后 60 天内提交申请。每个被标记的模板只能审核一次。可将结果跟踪为 审核中、 已撤销或 未更改。如果审核选项不可用,请联系 YCloud 并提供 WABA ID、模板名称或 ID、语言以及通知详情。YCloud 扩展功能:重用现有 Utility 模板
YCloud 在 Meta Direct Send 的基础上增加了模板转换功能。当您的集成已经发送模板名称和参数时,可使用此扩展功能。YCloud 会填充变量并将支持的组件转换为完整的消息内容,然后将该内容提交给 Meta Direct Send 进行匹配或生成。此转换由 YCloud 提供;它不是 Meta Direct Send 匹配和生成流程中的步骤。template.name 用于选择要转换的现有模板。上文所述的可选字段 templateName 用于指定 Direct Send 模板的名称,并不选择用于转换的模板。
转换现有的 Utility 模板
使用您 WABA 中的现有 Utility 模板。设置type: "template" 和 useDirectSend: true。提供模板名称、语言以及每个必需的参数。YCloud 会替换变量,并通过 category: "utility" 将支持的组件转换为文本或交互式内容。该模板必须符合下述转换限制。YCloud 在进行此转换时不要求具有 APPROVED 状态。
如果模板包含图片页眉,请在使用前确认 Meta 已为您的 WABA 启用了带图片页眉的 Direct Send。这需要单独的 Meta 访问权限。
在此示例中,使用名为 order_update 的现有 utility 模板,正文为 Your order {{1}} has been updated.,不包含页眉、页脚或按钮:
type 变为 text,并且模板变量变为所提供的订单 ID:
accepted 响应并不确认送达。请存储消息 id 并跟踪 whatsapp.message.updated 事件。在重用带有页眉或按钮的模板之前,请查看下述转换限制。
如果 YCloud 返回 WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT,请对照下述限制检查模板的页眉、按钮和未解析的变量。如果 WABA 无法使用 Direct Send,请在重试前检查其资格,或通过常规模板工作流程发送已批准的 Utility 模板。
设置转换消息的生命周期
对于模板转换,请求中的ttlSeconds 值优先于模板 TTL。如果省略该值,YCloud 会继承不超过 43200 秒的正数模板 TTL。低于 30 秒的模板 TTL 将无法通过验证,因此请使用有效的请求值进行替换覆盖。YCloud 不会继承超过 43200 的模板 TTL 值。如果两者均不适用,Meta 将使用其默认 TTL。
模板转换限制
以下限制适用于 YCloud 将现有 Utility 模板转换为 Direct Send 内容的过程:
请勿同时组合 CTA URL 和快速回复按钮。其他页眉和按钮类型无法转换。不支持的组件或未解析的模板变量将返回 HTTP
400,错误代码为 WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT。
Direct Send 常见问题
发送前是否需要模板名称?
发送前是否需要模板名称?
自定义内容不需要。只需提供完整的消息,由 Meta 进行匹配或生成模板。如需转换现有的效用(Utility)模板,请提供其
template.name 并设置 useDirectSend: true。可选的 templateName 字段用于命名 Utility Direct Send 模板,并非用于选择现有模板。为什么 Direct Send 仍会生成模板?
为什么 Direct Send 仍会生成模板?
模板支持类别和质量检查、效果报告以及问题排查。Direct Send 消除了手动创建模板的需要,但并未消除消息背后的基于模板的处理流程。
我可以在 24 小时客户服务窗口之外发送消息吗?
我可以在 24 小时客户服务窗口之外发送消息吗?
可以,适用于符合条件的 Utility Direct Send 通知。您的 WABA 必须拥有相应权限,客户必须期望接收该消息,且内容必须符合 Utility 要求。普通的自由格式服务消息仍需要处于打开状态的服务窗口。
为什么消息可以在生成的模板出现之前就发送成功?
为什么消息可以在生成的模板出现之前就发送成功?
模板生成和同步是异步进行的,可能会在消息发送之后完成。完成后,选择正确的 WABA 并使用 Auto generated 筛选条件。
未使用的已生成模板如何清理?
未使用的已生成模板如何清理?
Meta 会在 24 小时后删除从未用于发送的生成模板。之前使用过的模板在闲置一段时间后可能会被归档。您无需手动删除它们。
设置 utility 是否能保证 Meta 一定会接受该类别?
设置 utility 是否能保证 Meta 一定会接受该类别?
不能。Meta 会审核实际内容。请从 Utility 通知中移除促销用语;如果真实的 Utility 消息被错误标记,请使用申诉审核流程。
Direct Send 如何计费?
Direct Send 如何计费?
Utility 消息遵循与手动创建的 Utility 消息模板相同的 Utility 消息计费规则。参见 WhatsApp pricing。

