什么是 Direct Send
Direct Send 让你无需预先创建模板,即可发送由商家发起的 Utility 和 Authentication 消息。通过 YCloud WhatsApp Messages API 提交完整内容并指定category,Meta 会匹配或生成模板。
Utility(交易相关)用于与客户操作或请求相关的消息,例如订单更新和预约提醒;Authentication(身份验证)用于通过一次性密码(OTP)验证身份。Marketing(营销)消息使用常规模板发送。
使用前准备
- 获取 YCloud API Key,并接入 WhatsApp 业务电话号码。
- 确认 WhatsApp Business Account(WABA)已开通对应类别的 Direct Send 权限。参阅资格要求。
- 获得客户接收消息的许可,并遵循 Meta 消息类别准则。
发送消息
将YCLOUD_API_KEY 设置为你的 API Key,并将电话号码占位值替换为 E.164 格式。下方示例使用同步接口,也可以异步提交。
Utility 消息示例
每个标签页都提供完整的 cURL 请求。发送前,请替换 API Key、电话号码和示例 URL。- 文本
- 回复按钮
- URL 按钮
- 媒体标头
X-API-Key 请求头认证,并设置 Content-Type: application/json。
sendDirectly 控制的是提交方式,并不表示请求一定使用 Direct Send。通过消息状态与回调确认投递结果。
请求参数
如果同时省略
category 和 useDirectSend,则按普通自由格式消息发送,需要处于有效的 24 小时客户服务窗口内。
Authentication OTP 示例
选择以下三种 OTP 体验之一。每个示例都是完整的 YCloud 请求体,可用于同步或异步接口。WABA 必须已开通 Authentication Direct Send OTP 权限。使用to 指定接收方电话号码;Authentication 消息不支持企业范围用户编号(BSUID)接收方。
将
otp.code 和 interactive.body.text 中的 123456 同时替换为你的验证码。验证码必须为 4–10 位 ASCII 字母或数字,并在正文中作为独立值出现。
- copy_code
- one_tap
- zero_tap
使用
copy_code 展示复制验证码按钮。不要传入 supported_apps、autofill_text 或 zero_tap_terms_accepted。supported_apps 支持 1–5 个 Android 应用,包名不能重复,每个 signature_hash 必须恰好为 11 个字符。上面的包名和签名哈希仅用于示例,无法为你的应用启用自动填写。详见应用接入和完整参数规则。
code_expiration_minutes 以分钟描述验证码有效期,你的应用仍需负责校验验证码并执行过期检查。ttlSeconds 控制 WhatsApp 尝试投递消息的时长;Authentication Direct Send 支持 30–900 秒,默认 600 秒。
在 iOS 26 及以上版本中,设备启用 WhatsApp 通知和安全码自动填写后,copy code 和 one-tap 消息可为 4–8 位纯数字验证码提供键盘建议。Zero-tap 仅适用于 Android。详见 Meta 的 OTP 体验说明。
纯文本 Authentication Direct Send 仍受支持。消息已送达仅能证明投递成功,不能证明 Android 自动填写握手已成功。
消息有效期(TTL)
通过ttlSeconds 设置消息的投递有效期,避免在消息失去时效性后继续尝试投递。
例如,
ttlSeconds: 1800 表示 Utility 消息最多尝试投递 30 分钟。Authentication 消息最多为 15 分钟。TTL 不会删除已送达消息,也不能替代应用中的验证码过期检查。参阅 Meta TTL 说明。
自定义模板名称
可以选填templateName,为 Utility Direct Send 模板指定名称。启用 Direct Send 仍需设置 category: "utility" 或 useDirectSend: true。
自定义模板名称请求示例
自定义模板名称请求示例
templateName。如果名称不合法或已被普通模板占用,请修改名称后重试。
名称长度为 1–512 个字符,只能包含小写字母、数字或下划线。YCloud 会拒绝大写字母、空格和其他字符。
同一 WABA 下不能使用已被普通 WhatsApp 消息模板占用的名称,包括已被拒绝的模板。已删除的模板不再占用名称,也可以复用 Meta 之前为 Direct Send 生成的模板名称。
如果名称已被普通模板占用,API 返回 HTTP 400,target 为 templateName,错误消息为 A template with the same name already exists.。
请求被接受后,请继续关注消息状态。名称冲突或模板创建失败的处理方式见常见错误;Meta 的重试规则参阅商家命名模板说明。
Authentication Direct Send 不支持 templateName。对于未使用 Direct Send 的消息,YCloud 会忽略该字段。
消息状态与回调
投递状态 YCloud 通过whatsapp.message.updated 回调发送状态。保存响应中的 YCloud id 和 WhatsApp 消息 ID(wamid),用于关联后续状态更新。
accepted 表示 YCloud 已接受请求;sent 表示消息正在 WhatsApp 内传输。通过 delivered、read 或 failed 跟踪后续结果。也可以使用 YCloud id 调用 GET /v2/whatsapp/messages/{id} 查询消息。
如需与自己的业务记录关联,可以设置 externalId,但该字段不具备防止重复发送的作用。请求超时后,请先检查原消息的状态,再决定是否重试。参阅配置状态 Webhook。
回复按钮回调
客户点击 Direct Send 回复按钮后,回调中的入站消息类型为 button。通过 button.payload 和 button.text 读取客户选择。
YCloud 入站消息事件中的相关字段如下:
回复按钮回调示例
回复按钮回调示例
button.payload 识别客户选择的操作,并通过 context.id 关联原消息的 wamid。不要从 interactive.button_reply 读取此类响应,该对象属于普通自由格式回复按钮消息。
YCloud 扩展功能
YCloud 提供控制台中的模板查看与分析能力,以及将已有 Utility 模板转换为 Direct Send 消息的 API 扩展。模板匹配和自动生成仍由 Meta 完成。查看自动生成的模板
自动生成的模板同步后会出现在 YCloud,显示时间可能晚于消息发送。查看步骤如下:- 在 YCloud 控制台打开 WhatsApp Manager → Templates。
- 选择发送消息所用的 WABA。
- 将 Creator → Auto generated 作为筛选条件。如需只看 Utility 模板,再选择 Category → Utility。
- 检查模板名称、类别、语言、状态和最近更新时间。点击名称或 Insights,查看模板预览及表现数据。

