---
title: "Send your first WhatsApp message"
description: "Create a Bird API key, send a pre-approved WhatsApp template message to your phone without connecting a number, and check its delivery status."
canonical: "https://bird.com/docs/get-started/send-your-first-whatsapp"
---

# Send your first WhatsApp message

Send a WhatsApp message to your own phone with Bird WhatsApp, then read the message back to confirm delivery. Business-initiated sends use a pre-approved template. This quickstart sends from Bird's managed template catalog (such as `bird_delivery_update` or `bird_otp`), which uses a shared Bird-managed WhatsApp sender. You do not need to connect a WhatsApp Business Account or register a number first.

Before you start, make sure your organization's wallet has funds. WhatsApp template sends draw on the wallet, and Bird refuses a send the balance cannot cover with `402` `WalletInsufficientBalance`. [Payment methods and wallet](/docs/knowledge-base/billing/payment-methods-wallet) covers topping up.

## 1. Create an API key

In the dashboard, go to **Platform tools** > [**API keys**](https://bird.com/dashboard/w/api-keys) and create a key with the `whatsapp:write` scope, which covers sending and reading messages. Keys are scoped to a region and look like `bk_us1_...` or `bk_eu1_...`. The region in the prefix tells you which API host to call: `https://us1.platform.bird.com` or `https://eu1.platform.bird.com`.

![The API Keys page in the Bird dashboard, listing keys with their masked prefix, scopes, and last-used time](/images/docs/dashboard-api-keys.png)

The full key is shown **once**, at creation time. Copy it somewhere safe, then export it for the cURL examples:

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

## 2. Send a template message

Send the pre-approved `bird_delivery_update` template from Bird's managed catalog to your phone, or use `bird_otp` to send a one-time passcode. Managed templates start with `bird_` and send from a shared Bird number, so you omit `from`. Install the Bird SDK for your language by following its [SDK quickstart](/docs/get-started/quickstarts). If you use the [Bird CLI](/docs/cli) tab, install it (`curl -fsSL https://cli.bird.com/install.sh | sh`) and authenticate with write access first (`bird auth login --scope whatsapp:write`).

In the SDK tabs, replace the example API key, and replace `+15551234567` with your mobile number in [E.164](https://en.wikipedia.org/wiki/E.164) format. The CLI uses your login, and the cURL tab uses `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](/docs/get-started/send-your-first-whatsapp.ts.md) · [Python](/docs/get-started/send-your-first-whatsapp.py.md) · [Go](/docs/get-started/send-your-first-whatsapp.go.md) · [PHP](/docs/get-started/send-your-first-whatsapp.php.md) · [CLI](/docs/get-started/send-your-first-whatsapp.cli.md) · [MCP](/docs/get-started/send-your-first-whatsapp.mcp.md) · [cURL](/docs/get-started/send-your-first-whatsapp.curl.md)

If your key starts with `bk_eu1_`, call `https://eu1.platform.bird.com` instead.

The API responds with `202 Accepted` and the created message. Its `id` starts with `wam_`, and its `status` is `accepted`: Bird has accepted the message and delivers it asynchronously. Keep the `id` for the next step.

## 3. Check the delivery status

Fetch the message by its `wam_` ID. Replace `WHATSAPP_MESSAGE_ID` with the `id` from step 2, and replace the example API key in the SDK tabs with your own:

**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](/docs/get-started/send-your-first-whatsapp.ts.md) · [Python](/docs/get-started/send-your-first-whatsapp.py.md) · [Go](/docs/get-started/send-your-first-whatsapp.go.md) · [PHP](/docs/get-started/send-your-first-whatsapp.php.md) · [CLI](/docs/get-started/send-your-first-whatsapp.cli.md) · [cURL](/docs/get-started/send-your-first-whatsapp.curl.md)

The `status` field reports where the message is:

- `accepted`: Bird admitted the message and is preparing to hand it to WhatsApp.
- `sent`: WhatsApp accepted the message, and `sent_at` records when.
- `delivered`: WhatsApp confirmed delivery to the recipient's device, and `delivered_at` records when. When the recipient reads the message, `read_at` is set while `status` stays `delivered`.
- `failed` or `rejected`: the message did not reach the phone. `last_error` gives the reason, and [Message status events](/docs/guides/whatsapp/events/message-status) lists the error codes.

Poll until the status leaves `accepted` and `sent`, or subscribe to [WhatsApp webhooks](/docs/guides/whatsapp/webhooks) to receive each delivery and read status change (`whatsapp.sent`, `whatsapp.delivered`, `whatsapp.read`, `whatsapp.failed`). Shared Bird-managed numbers are outbound-only and do not route inbound replies to your workspace; to receive replies, [connect your own number](/docs/guides/whatsapp/numbers/connect). Every message also appears on the [**Messages**](https://bird.com/dashboard/w/whatsapp/messages) page with its event timeline.

## Fix a failed send

- **`402` `WalletInsufficientBalance`**: the wallet cannot cover the message. Top up the wallet, then send again.
- **`403` `InsufficientScope`**: the API key lacks the `whatsapp` scope. Edit the key's scopes or create a key with `whatsapp:write`.
- **`422` `WhatsAppInvalidRecipient`**: the `to` number is not a valid E.164 phone number. Check the leading `+`, country code, and subscriber digits.

## Next steps

- [Sending WhatsApp messages](/docs/guides/whatsapp/sending-whatsapp): send templates and free-form service messages inside the 24-hour customer service window.
- [WhatsApp templates](/docs/guides/whatsapp/templates): browse the managed catalog (`bird_otp`, `bird_delivery_update`, and others) or [create your own templates](/docs/guides/whatsapp/authoring-templates).
- [Connect a phone number](/docs/guides/whatsapp/numbers/connect): bring your own WhatsApp Business Account and sender number so your workspace can also receive inbound replies.
- [WhatsApp webhooks](/docs/guides/whatsapp/webhooks): receive delivery receipts and read receipts (plus inbound messages when using your own connected number).
- [WhatsApp API reference](/docs/api/reference/create-whatsapp-message): the full request and response schema.

## 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)