Direct Send 最佳实践

符合条件的企业可以通过 Direct Send 提交完整内容或复用现有效用模板来发送效用消息。Meta 会自动处理自定义内容的模板匹配与生成。本指南介绍了通过 YCloud 进行效用 Direct Send 的方法。有关常规消息发送，请参阅发送 WhatsApp 消息。

Direct Send 的工作原理

Direct Send 在后台使用模板机制。您可以提交最终文本或交互式内容，也可以引用现有效用模板，并让 YCloud 将其支持的组件转换为 Direct Send 消息。

起点	请求	YCloud 发送的内容
完整效用内容	将 `type` 设置为 `text` 或 `interactive`，并将 `category` 设置为 `utility`。	您的内容将作为 Direct Send 消息发送。
现有效用模板	将 `type` 设置为 `template`，提供 `template.name`、`template.language` 以及所有必需参数，然后设置 `useDirectSend: true`。	转换后的文本、CTA URL 或快速回复按钮内容。

Meta 会将您的消息内容与现有模板进行匹配。如果没有匹配项，Meta 会移除个人身份信息，检测语言，并在后台生成一个新模板供后续匹配的消息使用。例如，“您的订单 A123456 已发货”和“您的订单 B789012 已发货”具有相同的结构。后续通知可以复用匹配生成的模板。生成的模板会保留类别、质量和表现信息。即使模板不是您自行创建的，这也能让您识别出哪些内容表现良好，或者哪些内容导致了送达问题。

支持的功能与限制

使用资格与发送范围

将您的 WABA 和商业电话号码连接到 YCloud。在 Meta WhatsApp 管理工具 → 消息模板 中，检查您的企业是否符合 Direct Send 的使用资格。如果您的 WABA 无法使用该功能，请使用已获批的效用模板或联系 YCloud 查询资格。效用 Direct Send 可以在 24 小时客户服务窗口期外发起预期的通知。请先征得客户的同意，并确保内容与他们的请求、交易、账户或符合条件的必要信息相关联。营销推广和验证码不在该效用工作流范围内。

功能	行为
消息内容	发送完整文本和支持的按钮内容，无需预先创建模板。
现有效用模板	设置 `useDirectSend: true`，在提供参数后转换支持的模板组件。
模板创建	Meta 会匹配现有生成的模板，或在后台生成新模板。
提交	通过 YCloud 使用队列或同步方式提交。
消息有效期	为时效性通知设置自定义 `ttlSeconds`。
模板管理	在 YCloud 中查看生成的模板。在 API 请求中更改后续内容。
计费	适用效用消息计费规则。

消息长度与按钮

内容	限制
正文	1,024 个字符
页眉	60 个字符
页脚	60 个字符
按钮标签	20 个字符
回复按钮格式 (`interactive.type: button`)	最多 3 个回复按钮
URL 按钮格式 (`interactive.type: cta_url`)	1 个 URL 按钮

以下发送示例使用文本页眉。文本消息不会显示 URL 预览。账户限制和吞吐量控制仍然适用。自定义 interactive Direct Send 请求请使用文本页眉。仅当您转换支持的模板且 Meta 已为您的 WABA 启用该功能时，才可以使用图片页眉。

消息有效期 (TTL)

ttlSeconds 用于设置消息可保持有效待递送的时长。如果无法在该时间段内送达，消息将被丢弃。已送达的消息在其 TTL 过期时不会被删除。

设置	效用值
省略时的默认值	30 天
自定义最小 TTL	30 秒
自定义最大 TTL	43,200 秒（12 小时）

默认值与允许的自定义范围有所不同。对于仅在 30 分钟内有效的送达更新，请设置 ttlSeconds: 1800；不要保留默认值。

支持的消息类型

以下格式涵盖通过 YCloud 发送的文本通知、链接和客户回复。

类型	请求字段	典型用途
文本	`type: text`，包含 `text.body`	确认订单或报告状态变更。
URL 按钮	`type: interactive`，包含 `interactive.type: cta_url`	打开物流追踪、发票或预约页面。
回复按钮	`type: interactive`，包含 `interactive.type: button`	请客户在 WhatsApp 中确认或请求帮助。

URL 按钮可打开网站。回复按钮将所选回复发送回您的业务系统，以便您的应用程序继续执行工作流。

处理回复按钮响应

虽然您发送的是 interactive 请求，但 Direct Send 会以模板形式递送内容。因此，客户点击回复按钮时使用的是模板快捷回复格式：type: button，包含 button.payload 和 button.text。 YCloud 接收消息事件中的相关字段：

