发送 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 推送。

直接发送实用类内容

Direct Send 可以提交符合条件的实用性内容，或转换现有的实用性模板。它适用于任一发送端点。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。

一键、零点击（zero-tap）以及复制代码身份验证模板需要一个电话号码。对于这些模板类型，请使用 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"
        }
      ]
    }
  ]
}

回应消息

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

响应

成功的响应会返回 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`。
`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 消息

功能简介

准备工作

工作原理

直接发送实用类内容

选择最佳发送时间

请求

通用请求字段

请求示例

响应

响应示例

响应字段

送达状态

限制与故障排查

直接发送最佳实践

生产环境最佳实践

使用业务范围的用户 ID

完整集成示例

​功能简介

​准备工作

​工作原理

​直接发送实用类内容

​选择最佳发送时间

​请求

​通用请求字段

​请求示例

​响应

​响应示例

​响应字段

​送达状态

​限制与故障排查

直接发送最佳实践

生产环境最佳实践

使用业务范围的用户 ID

​完整集成示例

功能简介

准备工作

工作原理

直接发送实用类内容

选择最佳发送时间

请求

通用请求字段

请求示例

响应

响应示例

响应字段

送达状态

限制与故障排查

完整集成示例