发送 WhatsApp 消息

什么是消息

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

准备工作

将您的 YCloud API 密钥保存在 YCLOUD_API_KEY 中。
将 WhatsApp 商业账户和电话号码关联至 YCloud。
准备好 E.164 格式的发件人电话号码，以及收件人电话号码、BSUID 或父级 BSUID。
对于普通的模板发送，请使用 APPROVED 模板。
当消息引用 YCloud 媒体 ID 时，请先上传媒体文件。

运作方式

根据 YCloud 应在何时将消息提交给 WhatsApp Business API 来选择端点。

端点	行为	适用场景
`POST /whatsapp/messages`	将消息加入队列并异步提交。	大多数出站消息工作流。
`POST /whatsapp/messages/sendDirectly`	同步向 WhatsApp Business API 提交消息。	OTP 和其他有时效性的消息。

这两个端点都会返回一个 YCloud 消息对象。初始响应并不确认最终送达状态。后续的状态变更会通过 whatsapp.message.updated Webhook 发送。

发送您的第一条消息

选择已连接 WABA 名下已获批准的模板。将发送者、接收者、模板名称和语言替换为您自己的值，然后发送：

curl --request POST https://api.ycloud.com/v2/whatsapp/messages \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "template",
    "externalId": "welcome-10001",
    "template": {
      "name": "welcome_message",
      "language": { "code": "en_US" }
    }
  }'

保存返回的 id 并关注其 whatsapp.message.updated 事件。返回 accepted 响应仅表示请求已进入处理流程，并不代表客户已收到消息。如果您需要送达追踪和客户回复，请同时配置 whatsapp.message.updated 和 whatsapp.inbound_message.received。

选择模板消息或会话消息

在客户服务窗口之外发送常规的企业主动发起的日常消息时，请使用已获批准的模板。在处于打开状态的窗口内，请使用受支持的自由格式消息类型，例如文本、媒体或交互式回复。在发送时检查客户服务窗口规则。计费窗口并不能取代发消息资格。有关当前费用和入口点条件，请参阅WhatsApp 定价。

用于效用内容的 Direct Send

Direct Send 可以提交符合条件的实用性（utility）内容，或转换现有的实用性模板。它适用于任一发送端点。sendDirectly 端点控制同步提交；它本身不会启用 Direct Send。请遵循Direct Send 最佳实践，了解适用资格、请求、模板转换、配额限制以及账户事件相关内容。

选择最佳发送时间

将发送时间与消息目的以及接收者的当地时间相匹配。

立即发送 OTP 及其他时效性消息。使用当您的工作流程需要提交时使用 POST /whatsapp/messages/sendDirectly 结果后再继续。
在相关事件发生时发送交易类更新，例如付款、发货或预约变更。
在接收者所在时区的合理时间段安排发送营销消息。利用您自己的送达、阅读和转化数据来测试不同的时间段针对不同的受众群体进行分析，而不是假设存在一个普适的最佳时间段。
面向小规模受众群体启动定时活动。检查送达情况，响应和退订结果，然后再发送给受众的其他人员。
在消息延迟时避免重复发送。存储 externalId 并处理在决定是否重试之前whatsapp.message.updated Webhook。

请求

选择上面的任一端点，然后使用与消息类型匹配的请求体。from 的值是您已绑定的 WhatsApp 商业电话号码。使用 E.164 格式的 to 或设置为 BSUID 或父级 BSUID 的 recipient 来指定收件人。

常用请求字段

字段	是否必填	描述
`from`	是	采用 E.164 格式的已连接 WhatsApp 商业电话号码。
`to`	条件必填	接收者的电话号码（E.164 格式）。当缺失 `recipient` 时必填。
`recipient`	条件必填	接收者 BSUID 或父级 BSUID。在缺少 `to` 时必填。
`type`	是	消息类型。请包含与此值相匹配的内容字段。
`template`、`text`、`image` 以及其他类型字段	条件必填	所选 `type` 所需的内容对象。
`context`	否	回复之前的消息时所使用的消息上下文。
`externalId`	否	您的唯一参考信息，用于将消息与内部记录进行核对。
`filterUnsubscribed`	否	仅排队入队。默认为 `false`；当为 `true` 时，会过滤退订名单中的收件人。
`filterBlocked`	否	仅加入队列。默认值为 `false`；当为 `true` 时，过滤被拉黑的收件人。

filterUnsubscribed 和 filterBlocked 仅适用于 POST /whatsapp/messages；它们不适用于 sendDirectly。过滤后的排队的消息因 RECIPIENT_UNSUBSCRIBED 而失败，或在其状态 Webhook 中包含 RECIPIENT_IN_BLOCK_LIST。对于同步发送，在您的应用程序中强制执行同意、退订和屏蔽检查。

请至少提供 to 或 recipient 之一。如果两者均包含，YCloud 将使用 to 并忽略 recipient。

