---
title: "发送您的第一条 WhatsApp 消息"
description: "创建 Bird API 密钥，无需连接号码即可向您的手机发送一条预先审核通过的 WhatsApp 模板消息，并查看其投递状态。"
canonical: "https://bird.com/zh-sg/wendang/get-started/send-your-first-whatsapp"
---

# 发送您的第一条 WhatsApp 消息

使用 Bird WhatsApp 向您自己的手机发送一条 WhatsApp 消息，然后读取该消息以确认投递。由企业主动发起的发送需要使用预先审核通过的模板。本快速入门从 Bird 的托管模板目录（例如 `bird_delivery_update` 或 `bird_otp`）发送消息，这些模板使用由 Bird 管理的共享 WhatsApp 发送方。您无需先连接 WhatsApp Business Account 或注册号码。

开始之前，请确保您组织的钱包有余额。WhatsApp 模板发送会从钱包扣费，如果余额不足以支付，Bird 会拒绝发送并返回 `402` `WalletInsufficientBalance`。有关充值，请参阅[支付方式和钱包](/docs/knowledge-base/billing/payment-methods-wallet)。

## 1. 创建 API 密钥

在控制台中，前往 **Platform tools** > [**API keys**](https://bird.com/dashboard/w/api-keys)，创建一个具有 `whatsapp:write` 权限范围的密钥，该范围涵盖发送和读取消息。密钥按区域划分，形如 `bk_us1_...` 或 `bk_eu1_...`。前缀中的区域决定您要调用哪个 API 主机：`https://us1.platform.bird.com` 或 `https://eu1.platform.bird.com`。

![Bird 控制台中的 API Keys 页面，列出各密钥的掩码前缀、权限范围和最近使用时间](/images/docs/dashboard-api-keys.png)

完整密钥仅在创建时显示**一次**。请将其复制到安全的位置，然后导出为环境变量，供 cURL 示例使用：

```bash
export BIRD_API_KEY="bk_us1_..."
```

## 2. 发送模板消息

从 Bird 的托管目录向您的手机发送预先审核通过的 `bird_delivery_update` 模板，或使用 `bird_otp` 发送一次性验证码。托管模板以 `bird_` 开头，并从共享的 Bird 号码发送，因此您无需提供 `from`。请按照对应语言的 [SDK 快速入门](/docs/get-started/quickstarts)安装 Bird SDK。如果您使用 [Bird CLI](/docs/cli) 选项卡，请先安装它（`curl -fsSL https://cli.bird.com/install.sh | sh`），并以写入权限完成身份验证（`bird auth login --scope whatsapp:write`）。

在 SDK 选项卡中，替换示例 API 密钥，并将 `+15551234567` 替换为您的 [E.164](https://en.wikipedia.org/wiki/E.164) 格式手机号码。CLI 使用您的登录信息，cURL 选项卡使用 `BIRD_API_KEY`。

**TypeScript**

```typescript
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_delivery_update",
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", name: "ref", text: "A1B2C3D4" },
          { type: "text", name: "date", text: "10 Jul 2026" },
        ],
      },
    ],
  },
});

console.log(msg.id, msg.status);
```

Examples: [TypeScript](/zh-sg/wendang/get-started/send-your-first-whatsapp.ts.md) · [Python](/zh-sg/wendang/get-started/send-your-first-whatsapp.py.md) · [Go](/zh-sg/wendang/get-started/send-your-first-whatsapp.go.md) · [PHP](/zh-sg/wendang/get-started/send-your-first-whatsapp.php.md) · [CLI](/zh-sg/wendang/get-started/send-your-first-whatsapp.cli.md) · [MCP](/zh-sg/wendang/get-started/send-your-first-whatsapp.mcp.md) · [cURL](/zh-sg/wendang/get-started/send-your-first-whatsapp.curl.md)

如果你的密钥以 `bk_eu1_` 开头，请改为调用 `https://eu1.platform.bird.com`。

API 返回 `202 Accepted` 和已创建的消息。消息的 `id` 以 `wam_` 开头，`status` 为 `accepted`，表示 Bird 已接受该消息，并将异步投递。请保留 `id`，下一步会用到。

## 3. 检查投递状态

按 `wam_` ID 获取消息。将 `WHATSAPP_MESSAGE_ID` 替换为第 2 步中的 `id`，并将 SDK 标签页中的示例 API 密钥替换为你自己的密钥：

**TypeScript**

```typescript
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.get("WHATSAPP_MESSAGE_ID");

console.log(msg.id, msg.status);
```

Examples: [TypeScript](/zh-sg/wendang/get-started/send-your-first-whatsapp.ts.md) · [Python](/zh-sg/wendang/get-started/send-your-first-whatsapp.py.md) · [Go](/zh-sg/wendang/get-started/send-your-first-whatsapp.go.md) · [PHP](/zh-sg/wendang/get-started/send-your-first-whatsapp.php.md) · [CLI](/zh-sg/wendang/get-started/send-your-first-whatsapp.cli.md) · [cURL](/zh-sg/wendang/get-started/send-your-first-whatsapp.curl.md)

`status` 字段表示消息当前所处的阶段：

- `accepted`：Bird 已接收该消息，正准备将其交给 WhatsApp。
- `sent`：WhatsApp 已接受该消息，`sent_at` 记录接受时间。
- `delivered`：WhatsApp 已确认消息送达收件人的设备，`delivered_at` 记录送达时间。收件人阅读消息后，系统会设置 `read_at`，而 `status` 仍为 `delivered`。
- `failed` 或 `rejected`：消息未能送达手机。`last_error` 给出原因，[消息状态事件](/docs/guides/whatsapp/events/message-status)列出了错误代码。

持续轮询，直到状态不再是 `accepted` 或 `sent`；也可以订阅 [WhatsApp webhook](/docs/guides/whatsapp/webhooks)，接收每次投递和已读状态变更（`whatsapp.sent`、`whatsapp.delivered`、`whatsapp.read`、`whatsapp.failed`）。由 Bird 管理的共享号码仅用于外发，不会将收到的回复转到你的工作区；如需接收回复，请[连接你自己的号码](/docs/guides/whatsapp/numbers/connect)。每条消息及其事件时间线也会显示在 [**Messages**](https://bird.com/dashboard/w/whatsapp/messages) 页面上。

## 修复发送失败

- **`402` `WalletInsufficientBalance`**：钱包余额不足以支付该消息。请为钱包充值，然后重新发送。
- **`403` `InsufficientScope`**：该 API 密钥缺少 `whatsapp` 权限范围。请编辑该密钥的权限范围，或创建一个带有 `whatsapp:write` 的密钥。
- **`422` `WhatsAppInvalidRecipient`**：`to` 号码不是有效的 E.164 电话号码。请检查开头的 `+`、国家代码和用户号码。

## 后续步骤

- [发送 WhatsApp 消息](/docs/guides/whatsapp/sending-whatsapp)：在 24 小时客户服务窗口内发送模板消息和自由格式的服务消息。
- [WhatsApp 模板](/docs/guides/whatsapp/templates)：浏览托管模板目录（`bird_otp`、`bird_delivery_update` 等），或[创建您自己的模板](/docs/guides/whatsapp/authoring-templates)。
- [连接电话号码](/docs/guides/whatsapp/numbers/connect)：接入您自己的 WhatsApp Business Account 和发送号码，使您的工作区也能接收入站回复。
- [WhatsApp webhook](/docs/guides/whatsapp/webhooks)：接收送达回执和已读回执（使用您自己连接的号码时，还可接收入站消息）。
- [WhatsApp API 参考](/docs/api/reference/create-whatsapp-message)：完整的请求和响应结构。

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [Connect WhatsApp](/whatsapp-api) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp-connect)