{
  "type": "whatsapp.inbound_message.received",
  "whatsappInboundMessage": {
    "type": "button",
    "button": {
      "payload": "delivery_help_A123456",
      "text": "I need help"
    },
    "context": {
      "id": "ORIGINAL_MESSAGE_WAMID"
    }
  }
}

使用 button.payload 识别操作，并使用 context.id 将回复与原始消息的 wamid 关联起来。请勿从 interactive.button_reply 读取此响应，那是普通的自由格式回复按钮格式。

通过 YCloud 发送

准备一个服务端 API 密钥以及 E.164 格式的发件人和收件人号码。仅当您选择提交消息样本时，才需要 WABA ID。

1. 选择提交模式

端点	行为
`POST /v2/whatsapp/messages`	将消息排队并异步提交。
`POST /v2/whatsapp/messages/sendDirectly`	将消息同步提交到 WhatsApp Business API。

sendDirectly 端点名称说明了提交时序。要使用 Direct Send，您的 WABA 必须具有相应权限，且请求中必须包含下方的 Direct Send 字段。

2. 构建请求

字段	值或用途
`from`、`to`	E.164 格式的发件人和收件人号码。
`type`	`text` 或 `interactive`。
`text` 或 `interactive`	完整的消息内容。
`category`	`utility`.
`useDirectSend`	转换现有模板时设置为 `true`。对于带有 `category: "utility"` 的自定义内容，此字段是可选的。
`ttlSeconds`	可选的有效生存时间（以秒为单位）。
`externalId`	用于对账的可选业务参考；不保证幂等性。

这些示例展示了如何同步提交完整内容。您也可以使用队列发送或转换现有的 Utility 模板。发送前请替换电话号码占位符和示例 URL。

文本
URL 按钮
回复按钮

curl --request POST \
  'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${YCLOUD_API_KEY}" \
  --data '{
    "from": "BUSINESS_PHONE_NUMBER",
    "to": "CUSTOMER_PHONE_NUMBER",
    "type": "text",
    "text": {
      "body": "Your order A123456 has shipped. Your estimated delivery date is September 15."
    },
    "category": "utility",
    "useDirectSend": true,
    "ttlSeconds": 1800,
    "externalId": "order-A123456-shipped-text"
  }'

curl --request POST \
  'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${YCLOUD_API_KEY}" \
  --data '{
    "from": "BUSINESS_PHONE_NUMBER",
    "to": "CUSTOMER_PHONE_NUMBER",
    "type": "interactive",
    "interactive": {
      "type": "cta_url",
      "header": {
        "type": "text",
        "text": "Order shipped"
      },
      "body": {
        "text": "Your order A123456 has shipped. View its latest delivery status below."
      },
      "footer": {
        "text": "Order A123456"
      },
      "action": {
        "name": "cta_url",
        "parameters": {
          "display_text": "Track order",
          "url": "https://example.com/orders/A123456"
        }
      }
    },
    "category": "utility",
    "useDirectSend": true,
    "ttlSeconds": 1800,
    "externalId": "order-A123456-shipped-url"
  }'

curl --request POST \
  'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${YCLOUD_API_KEY}" \
  --data '{
    "from": "BUSINESS_PHONE_NUMBER",
    "to": "CUSTOMER_PHONE_NUMBER",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "header": {
        "type": "text",
        "text": "Delivery update"
      },
      "body": {
        "text": "Your order A123456 is scheduled for delivery on September 15. Do you need help with this delivery?"
      },
      "footer": {
        "text": "Order A123456"
      },
      "action": {
        "buttons": [
          {
            "type": "reply",
            "reply": {
              "id": "delivery_help_A123456",
              "title": "I need help"
            }
          },
          {
            "type": "reply",
            "reply": {
              "id": "delivery_ok_A123456",
              "title": "No help needed"
            }
          }
        ]
      }
    },
    "category": "utility",
    "useDirectSend": true,
    "ttlSeconds": 1800,
    "externalId": "order-A123456-delivery-reply"
  }'

3. 追踪送达状态

保存返回的消息 id、您的 externalId 以及可用的 wamid。通过 whatsapp.message.updated 接收更新，或查询 GET /v2/whatsapp/messages/{id}。在 accepted 之后，发送结果为 sent 或 failed。成功的消息可以继续流转至 delivered 和 read。请求被接收并不等同于送达回执。对于同步提交错误，请在存在时检查 error.whatsappApiError。对于排队的消息，请检查后续的状态更新。如果请求超时，请在重试之前先对账原始消息。

转换现有的 Utility 模板

