WhatsApp API FAQ

Install the SDK, grab an API key, and call the send endpoint with a pre-approved template. Bird provides managed sender numbers, so there is no number provisioning step before your first send.

One send endpoint that takes a template or free-form content, a pre-approved template catalog, delivery and read-receipt events over the API and webhooks, a per-message event timeline, inbound messages and media, aggregate delivery metrics, and Bird-managed sender numbers for your first send. Same API keys and regional hosts as Bird Email and SMS.

It means Bird accepted your message and will deliver it asynchronously. The 202 is not a delivery confirmation. Delivery, read receipts, and failures arrive later as events you can poll or receive via webhooks.

Both. A template reaches anyone at any time, which is why it is the only way to start a conversation. Free-form content reaches a contact inside the 24-hour customer service window their own message opens, and only from a number your workspace owns. Bird does not track that window for you, so a free-form send outside one is accepted and then fails with service_window_expired.

Yes. A contact's message arrives on the whatsapp.received webhook, lands in the WhatsApp log in the dashboard, and counts on the Inbound tab of the Metrics page. Inbound reaches you on your own numbers only: Bird-managed numbers are shared across workspaces, so a message sent to one is not recorded for yours.

Per message, based on the template's category (authentication, utility, or marketing) and the recipient's country. The charge happens when Bird accepts the message, not when the recipient reads it.

A higher per-message rate Meta charges when your business is located outside the recipient's country and you send authentication templates. Eligibility begins after you send more than 750,000 authentication-template messages to users in one country during a moving 30-day period. Your primary business location, set in Meta Business Manager, determines which sends qualify.

Shared senders always pay the international rate for authentication templates, regardless of your volume threshold. All WhatsApp numbers are currently Bird-managed, so this rate applies to authentication sends where your business is outside the recipient's country.

The Usage and Spend pages in the dashboard show your WhatsApp costs. The message log shows the category and cost on each individual message once it is priced.

No. Each WhatsApp message is a separate API call to POST /v1/whatsapp/messages with one recipient. To send to many recipients, loop over the send endpoint.

The whatsapp_send rate group applies to the send endpoint. Every response carries an IETF RateLimit header with the remaining quota and reset time, so pace against that rather than a hardcoded number. Paid plans raise the base rate.

Yes, as free-form content. The send endpoint carries image, video, audio, sticker, document, and location alongside text. Like any free-form send, each one needs an open 24-hour customer service window and a number your workspace owns. Template parameters themselves stay text-based.

A pre-approved message structure registered with WhatsApp through Meta. Each template has a name, one or more languages, a category (authentication, utility, or marketing), and placeholder variables you fill in at send time. Bird ships a managed catalog you can send straight away, and you can author your own once you have connected a WhatsApp Business Account.

Meta reviews and approves every template, whether Bird submitted it or you did. A template can be active overall but have individual languages in a rejected or paused state, so check the per-language status before sending in that language.

Authentication (one-time passcodes and login flows), utility (order updates, account notifications), and marketing (promotions and offers). The category determines which sender number Bird selects and how the message is priced.

Pass a components array with body and button parameters when you send. Parameters can be named (matched by a key like 'name') or positional (matched by index). Named parameters are safer when a template's variable order might change.

Yes, on the Templates page in the dashboard, once your workspace has connected a WhatsApp Business Account of its own. The builder covers body text in a single language today. Authoring over the public API is not available, but the send endpoint takes any template your workspace can send, managed or your own.

No. Bird provides managed sender numbers. Authentication templates send from a dedicated number, and utility and marketing templates share a notification number. The Numbers page in the dashboard lists the numbers available to your workspace.

Yes, and connecting one is what unlocks sending as your own brand: your own templates, free-form content inside an open customer service window, and inbound messages. Bird-managed numbers are shared across workspaces and carry managed templates only, so treat them as the zero-setup path to a first send rather than the end state.

For a managed template, by its category: authentication uses a dedicated sender number, while utility and marketing share a notification number. Everything else names its own sender in the from field, which has to be a number your workspace owns, and a template you authored has to sit on the same WhatsApp Business Account as that number.

POST to /v1/whatsapp/messages with the recipient's E.164 phone number, a template slug, and values for the template's variables. Bird validates the request, returns 202 with a message ID, and delivers asynchronously.

Pass an Idempotency-Key header and a retried request returns the original result instead of sending twice. Without one, a retry is treated as a new message and the recipient gets a duplicate.

Yes. Tags are up to 20 structured labels you can filter and group by in the message log and metrics. Metadata is arbitrary JSON (up to 2 KB) returned on the message and its events, useful for correlating sends with your own systems.

Every state change fires a webhook event: accepted, sent, delivered, read, failed, or rejected. You can also poll the message's event timeline via the API. A delivered status means WhatsApp confirmed the recipient's device received it.

Six lifecycle events: whatsapp.accepted (Bird queued it), whatsapp.sent (submitted to WhatsApp), whatsapp.delivered (recipient's device got it), whatsapp.read (recipient opened it), whatsapp.failed (WhatsApp refused it after submission), and whatsapp.rejected (Bird refused it before submission, not charged).

No. A read event means the recipient opened the message, but the message status stays at delivered. Read is reported separately as a timestamp and a whatsapp.read event, not as a status change.

Rejected means Bird refused the message before submitting it to WhatsApp, so you are not charged. Failed means Bird submitted it but WhatsApp refused delivery. Both carry an error object with a code, description, and Meta error code when applicable.

Two ways: pull the timeline for a specific message with GET /v1/whatsapp/messages/{id}/events, or subscribe a webhook endpoint to whatsapp.* event types and receive them as they happen. The dashboard Messages page also renders the event timeline per message.

The Metrics page in the WhatsApp dashboard app. It shows delivery rate, failure rate, accepted volume, and delivery latency (processing and end-to-end) across everything your workspace sends.

By sender number, by template, by template category, and by tag. A failure rate that looks fine overall often turns out to be one template or one tag driving most of the errors.

Two: processing latency (Bird's side, from accept to submit) and total latency (end-to-end, from accept to delivery receipt). Both are reported at p50, p95, and p99.

Not yet for aggregate stats. You can build your own aggregations from webhook events or from the message list API, which carries the status and event timeline for each message.

WhatsApp provides end-to-end encryption for messages between the sender and the recipient's device. Your API call to Bird is over HTTPS, and webhook events Bird sends you are HMAC-signed.

Every event is HMAC-signed. Verify the signature with your endpoint's secret before acting on the payload, and rotate that secret from the dashboard when you need to.

In the region your organization is hosted in, either us1 or eu1. Your API key carries it in its prefix (bk_us1_, bk_eu1_), which is how the SDKs and CLI pick the right endpoint without you configuring one.

Only what you scope it to. A key carries a list of scopes, each at read or write, so a key that sends WhatsApp messages cannot manage your numbers or read another channel. Keys also support IP allowlists and safe rotation with a configurable grace period.

Certifications and security documentation are at trust.bird.com. The data processing agreement, privacy statement, and acceptable use policy are at bird.com/legal. For a vendor questionnaire, your Bird account team handles it.