跳转到主要内容

什么是 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。
同步与异步接口 两个接口使用相同的 Direct Send 请求体。通过 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 展示复制验证码按钮。不要传入 supported_apps、autofill_text 或 zero_tap_terms_accepted。
对于 one-tap 和 zero-tap,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。
YCloud 会在接受发送请求前校验 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,显示时间可能晚于消息发送。查看步骤如下:
  1. 在 YCloud 控制台打开 WhatsApp Manager → Templates。
  2. 选择发送消息所用的 WABA。
  3. 将 Creator → Auto generated 作为筛选条件。如需只看 Utility 模板,再选择 Category → Utility。
  4. 检查模板名称、类别、语言、状态和最近更新时间。点击名称或 Insights,查看模板预览及表现数据。
Templates 页面中 Creator 筛选项设置为 Auto generated

将 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.,且不包含标头、页脚或按钮。以下请求通过异步接口提交:
YCloud 接受消息入队后的响应示例。消息内容已经转换为 type: "text":
accepted 不代表消息已送达。请保存返回的 id,通过 whatsapp.message.updated 跟踪状态,或调用 GET /v2/whatsapp/messages/{id} 查询。 如果 YCloud 返回 WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT,请检查模板标头、按钮和未替换变量是否符合下方限制。如果 WABA 无法使用 Direct Send,请先确认使用资格,再重试;也可以通过普通模板流程发送已获批的 Utility 模板。 消息有效期 模板转换时,按以下顺序确定投递有效期:
  1. 请求值优先:提供 ttlSeconds 时使用该值,范围为 30–43,200 秒。
  2. 其次使用模板值:未提供请求值时,沿用 30–43,200 秒的模板 TTL。模板 TTL 大于 0 但小于 30 秒会导致校验失败,请在请求中指定有效的 ttlSeconds。
  3. 最后使用默认值:模板 TTL 未设置、不是正数或超过 43,200 秒时,使用 Meta 默认 TTL。
转换限制 以下限制适用于 YCloud 将已有 Utility 模板转换为 Direct Send 内容的过程: 不能混合 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。样本中使用虚构客户信息:
响应示例:
在 Utility Direct Send 请求中使用内容前,请先检查 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 账户限制事件中的相关字段:
使用 WABA ID 暂停受影响的发送流程。通过 violationType 了解原因;如果提供了 restrictions[].expiration,则以该字段获取限制到期时间。 Direct Send 特有的违规类型,以及告警、限制和恢复的完整载荷,参阅 Meta 的账户限制 Webhook。 常见错误 同步请求失败时,检查响应中的 error.whatsappApiError(如有);异步排队消息失败时,检查 whatsapp.message.updated 中的失败详情。

功能更新与兼容性

你可以继续使用原有的 YCloud 同步或异步接口,以及 X-API-Key 认证方式。原有 Utility 文本和按钮请求、Authentication 文本请求均继续支持。下表对照原有用法与当前可选能力。
使用新能力仍需具备相应的 WABA 权限。Authentication Direct Send 仍处于 Alpha 阶段。平台可用性及消息格式以 Meta 的资格要求和支持的功能为准。

Direct Send 常见问题

不需要。提交完整内容,并设置 category: "utility" 或 category: "authentication",由 Meta 匹配或生成模板。对于 Utility 消息,可以选填 templateName,为 Direct Send 模板命名。如果要转换已有 Utility 模板,则需提供 template.name 和 useDirectSend: true,它们与 templateName 的用途不同。Authentication 模板不能转换为 Direct Send。
Meta 通过模板进行类别和质量检查、效果统计及故障排查。Direct Send 会替你完成模板匹配和生成,因此无需在发送前手动创建模板。参阅 Direct Send 的工作原理。
可以。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 常见问题。
不能。Meta 会判断消息的实际内容,Utility 消息中不应包含营销内容。如果你认为类别判定有误,可以按复审流程申请审核。一次发送成功,也不代表后续消息可以免除类别或质量检查。
Direct Send 消息按适用的 Utility 或 Authentication 计费规则收费,自动生成模板不代表消息免费。当前费率及适用条件请参阅 WhatsApp 计费说明。