使用 WABA 中的现有 Utility 模板。设置 type: "template" 和 useDirectSend: true。提供模板名称、语言以及每个必需的参数。YCloud 会替换变量，并通过 category: "utility" 将支持的组件转换为文本或交互式内容。模板必须符合下方的转换限制。YCloud 进行此转换不要求 APPROVED 状态。如果模板包含图片页眉，请在使用前确认 Meta 已为您的 WABA 启用了带图片页眉的 Direct Send 功能。这需要单独的 Meta 权限。在本示例中，使用一个名为 order_update 的现有效用模板，正文为 Your order {{1}} has been updated.，且不含页眉、页脚或按钮：

curl --request POST https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "template",
    "template": {
      "name": "order_update",
      "language": {
        "code": "en_US",
        "policy": "deterministic"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "A123456"
            }
          ]
        }
      ]
    },
    "useDirectSend": true,
    "ttlSeconds": 600
  }'

响应中包含转换后的内容。在此示例中，type 变为 text，模板变量变为提供的订单 ID：

{
  "id": "MESSAGE_ID",
  "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "text",
  "text": {
    "body": "Your order A123456 has been updated."
  },
  "status": "accepted",
  "category": "utility",
  "ttlSeconds": 600,
  "createTime": "2026-09-17T08:00:00.000Z"
}

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。

为 Utility Direct Send 模板命名

上述转换请求中的 template.name 用于标识现有模板。templateName 用于不同的目的：当您希望 Meta 为 Utility Direct Send 模板复用可识别的名称时进行设置。该字段为可选字段，本身不会启用 Direct Send。您还必须设置 useDirectSend: true 或 category: "utility"。

{
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "text",
  "text": {
    "body": "Your order 12131123 has been placed at the door."
  },
  "category": "utility",
  "templateName": "order_update_ds"
}

名称区分大小写。请使用 1 到 512 个小写字母、数字或下划线。YCloud 会拒绝大写字母、空格和其他字符。同一个 WABA 不能使用属于现有常规 WhatsApp 消息模板的名称（包括已被拒绝的模板）。YCloud 会在同步提供商调用前或接受排队消息前对此进行检查。已删除的模板不会占用名称，并且您可以复用 Meta 先前为 Direct Send 生成的名称。如果常规模板已使用该名称，API 将返回 HTTP 400，目标为 templateName，消息为 A template with the same name already exists.。重试前请选择其他名称。 Authentication Direct Send 不支持 templateName。对于排队的 Utility Direct Send 消息，YCloud 会返回验证错误且不返回消息 ID，而在其他情况下会将名称转发给 Meta，而不会将其存储在消息记录中。对于不使用 Direct Send 的消息，YCloud 会忽略该字段。

模板转换与语言限制

Utility Direct Send 支持文本、CTA URL 按钮和回复按钮。当 YCloud 转换实用模板时，以下限制同样适用：

内容或组件	限制和转换行为
正文	最多 1,024 个字符。请提供每个模板变量。Direct Send 不显示 URL 预览；请省略 `preview_url`。
文本页眉	最多 60 个字符。带有按钮时，它会转换为交互式文本页眉。没有按钮时，YCloud 会将页眉和正文合并为文本消息。
图片页眉	需要 CTA URL 或回复按钮。请提供 `image.link` 或 `image.id` 参数。没有按钮的图片页眉无法转换。
页脚	最多 60 个字符。YCloud 会在交互式消息中包含该内容，而在将没有按钮的模板转换为文本时将其省略。
CTA URL 按钮	最多 1 个。YCloud 会将模板 `URL` 按钮转换为 `interactive.cta_url`。
回复按钮	最多 3 个。YCloud 会将模板 `QUICK_REPLY` 按钮转换为 `interactive.button`。
按钮标签	最多 20 个字符。

请勿将 CTA URL 和快速回复按钮混合使用。其他页眉和按钮类型无法转换。不支持的组件或未解析的模板变量将返回 HTTP 400 及代码 WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT。

语言支持

Direct Send 支持 WhatsApp 模板语言，以下除外：

语言	代码
简体中文	`zh_CN`
繁体中文（香港）	`zh_HK`
繁体中文（台湾）	`zh_TW`
日语	`ja`
韩语	`ko`
泰语	`th`
老挝语	`lo`

请在 Direct Send 工作流中使用受支持的语言。

在 YCloud 中查看由 Direct Send 生成的模板

在 YCloud 控制台中打开 WhatsApp Manager → 模板 。
选择用于发送消息的 WABA。
设置 创建者 → 自动生成。使用 类别 → 实用 将列表筛选为 Utility 模板。
查看模板的名称、类别、语言、状态和最后更新时间。点击其名称或 数据分析 打开其预览和效果详情。

