Bird

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

verify:
  driver: bird

notify:
  driver: bird

email:
  driver: bird

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

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.

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.

Use it

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.

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

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, Sign-in and sessions and Phone, email and identity checks
• WhatsApp, MSG91 and Twilio