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, a pre-approved template catalog, delivery and read-receipt events over the API and webhooks, a per-message event timeline, aggregate delivery metrics, and Bird-managed sender numbers. 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.

Templates only, for now. Every business-initiated WhatsApp message must name a pre-approved template and supply its variables. Free-text sends are not available yet.

Not yet. The channel is outbound-only today. Inbound message handling is on the roadmap but not available through the API or dashboard.

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. It kicks in automatically once you cross 750,000 messages in a rolling 30-day window. 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.

Not through the API yet. The current send endpoint supports text-based template parameters only. Image, video, and document parameters are on the roadmap.

Not yet. Every business-initiated send requires a pre-approved template. Free-text messaging and the 24-hour customer service window are not available through the Bird API today.

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 manages the templates; you browse and send them.

Meta reviews and approves every template. Bird manages the submission. 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.

Not yet through the Bird API or dashboard. Templates are currently Bird-managed and pre-approved. You can browse the available templates and their content on the Templates page in the dashboard or via the API.

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.

Not yet. Bring-your-own-number is not available. All sends go through Bird-managed numbers, and the API has no from field because Bird selects the sender based on the template's category.

By the template's category. Authentication templates use a dedicated sender number, while utility and marketing templates share a separate notification number. You do not choose the sender per message.

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.