模板中创建者筛选器设置为自动生成 — Set Creator to Auto generated. This test WABA has no matching generated templates.

内容生成的模板名称通常以 auto_generated 开头。请使用 自动生成 筛选器来识别它们，而不是仅依赖其名称。洞察页面会显示所选时段内的消息预览以及可用的送达、失败、已读和互动统计数据。在排查警告或已暂停的模板时，请结合模板的状态和内容一起分析。生成的模板无法手动编辑或删除。如需更改通知，请在发送请求中更改内容；Meta 随后会针对该内容匹配或生成模板。

合规与内容指南

保持 Utility 内容明确且非促销性

Utility 消息应当跟进客户预期的操作或提供符合要求的关键信息。请清楚说明相关订单、预约、账户或交易。

合适的 Utility 内容	应排除在此工作流之外的内容
“Your order A123456 has shipped.”	“Your order has shipped. Buy again today for 20% off.”
“Your appointment is confirmed for September 15 at 10:00.”	“Book another appointment now and receive a gift.”
“Your refund for order A123456 has been processed.”	普通促销或身份验证码。

将 category 改为 utility 并不会改变内容的含义。Meta 会在发送后继续评估生成的模板。在发送之前，您可以使用消息样本对实质上不同的用例进行检查。

使用消息样本检查新用例（可选）

POST /v2/whatsapp/messages/{wabaId}/messageSamples 会向 Meta 提交一个示例并返回 Meta 检测到的类别。它不会向客户发送消息。此检查是可选的；您无需针对每条消息或在使用 Direct Send 之前都调用它。对于新的 Utility 用例，我们建议检查三到四个代表性样本，每次请求一个。将 WABA_ID 替换为您的 WhatsApp 商业账户 ID，并在您的环境中设置 YCLOUD_API_KEY。在样本中使用虚构的客户详细信息：

curl --request POST \
  'https://api.ycloud.com/v2/whatsapp/messages/WABA_ID/messageSamples' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${YCLOUD_API_KEY}" \
  --data '{
    "type": "text",
    "text": {
      "body": "Your order A123456 has shipped. Your estimated delivery date is September 15."
    }
  }'

示例响应：

{
  "success": true,
  "category": "UTILITY"
}

在 Utility Direct Send 请求中使用该内容之前，请先检查 category。如果 Meta 检测到 MARKETING 或 AUTHENTICATION，请修改内容或使用相应的消息发送工作流。对于按钮样本，请提交上述发送示例中的 type 和 interactive 字段；省略接收者和发送字段。

区分暂停的模板与账户限制

模板可能会因质量过低而被暂停。与之匹配或非常相似的消息随后可能会失败并返回 Meta 错误 132015。请在 YCloud 中找到受影响的模板，检查其内容和状态，并在恢复该通知之前解决问题根因。多次滥用类别可能会限制整个 WABA 的 Direct Send 功能：

阶段	影响
警告	Meta 指出违规行为，以便您进行纠正或请求复审。
速率限制	WABA 发送量受临时上限限制。进一步的 Utility 发送可能会返回 `131064`。
7 天限制	Direct Send 消息发送被阻止 7 天。
30 天限制	持续违规会导致延长限制期。
吊销	Direct Send 权限被永久移除。

请遵循账户通知了解生效的限制及其到期时间。单个模板复审成功不会自动解除账户级别的限制。

接收 YCloud 通知

事件	用途
`whatsapp.message.updated`	跟踪送达情况并检查消息发送失败。
`whatsapp.template.correct_category_detection`	当 Meta 为 Utility Direct Send 模板检测到不同类别时接收通知。
`whatsapp.business_account.updated`	跟踪 Direct Send 警告、限制和恢复情况。

如果您希望接收类别检测通知，请通过您的 Webhook 端点订阅 whatsapp.template.correct_category_detection。它不是对 messageSamples 的响应，也不会针对每条消息都触发。在事件的 whatsappTemplate 中，对比 previousCategory 与 category。例如，previousCategory: "UTILITY" 与 category: "MARKETING" 意味着 Meta 在 Utility Direct Send 模板中识别出了营销内容。在再次发送类似消息之前，请审查相关内容。使用 whatsapp.message.updated 单独跟踪送达情况。来自 YCloud 账户限制事件的相关字段：

{
  "id": "EVENT_ID",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "whatsappBusinessAccount": {
    "id": "WABA_ID",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "violationType": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES",
        "expiration": "2026-09-17T10:00:00.000Z"
      }
    ]
  }
}

