> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 发送 WhatsApp 消息

> 使用排队或同步 API 发送 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 最佳实践](/zh/api-reference/guides/whatsapp-platform/best-practices/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` 时，会过滤被阻止的接收者。 |

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

请提供 `to` 或 `recipient` 中的至少一个。如果两者都包含，YCloud 将使用 `to` 并忽略 `recipient`。

<Note>
  一键、零点击（zero-tap）以及复制代码身份验证模板需要一个电话
  号码。对于这些模板类型，请使用 `to`。
</Note>

### 请求示例

<AccordionGroup>
  <Accordion title="模板消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "from": "+16315551111",
      "to": "+16315551111",
      "type": "template",
      "template": {
        "name": "sample_whatsapp_template",
        "language": {
          "code": "en",
          "policy": "deterministic"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="文本消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "from": "+16315551111",
      "to": "+16315551111",
      "type": "text",
      "text": {
        "body": "Hello from YCloud!"
      }
    }
    ```
  </Accordion>

  <Accordion title="图片消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "from": "+16315551111",
      "to": "+16315551111",
      "type": "image",
      "image": {
        "id": "MEDIA_ID",
        "caption": "Product image"
      }
    }
    ```
  </Accordion>

  <Accordion title="视频消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "from": "+16315551111",
      "to": "+16315551111",
      "type": "video",
      "video": {
        "id": "MEDIA_ID",
        "caption": "Product video"
      }
    }
    ```
  </Accordion>

  <Accordion title="音频消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "from": "+16315551111",
      "to": "+16315551111",
      "type": "audio",
      "audio": {
        "id": "MEDIA_ID"
      }
    }
    ```
  </Accordion>

  <Accordion title="文档消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "from": "+16315551111",
      "to": "+16315551111",
      "type": "document",
      "document": {
        "id": "MEDIA_ID",
        "filename": "invoice.pdf"
      }
    }
    ```
  </Accordion>

  <Accordion title="贴图消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "from": "+16315551111",
      "to": "+16315551111",
      "type": "sticker",
      "sticker": {
        "id": "MEDIA_ID"
      }
    }
    ```
  </Accordion>

  <Accordion title="位置消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "from": "+16315551111",
      "to": "+16315551111",
      "type": "location",
      "location": {
        "latitude": 37.422,
        "longitude": -122.084,
        "name": "Googleplex",
        "address": "1600 Amphitheatre Pkwy, Mountain View, CA"
      }
    }
    ```
  </Accordion>

  <Accordion title="交互式消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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"
              }
            }
          ]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="联系人消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "from": "+16315551111",
      "to": "+16315551111",
      "type": "contacts",
      "contacts": [
        {
          "name": {
            "formatted_name": "John Smith"
          },
          "phones": [
            {
              "phone": "+16315551111",
              "type": "CELL"
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="回应消息">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "from": "+16315551111",
      "to": "+16315551111",
      "type": "reaction",
      "reaction": {
        "message_id": "wamid.BgNODYxN...",
        "emoji": "👍"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## 响应

成功的响应会返回 YCloud 消息对象。初始的 `status: accepted` 表示 YCloud 已接受发送请求。这并不意味着消息已由 Meta 发送或已送达 WhatsApp 用户。

### 响应示例

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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}`。

<Tip>
  对于媒体消息，请先使用 `POST /whatsapp/media/{phoneNumber}/upload` 上传文件，然后在消息有效负载中使用返回的媒体 ID。
</Tip>

## 限制与故障排查

* 常规模板发送需要 `APPROVED` 模板；`ARCHIVED` 模板
  无法作为普通消息模板发送。
* 在没有幂等策略的情况下，请勿重试已接受的请求。重复的
  请求可能会发送重复的消息。
* 在进行以下操作时，请使用 YCloud `id`、`wamid`、`externalId` 以及 Webhook 状态：
  排查送达情况。
* 当直接请求到达 Meta 且被 Meta 拒绝时，请检查 `whatsappApiError`
  它。

有关吞吐量限制，请参阅[速率限制](/zh/api-reference/guides/api-fundamentals/rate-limits)。

<Card title="直接发送最佳实践" icon="bolt" href="/zh/api-reference/guides/whatsapp-platform/best-practices/direct-send">
  发送效用类内容、转换模板，并监控类别和限制事件。
</Card>

<Card title="生产环境最佳实践" icon="shield-check" href="/zh/api-reference/guides/whatsapp-platform/whatsapp-messages-api-best-practices">
  设计状态同步、有界重试、同意检查、媒体复用，
  以及生产集成的吞吐量控制。
</Card>

<Card title="使用业务范围的用户 ID" icon="user-tag" href="/zh/api-reference/guides/whatsapp-platform/use-business-scoped-user-ids">
  通过 BSUID 发送消息和发起通话、请求电话号码、管理 Meta 联系人
  簿条目，并处理 BSUID Webhook 字段。
</Card>

## 完整集成示例

有关完整的模板创建和变量绑定工作流程，请参阅
[模板创建示例](/zh/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples)
以及 [消息发送示例](/zh/api-reference/guides/examples/api-examples/whatsapp-messaging-examples)。
使用 [WhatsApp 错误处理](/zh/api-reference/guides/whatsapp-platform/handle-whatsapp-errors)
来区分请求被拒与后续的投递失败，并参阅
[Webhook 接收端实现](/zh/api-reference/guides/api-fundamentals/implement-a-webhook-receiver)
以验证签名并持久接收状态更新。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.