一键登录 (One-tap)、零点击登录 (zero-tap) 以及复制代码 (copy-code) 身份验证模板需要提供电话号码。对于这些模板类型，请使用 to。

请求示例

模板消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "template",
  "template": {
    "name": "sample_whatsapp_template",
    "language": {
      "code": "en",
      "policy": "deterministic"
    }
  }
}

文本消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "text",
  "text": {
    "body": "Hello from YCloud!"
  }
}

图片消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "image",
  "image": {
    "id": "MEDIA_ID",
    "caption": "Product image"
  }
}

视频消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "video",
  "video": {
    "id": "MEDIA_ID",
    "caption": "Product video"
  }
}

音频消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "audio",
  "audio": {
    "id": "MEDIA_ID"
  }
}

文档消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "document",
  "document": {
    "id": "MEDIA_ID",
    "filename": "invoice.pdf"
  }
}

贴纸消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "sticker",
  "sticker": {
    "id": "MEDIA_ID"
  }
}

位置消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "location",
  "location": {
    "latitude": 37.422,
    "longitude": -122.084,
    "name": "Googleplex",
    "address": "1600 Amphitheatre Pkwy, Mountain View, CA"
  }
}

互动消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "Do you want to continue?"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "yes",
            "title": "Yes"
          }
        }
      ]
    }
  }
}

联系人消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "John Smith"
      },
      "phones": [
        {
          "phone": "+16315551111",
          "type": "CELL"
        }
      ]
    }
  ]
}

Reaction 消息

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "reaction",
  "reaction": {
    "message_id": "wamid.BgNODYxN...",
    "emoji": "👍"
  }
}

添加模板变量

请将模板名称、语言和参数顺序与您已获批的模板保持一致。对于包含客户姓名和订单参考编号参数的正文，请发送：

{
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Alex" },
          { "type": "text", "text": "ORDER-10001" }
        ]
      }
    ]
  }
}

请参阅模板消息示例，了解其他组件和消息类型。

回复特定消息

将 context.message_id 设置为原始 WhatsApp 消息 ID（wamid）以创建引用回复。请继续确保客户服务窗口处于打开状态。

{
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "text",
  "text": { "body": "Your order is ready for collection." },
  "context": { "message_id": "wamid.EXAMPLE" }
}

应用退订和屏蔽过滤器

对于 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 用户。

响应示例

{
  "id": "MESSAGE_ID",
  "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "text",
  "status": "accepted",
  "externalId": "order-10001",
  "createTime": "2026-07-16T12:00:00.000Z"
}

响应字段

字段	描述
`id`	YCloud 消息 ID。请妥善保存以供检索以及 Webhook 关联使用。
`wamid`	原始 WhatsApp 消息 ID。提交至 WhatsApp 后可用。
`wabaId`	WhatsApp 商业账户 ID。
`from`、`to`	发送方和接收方的电话号码。
`type`	消息内容类型。
`status`	当前状态，例如 `accepted`、`sent`、`failed`、`delivered` 或 `read`。
`errorCode`，`errorMessage`	当 `status` 为 `failed` 时的 YCloud 失败详情。
`whatsappApiError`	WhatsApp Business API 返回的错误（如果有）。
`externalId`	请求中提供的自定义参考信息。
`category`	Direct Send 类别，例如上述实用类（utility）示例中的 `utility`。
`ttlSeconds`	消息上设置的 Direct Send 消息生命周期。
`totalPrice`，`currency`	预估或最终的消息费用及币种。
`createTime`, `sendTime`, `deliverTime`, `readTime`	RFC 3339 格式的生命周期时间戳。

送达状态

订阅 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 接收器实现以验证签名并持久接收状态更新。

开始使用

指南

接口

Webhooks

发送 WhatsApp 消息

什么是消息

准备工作

运作方式

发送您的第一条消息

选择模板消息或会话消息

用于效用内容的 Direct Send

选择最佳发送时间

请求

常用请求字段

请求示例

添加模板变量

回复特定消息

应用退订和屏蔽过滤器

响应

响应示例

响应字段

送达状态

限制和故障排除

直接发送最佳实践

生产最佳实践

使用企业范围的用户 ID

完整集成示例

​什么是消息

​准备工作

​运作方式

​发送您的第一条消息

​选择模板消息或会话消息

​用于效用内容的 Direct Send

​选择最佳发送时间

​请求

​常用请求字段

​请求示例

​添加模板变量

​回复特定消息

​应用退订和屏蔽过滤器

​响应

​响应示例

​响应字段

​送达状态

​限制和故障排除

直接发送最佳实践

生产最佳实践

使用企业范围的用户 ID

​完整集成示例

什么是消息

准备工作

运作方式

发送您的第一条消息

选择模板消息或会话消息

用于效用内容的 Direct Send

选择最佳发送时间

请求

常用请求字段

请求示例

添加模板变量

回复特定消息

应用退订和屏蔽过滤器

响应

响应示例

响应字段

送达状态

限制和故障排除

完整集成示例