将 Creator 设置为 Auto generated。截图中的测试 WABA 没有匹配的自动生成模板。
auto_generated 开头;自定义名称的模板使用请求中提供的名称。两者均可通过 Creator → Auto generated 查找。参阅 Meta 自动生成模板说明。
Insights 页面展示消息预览,以及所选时间段内可用的送达、失败、已读和交互统计。排查告警或模板暂停时,请结合模板状态与内容一起检查。
自动生成的模板不能手动编辑或删除。如需调整 Utility 消息,请修改发送请求中的内容,Meta 会重新匹配或生成相应模板。
Meta 会在 24 小时后删除从未使用过的自动生成模板。曾经使用过的模板可能在一段时间未使用后被归档。
模板转 Direct Send
这是 YCloud 为已有 Utility 模板提供的扩展功能。设置useDirectSend: true,YCloud 会填充模板参数后通过 Direct Send 发送。
template.name 用于选择待转换的已有模板;templateName 用于指定 Meta 为 Utility Direct Send 匹配或生成的模板名称。
选择当前 WABA 中的 Utility 模板,设置 type: "template" 和 useDirectSend: true,并提供模板名称、语言及全部必填参数。模板必须符合下方转换限制,但不要求处于 APPROVED 状态。
Authentication 模板不支持转换。通过 Direct Send 发送 OTP 时,请使用 Authentication 请求。
下面使用名为 order_update 的已有 Utility 模板,其正文为 Your order {{1}} has been updated.,且不包含标头、页脚或按钮。以下请求通过异步接口提交:
type: "text":
accepted 不代表消息已送达。请保存返回的 id,通过 whatsapp.message.updated 跟踪状态,或调用 GET /v2/whatsapp/messages/{id} 查询。
如果 YCloud 返回 WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT,请检查模板标头、按钮和未替换变量是否符合下方限制。如果 WABA 无法使用 Direct Send,请先确认使用资格,再重试;也可以通过普通模板流程发送已获批的 Utility 模板。
消息有效期
模板转换时,按以下顺序确定投递有效期:
- 请求值优先:提供
ttlSeconds时使用该值,范围为 30–43,200 秒。 - 其次使用模板值:未提供请求值时,沿用 30–43,200 秒的模板 TTL。模板 TTL 大于 0 但小于 30 秒会导致校验失败,请在请求中指定有效的
ttlSeconds。 - 最后使用默认值:模板 TTL 未设置、不是正数或超过 43,200 秒时,使用 Meta 默认 TTL。
不能混合 CTA URL 和快速回复按钮。其他类型的标头和按钮不支持转换。不受支持的组件或未替换的模板变量会返回 HTTP
400,错误码为 WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT。
转换带图片标头的模板前,请确认当前 WABA 可以使用媒体标头。参阅支持的功能与限制和 Meta 媒体标头要求。
消息样本检查(可选)
POST /v2/whatsapp/messages/{wabaId}/messageSamples 向 Meta 提交一条样本并返回识别的类别,不会给客户发送消息。这是可选的 YCloud 接口。接入新场景时,可以先检查有代表性的内容,但样本结果不能免除后续消息的类别和质量检查。
将 WABA_ID 替换为你的 WABA ID,并将 YCLOUD_API_KEY 设置为 API Key。样本中使用虚构客户信息:
category。如果 Meta 识别为 MARKETING 或 AUTHENTICATION,请修改内容或使用对应的发送流程。检查按钮样本时,提交上面 Utility 按钮示例中的 type 和 interactive 字段,省略接收方和发送相关字段。
支持的功能与限制
WABA 使用资格 在 Meta WhatsApp 管理工具 → 消息模板 中检查可用性。消息发送限额为 100,000 或无限制的业务资产组合(Business Portfolio)通常具备 Utility Direct Send 资格;Authentication Direct Send 处于 Alpha 阶段。详见 Meta 的资格要求。 消息格式、语言与计费 以下限制适用于本页请求示例使用的消息格式。Meta 平台要求参见支持的消息类型。
支持所有 WhatsApp 模板语言。常规消息发送限额与吞吐量限制仍然适用,费用按相应的 Utility 或 Authentication 类别计算。
合规性与内容指南
Utility 内容必须是非营销性质,并与客户操作、请求或符合条件的重要信息相关。写明对应的订单、预约、账户或交易,让客户理解收到消息的原因。请遵循 Meta 模板类别指南。
不要在 Utility 更新中加入促销、折扣或其他商品推荐。OTP 使用 Authentication 类别,营销内容使用 Marketing 模板。设置
category: "utility" 不会改变 Meta 对内容的判断。
接入新场景时,可以先执行消息样本检查。如果 Meta 标记了内容,请检查类别通知并参阅账户状态与故障排查;对判断有异议时,可按其中的步骤申请复审。
账户状态与故障排查
告警、限制与复审 模板可能因质量较低而暂停。与它匹配或内容高度相似的消息,随后可能返回 Meta 错误132015。在 YCloud 中找到受影响的模板,检查其内容和状态,解决原因后再恢复相关发送。
反复错误使用类别,可能导致整个 WABA 的 Direct Send 权限受限:
当前生效的限制及到期时间以账户通知为准。某个模板复审成功,不代表账户级限制会自动解除。
申请类别复审
如果你认为内容被错误标记,请打开 Meta Business Support Home → WhatsApp account → Direct Send template updates → Available for review,选择相关模板并点击 Request review。
请在收到通知后的 60 天内提交申请;每个被标记的模板只能复审一次。通过 In review、Reversed 或 Unchanged 跟踪结果。如果没有复审入口,请向 YCloud 提供 WABA ID、模板名称或 ID、语言及通知详情。
状态通知
通过 Webhook 端点订阅
whatsapp.template.correct_category_detection。收到通知后,比较 whatsappTemplate.previousCategory 与 whatsappTemplate.category;若分别为 UTILITY 和 MARKETING,请检查消息是否包含营销内容。参阅类别检测 Webhook 示例。
该通知针对模板类别,不会逐条消息触发。样本检查结果由 messageSamples 接口直接返回,消息投递结果通过 whatsapp.message.updated 获取。
以下是 YCloud 账户限制事件中的相关字段:
账户限制 Webhook 示例
账户限制 Webhook 示例
violationType 了解原因;如果提供了 restrictions[].expiration,则以该字段获取限制到期时间。
Direct Send 特有的违规类型,以及告警、限制和恢复的完整载荷,参阅 Meta 的账户限制 Webhook。
常见错误
同步请求失败时,检查响应中的 error.whatsappApiError(如有);异步排队消息失败时,检查 whatsapp.message.updated 中的失败详情。
功能更新与兼容性
你可以继续使用原有的 YCloud 同步或异步接口,以及X-API-Key 认证方式。原有 Utility 文本和按钮请求、Authentication 文本请求均继续支持。下表对照原有用法与当前可选能力。
Direct Send 常见问题
发送前是否需要模板名称?
发送前是否需要模板名称?
不需要。提交完整内容,并设置
category: "utility" 或 category: "authentication",由 Meta 匹配或生成模板。对于 Utility 消息,可以选填 templateName,为 Direct Send 模板命名。如果要转换已有 Utility 模板,则需提供 template.name 和 useDirectSend: true,它们与 templateName 的用途不同。Authentication 模板不能转换为 Direct Send。为什么 Direct Send 仍会生成模板?
为什么 Direct Send 仍会生成模板?
Meta 通过模板进行类别和质量检查、效果统计及故障排查。Direct Send 会替你完成模板匹配和生成,因此无需在发送前手动创建模板。参阅 Direct Send 的工作原理。
可以在 24 小时客户服务窗口之外发送消息吗?
可以在 24 小时客户服务窗口之外发送消息吗?
可以。Direct Send 支持在客户服务窗口之外发送由商家发起的 Utility 和 Authentication 消息,前提是 WABA 已开通对应类别的权限,且消息符合 Meta 对客户许可和内容的要求。普通自由格式消息仍需处于有效的客户服务窗口内。参阅使用资格与发送范围。
为什么消息已发送成功,却还看不到生成的模板?
为什么消息已发送成功,却还看不到生成的模板?
标准 Direct Send 可以先通过引导模板(onboarding template)发送消息,同时由 Meta 异步生成匹配的模板。同步到 YCloud 可能晚于消息发送。在正确的 WABA 下,使用 Creator → Auto generated 查找自动生成的模板。生成模板时,Meta 会移除个人信息并识别语言。商家命名的 Utility 模板不使用这一引导模板回退机制。
未使用的自动生成模板如何清理?
未使用的自动生成模板如何清理?
Meta 会在创建 24 小时后删除从未用于发送的自动生成模板。曾经使用过的模板,在一段时间未使用后会被定期归档。清理由 Meta 管理;Direct Send 模板不能手动编辑或删除。参阅 Meta Direct Send 常见问题。
设置 utility 是否能保证 Meta 接受该类别?
设置 utility 是否能保证 Meta 接受该类别?
不能。Meta 会判断消息的实际内容,Utility 消息中不应包含营销内容。如果你认为类别判定有误,可以按复审流程申请审核。一次发送成功,也不代表后续消息可以免除类别或质量检查。
Direct Send 如何计费?
Direct Send 如何计费?
Direct Send 消息按适用的 Utility 或 Authentication 计费规则收费,自动生成模板不代表消息免费。当前费率及适用条件请参阅 WhatsApp 计费说明。

