---
title: "Bird"
description: "Use Bird for MainSDK WhatsApp notifications, WhatsApp sign-in codes and phone checks, with no SMS or email driver yet - main.yaml, secrets and swapping."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/bird"
updated: "2026-10-28"
---

# Bird

> Use Bird for MainSDK WhatsApp notifications, WhatsApp sign-in codes and phone checks, with no SMS or email driver yet - main.yaml, secrets and swapping.

Canonical: https://mainsdk.dev/docs/integrations/bird · Updated: 2026-10-28

Bird (formerly MessageBird) is a messaging platform for WhatsApp, SMS and email. In a MainSDK app it is a WhatsApp channel driver for [`notify`](https://mainsdk.dev/docs/interfaces/notify), a sender for WhatsApp one-time codes in [`auth`](https://mainsdk.dev/docs/interfaces/auth), and a provider for phone and email checks in [`verify`](https://mainsdk.dev/docs/interfaces/verify). Pick it when you want WhatsApp through a messaging provider rather than directly through Meta.

## Interfaces it serves

### Phone, email and identity checks (`verify`)

- Status: Building for 0.7 · ships as a beta API
- Driver: `bird` (Bird)
- Docs: https://mainsdk.dev/docs/interfaces/verify.md

```yaml
verify:
  driver: bird
```

Swap to another provider: `twilio-verify`, `local`, `digilocker`, `onfido`, `persona`.

### Notifications (`notify`)

- Status: Building for 0.3 · ships as a stable API
- Driver: `bird` (Bird). WhatsApp channel in the spec; SMS and email through Bird are named only in the requirements
- Docs: https://mainsdk.dev/docs/interfaces/notify.md

```yaml
notify:
  driver: bird
```

Swap to another provider: `whatsapp-cloud`, `msg91`, `twilio`, `local`, `fcm`, `apns`, `expo`, `resend`, `ses`, `onesignal`, `slack`, `pagerduty`, `opsgenie`, `webhook`.

### Email (`email`)

- Status: Building for 0.3 · ships as a stable API
- Driver: `bird` (Bird, planned driver)
- Docs: https://mainsdk.dev/docs/interfaces/email.md

```yaml
email:
  driver: bird
```

Swap to another provider: `resend`, `ses`, `local`, `postmark`, `smtp`.

## Before you start

1. Create a Bird workspace and an access key for this app.
2. Connect a WhatsApp Business number as a channel and get your message templates approved.
3. For phone checks, set up Bird's verification for the countries you serve.

Store the access key in your secrets manager.

## Configure

```yaml title="main.yaml"
notify:
  channels: [whatsapp, email]
  whatsapp: bird
  bird:
    workspace: "ws_123"                  # the Bird workspace id
    channel: "ch_123"                    # the WhatsApp channel id
    key: secret:BIRD_ACCESS_KEY          # an access key; this is the default name
    project: "proj_123"                  # optional: the template project id
    version: latest                      # optional: the template version
  templates:
    order.shipped:
      whatsapp: { name: order_shipped, language: en, params: [orderId] }
auth:
  whatsapp: { driver: bird }
verify:
  driver: bird
  drivers:
    bird: { workspace: ws_123, channel: ch_sms, key: secret:BIRD_ACCESS_KEY }   # an SMS channel
```

- `workspace` and `channel` are required for sending.
- A literal key fails validation with `MAIN-CONFIG-0004`.
- Bird sends WhatsApp only. There is no Bird SMS or email driver: `email.driver: bird` is not accepted.

> **Warning:** The Bird request shape is written from Bird's documentation and is unverified against the live API. Verify with a sandbox key before production: send one template message to your own number with the template approved on the channel.

### What the driver sends

Each message is one `POST https://api.bird.com/workspaces/<workspace>/channels/<channel>/messages` with `Authorization: AccessKey <key>`. The JSON body holds the receiver (the phone number as a `phonenumber` contact) and a template body: the template name, the locale, the optional `projectId` and `version`, and the parameters as named string values, keyed by the names in `params`. The `id` Bird returns becomes the delivery's `providerId`. The call goes through MainSDK's network layer, is never retried by it, does not follow redirects, and reads at most 64 KiB of the answer. A 429, a 5xx or no answer is a retryable `MAIN-NOTIFY-0007` and `notify` tries the next channel. MainSDK does not read Bird's delivery events.

For `verify`, Bird sends the six-digit code MainSDK made as a text message on an SMS channel: one `POST` to the same endpoint with a `text` body (`{code} is your verification code. It expires in {minutes} minutes.`, which `drivers.bird.text` can change). A 429, a 5xx or no answer is a retryable `MAIN-VERIFY-0003`; a 4xx is not retryable and leaves the answer the same as for any other number.

> **Note:** The Bird `verify` request is written from Bird's documentation and tested against recorded replies. Send one real code to your own number from a sandbox channel before launch.

## Use it

```ts title="app/orders/ship.ts"
import { notify } from "mainsdk";
import { verify } from "mainsdk/verify";

await notify(user, { template: "order.shipped", data: { orderId: order.id }, category: "orders" });

const started = await verify.phone({ number: input.phone, for: user });   // then verify.phone.check({ id: started.id, code })
```

`auth.whatsapp.send()` and `auth.whatsapp.verify()` work the same with Bird as the sender.

## Local development and testing

With `notify.whatsapp: local`, `mainsdk dev` logs one line per WhatsApp message with the number masked. `createTestApp()` from `@mainsdk/testing` runs `notify` on a local channel; read it with `channels(app).whatsapp`. `channels(app).whatsapp?.failNext(1)` simulates an outage, and `fakeMessagingServer("bird")` records the request the real driver makes. For `verify`, set `verify.driver: local` and read the codes from `app.verifyKit().outbox`.

## What MainSDK adds on top

- WhatsApp only with recorded consent (`MAIN-NOTIFY-0004` otherwise) and approved templates.
- Opt-outs and quiet hours respected; a retry never sends twice.
- Sign-in codes single use, expiring and rate limited per phone and per IP.

See [Notifications](https://mainsdk.dev/docs/interfaces/notify).

## Limits and notes

- The WhatsApp channel driver is built (spec `email-notify`). The `auth.whatsapp` sender comes with the auth spec. SMS and email through Bird are not built.
- The driver declares its own host, `api.bird.com`, so `network.allow` does not change.
- `verify:bird` is built (spec `verify`): it sends the code by SMS through the same host.

## Swap to or from it

```yaml title="main.yaml"
notify:
  whatsapp: whatsapp-cloud   # was bird
```

Sending is stateless, but your number and approved templates belong to your WhatsApp Business Account; check the new provider can use them before switching.

## FAQ

**Can I send SMS through Bird?** Not yet. Bird SMS is a later driver; use Twilio or MSG91 for SMS today.

**Is Bird the same as MessageBird?** Yes, MessageBird renamed itself Bird.

## Next

- [Notifications](https://mainsdk.dev/docs/interfaces/notify), [Sign-in and sessions](https://mainsdk.dev/docs/interfaces/auth) and [Phone, email and identity checks](https://mainsdk.dev/docs/interfaces/verify)
- [WhatsApp](https://mainsdk.dev/docs/integrations/whatsapp), [MSG91](https://mainsdk.dev/docs/integrations/msg91) and [Twilio](https://mainsdk.dev/docs/integrations/twilio)