使用 WABA ID 暂停受影响的工作流。查看 violationType 获取原因，并查看 restrictions[].expiration 获取其到期时间（如果提供）。

申请对类别判定进行复审

如果您认为内容被错误标记，请前往 Meta 业务支持中心 → WhatsApp 账户 → Direct Send 模板更新 → 可申请复审。选择受影响的模板，然后选择 申请复审。请在收到通知后 60 天内提交申诉。每个被标记的模板只能申诉一次。您可以跟踪结果状态，如 In review、 Reversed 或 Unchanged。如果申诉选项不可用，请联系 YCloud 并提供 WABA ID、模板名称或 ID、语言以及通知详情。

Direct Send 常见问题

发送前是否需要模板名称？

自定义内容不需要。只需提供完整的消息，由 Meta 来匹配或生成模板。如需转换现有的 Utility 模板，请提供其 template.name 并设置 useDirectSend: true。可选字段 templateName 用于命名 Utility Direct Send 模板，并非用于选择现有模板。

为什么 Direct Send 仍会生成模板？

模板支持类别和质量审核、效果报告以及问题排查。Direct Send 只是免去了手动创建模板的麻烦，并未取消消息背后的基于模板的处理流程。

我可以在 24 小时客户服务窗口之外发送消息吗？

可以，适用于符合条件的 Utility Direct Send 通知。您的 WABA 必须具备相应权限，客户必须期望接收该消息，且内容必须符合 Utility 要求。普通的自由格式客服消息仍需要有效的服务窗口。

为什么消息发送成功后生成的模板才出现？

模板生成和同步是异步进行的，可能会在消息发送之后完成。完成后，选择正确的 WABA 并使用 Auto generated 筛选器查看。

未使用的已生成模板如何清理？

Meta 会在 24 小时后删除从未用于发送的已生成模板。之前使用过的模板在闲置一段时间后可能会被归档。您无需手动删除它们。

设置为 utility 能否保证 Meta 一定接受该类别？

不能。Meta 会根据实际内容进行评估。请删除 Utility 通知中的促销措辞；如果正当的 Utility 消息被错误标记，请使用申诉流程。

Direct Send 如何计费？

Utility 消息遵循与手动创建的 Utility 模板相同的 Utility 消息定价规则。请参阅 WhatsApp 定价。

开始使用

指南

接口

Webhooks

Direct Send 最佳实践

Direct Send 的工作原理

支持的功能与限制

使用资格与发送范围

消息长度与按钮

消息有效期 (TTL)

支持的消息类型

处理回复按钮响应

通过 YCloud 发送

1. 选择提交模式

2. 构建请求

3. 追踪送达状态

转换现有的 Utility 模板

设置消息生命周期

为 Utility Direct Send 模板命名

模板转换与语言限制

语言支持

在 YCloud 中查看由 Direct Send 生成的模板

合规与内容指南

保持 Utility 内容明确且非促销性

使用消息样本检查新用例（可选）

区分暂停的模板与账户限制

接收 YCloud 通知

申请对类别判定进行复审

Direct Send 常见问题

​Direct Send 的工作原理

​支持的功能与限制

​使用资格与发送范围

​消息长度与按钮

​消息有效期 (TTL)

​支持的消息类型

​处理回复按钮响应

​通过 YCloud 发送

​1. 选择提交模式

​2. 构建请求

​3. 追踪送达状态

​转换现有的 Utility 模板

​设置消息生命周期

​为 Utility Direct Send 模板命名

​模板转换与语言限制

​语言支持

​在 YCloud 中查看由 Direct Send 生成的模板

​合规与内容指南

​保持 Utility 内容明确且非促销性

​使用消息样本检查新用例（可选）

​区分暂停的模板与账户限制

​接收 YCloud 通知

​申请对类别判定进行复审

​Direct Send 常见问题

Direct Send 的工作原理

支持的功能与限制

使用资格与发送范围

消息长度与按钮

消息有效期 (TTL)

支持的消息类型

处理回复按钮响应

通过 YCloud 发送

1. 选择提交模式

2. 构建请求

3. 追踪送达状态

转换现有的 Utility 模板

设置消息生命周期

为 Utility Direct Send 模板命名

模板转换与语言限制

语言支持

在 YCloud 中查看由 Direct Send 生成的模板

合规与内容指南

保持 Utility 内容明确且非促销性

使用消息样本检查新用例（可选）

区分暂停的模板与账户限制

接收 YCloud 通知

申请对类别判定进行复审

Direct Send 常见问题