Bird Whatsapp Messages API
Send WhatsApp messages, whether a template, free-form content, or interactive content the recipient can tap, and read the messages your workspace sent and received, including their current delivery status and lifecycle events.
Bird Whatsapp Messages API is one of 65 APIs that Bird publishes on the APIs.io network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification.
Tagged areas include whatsapp-messages. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, and an AsyncAPI specification.
This API exposes 9 operations across 7 paths, and defines 100 schemas. It is described by OpenAPI 3.2.0, at version 1.0.0.
Requests are made against 3 base URLs: https://{region}.platform.bird.com, https://platform.bird.com, http://localhost:8080.
9 operations
7 paths
100 schemas
1 DELETE5 GET2 POST1 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 4
Bird Whatsapp Messages API declares
4 security schemes
for authenticating requests.
It accepts HTTP bearer tokens (BearerAuth).
An API key is passed in the cookie as bird_session (CookieAuth).
An API key is passed in the header as X-Realtime-Key (RealtimeKey).
An API key is passed in the header as X-Realtime-Secret (RealtimeSecret).
By default, every request must be authenticated.
BearerAuth— Pass the API key as a bearer token in the Authorization header. Keys use the format bk{region}. The prefix identifies the region and selects the API endpoint.…CookieAuth— Session cookie set after signing in to the Bird dashboard. The cookie value is an opaque session token; no session data is stored in the cookie itself.RealtimeKey— The Realtime app key. Together with X-Realtime-Secret, it authenticates a request to the Realtime API in addition to the workspace credential. Both values come…RealtimeSecret— The Realtime app secret paired with X-Realtime-Key. The API returns the secret only when the key is created and does not store it. Create a new key and revoke…
Paths & Operations 9
Across 7 paths, the API surfaces 9 operations — 1 DELETE, 5 GET, 2 POST, 1 PUT. Each is listed below with its method, path, parameters, and response codes.
whatsapp-messages 9
Send WhatsApp messages, whether a template, free-form content, or interactive content the recipient can tap, and read the messages your workspace sent and received, including thei…
GET
/v1/whatsapp/messages
List WhatsApp messages
POST
/v1/whatsapp/messages
Send a WhatsApp message
GET
/v1/whatsapp/messages/{message_id}
Get a WhatsApp message
POST
/v1/whatsapp/messages/{message_id}/read
Mark a WhatsApp message as read
GET
/v1/whatsapp/messages/{message_id}/events
List events for a WhatsApp message
GET
/v1/whatsapp/messages/{message_id}/media/{media_id}
Get a WhatsApp message's media
PUT
/v1/whatsapp/messages/{message_id}/reaction
React to a WhatsApp message
DELETE
/v1/whatsapp/messages/{message_id}/reaction
Remove your reaction from a WhatsApp message
GET
/v1/whatsapp/messages/{message_id}/reaction-events
List reaction events for a WhatsApp message
Schemas 100
The contract defines 100 schemas that model the data the API accepts and returns. The most detailed are WhatsAppMessage (30 properties), WhatsAppMessageSendRequest (15 properties), ErrorBody (11 properties), WhatsAppContactCard (9 properties). Each schema is shown below with its type and property counts.
WhatsAppInteractiveCardHeaderSend
object
The media at the top of a carousel card. Every card must carry one, and it must be an image or a video: a card takes no text or document header.
2 properties
2 required
_ListEnvelope
object
3 properties
3 required
WhatsAppInteractiveButtonSend
object
One button on an interactive message or on a carousel card. type names the kind and the field that carries it, so a button kind WhatsApp adds later arrives as…
3 properties
1 required
WhatsAppMessageID
string
WhatsAppFileID
string
ErrorDetail
object
2 properties
2 required
WhatsAppDocumentSend
object
A free-form document to send, with an optional caption and filename. Deliverable only inside an open 24-hour customer service window; outside one, send a templ…
3 properties
1 required
WhatsAppContactOrg
object
Where the contact works, as their card records it.
3 properties
WhatsAppReactionEventList
WhatsAppAddress
object
Sender or recipient of a WhatsApp message: a phone number, a business-scoped user ID, or both. A message received from a WhatsApp user carries whatever profile…
5 properties
WhatsAppInteractiveButtonTypeWrite
string
Which kind of button this is, and which field carries it. - quickreply: sends its own identifier back as an inbound message. The name WhatsAppTemplateButtonTyp…
WhatsAppInteractiveListSectionSend
object
One group of options in a list's menu. A menu with a single group still carries a title, which WhatsApp shows above its rows.
2 properties
2 required
WhatsAppGroupID
string
WhatsAppEvent
object
5 properties
3 required
WhatsAppInteractiveQuickReplyButton
object
A reply button's label and the handle it carries back. On the echo of a message Bird sent, the pair the send declared; on an inbound interactivereply, the pair…
2 properties
2 required
MessageCost
objectnull
What was charged for a message, split into the components that make it up. null until at least one component has been priced.
4 properties
4 required
WhatsAppInteractiveHeaderType
string
A header's kind, and which field carries it. Open enum: WhatsApp adds header kinds over time, so treat an unrecognized value as a future kind rather than an er…
WhatsAppInteractiveListSend
object
A menu of options behind a single button. The recipient taps the button, WhatsApp opens the menu, and choosing one option sends it back as a reply.
2 properties
2 required
WhatsAppStickerSend
object
A free-form sticker to send. Deliverable only inside an open 24-hour customer service window; outside one, send a template instead.
1 property
1 required
WhatsAppInteractiveQuickReplyButtonSend
object
One tappable reply button. Tapping it sends slug back as an inbound message, which reads as an interactivereply.
2 properties
2 required
Tag
object
Structured key/value label attached to a message or a call. Use tags for low-cardinality filtering dimensions (category, experiment ID, template ID); they surf…
2 properties
2 required
WhatsAppContactAddress
object
One postal address on a shared contact card.
7 properties
WhatsAppContactNameSend
object
The contact's name. formattedname is what the card shows, and WhatsApp additionally requires at least one of the parts below it, so a card carrying only a form…
6 properties
1 required
WhatsAppMessageSendRequest
object
A WhatsApp message to send. Carry exactly one kind of content: a request with none returns a 422 WhatsAppContentRequired, and one carrying more than one return…
15 properties
1 required
WhatsAppLocation
object
Location content of a WhatsApp message: a point on the map the recipient can open in their maps app.
5 properties
WhatsAppTemplateParameterType
string
The kind of value a template parameter carries, which follows the block it fills. The text type is a plain string substituted into a placeholder. This includes…
WhatsAppContactPhoneSend
object
One phone number to put on a contact card.
2 properties
1 required
WhatsAppInteractiveListSection
object
One group of options in the menu the message showed.
2 properties
2 required
WhatsAppDocument
object
Document content of a WhatsApp message.
WhatsAppInteractiveCtaUrlSend
object
A button that opens a link in the recipient's browser, so a long or opaque address never has to appear in the message body.
2 properties
2 required
WhatsAppReactionEventID
string
WhatsAppInteractiveType
string
Which kind of interactive message this is. - button: up to three tappable buttons, each sending its own identifier back as an inbound message. Carried in butto…
WhatsAppContactUrlSend
object
One website to put on a contact card.
2 properties
1 required
WhatsAppReadReceipt
object
The acknowledgement Bird accepted. There is no status to poll afterwards: WhatsApp reports nothing about a read receipt.
1 property
1 required
ErrorBody
object
11 properties
6 required
WhatsAppUnsupported
object
A message whose content we do not model, named so it is visible in the message log rather than arriving empty. Inbound only.
1 property
1 required
WhatsAppInteractiveCardSend
object
One card in a carousel: media at the top, optional text of its own, and the buttons under it. A card has no footer, and its position in cards is the position i…
3 properties
2 required
WhatsAppReaction
object
An emoji reaction standing on a message. One entry per sender: reacting again replaces that sender's entry rather than adding one, and removing a reaction drop…
2 properties
2 required
WhatsAppInteractiveButton
object
One button the message offered. The field named by type is the one that is present. As on the message itself, the read vocabulary is open: dispatch on type and…
3 properties
1 required
WhatsAppTextSend
object
Free-form text to send. Deliverable only inside an open 24-hour customer service window; outside one, send a template instead.
2 properties
1 required
WhatsAppTemplateSend
object
A send-by-template reference. Identify the template by its id or its slug (supply exactly one), optionally name a language, and fill its placeholders through c…
4 properties
WhatsAppContactEmail
object
One email address on a shared contact card.
2 properties
WhatsAppMessageList
WhatsAppInteractiveReplyType
string
Which kind of tap the reply came from. - button: a reply button on an interactive message, or a quick-reply button on a template. Both carry an identifier and…
WhatsAppImage
object
Image content of a WhatsApp message.
WhatsAppReactionAccepted
object
A reaction as accepted, which WhatsApp has not applied yet and may still refuse. It names the reaction-log entry the request created, so a caller that places t…
2 properties
2 required
MessageDirection
string
Whether a message was sent from the workspace (outbound) or received by it (inbound).
WhatsAppInteractiveListRow
object
One option in a list's menu. On the echo of a message Bird sent, the row as declared; on an inbound interactivereply, the row the contact chose. No length is d…
3 properties
2 required
WhatsAppInteractiveTypeWrite
string
Which kind of interactive message to send. - button: up to three tappable buttons, each sending its own identifier back as an inbound message. Carried in butto…
WhatsAppReadReceiptRequest
object
What to acknowledge on the inbound message. An absent body and {} mean the same thing: mark the message read and show nothing.
1 property
WhatsAppErrorCode
string
Standardized failure reason: - insufficientbalance: The workspace wallet could not fund the send. - pricenotfound: No price was configured for the destination…
WhatsAppInteractive
object
Interactive content of a WhatsApp message: body text plus something the recipient can tap. The field named by type is the one that is present, except on locati…
8 properties
2 required
WhatsAppMessageTemplateComponentParameter
object
5 properties
1 required
WhatsAppMessageTemplateCard
object
The values that fill one card of a carousel. Cards fill in the order the template was approved with, so send one entry per card and keep them in that order.
1 property
1 required
WhatsAppContactEmailSend
object
One email address to put on a contact card.
2 properties
1 required
WhatsAppLocationSend
object
A free-form location to send: a point on the map the recipient can open in their maps app. Deliverable only inside an open 24-hour customer service window; out…
4 properties
2 required
WhatsAppReactionEventStatus
string
What became of one reaction change: - received means the contact placed or removed the reaction and WhatsApp told us about it. Every inbound entry carries this…
WhatsAppInteractiveHeaderTypeWrite
string
A header's kind, and which field carries it. text is a line of copy; the rest each show a file whose address you give in url. A list accepts text only, and a c…
WhatsAppInteractiveSend
object
An interactive message to send: body text plus something for the recipient to tap. Name the kind in type and carry that kind's field alongside it: buttons, lis…
8 properties
2 required
WhatsAppContactOrgSend
object
Where the contact works, as the card should record it.
3 properties
CurrencyCode
string
ISO 4217 three-letter currency code.
WhatsAppInteractiveReply
object
What the contact tapped, on an inbound message answering an interactive message or a template's quick-reply button. type names the kind and the field it names…
3 properties
1 required
NextAction
object
5 properties
2 required
TemplateSlug
string
A template's slug: what you send it by, for example welcome-email. Email and SMS slugs stay fixed after creation. WhatsApp slugs can change only before the fir…
WhatsAppReactionUpsert
object
1 property
1 required
WhatsAppVideo
object
Video content of a WhatsApp message.
WhatsAppMessageTemplate
object
The template a message was sent from. On reads slug, language, category, and components are always present; components is an empty array for an authentication…
4 properties
4 required
WhatsAppInteractiveHeaderSend
object
What to show above an interactive message's body. type names the kind and the field that carries it: text for a line of copy, url for the file every other kind…
3 properties
1 required
WhatsAppMessageTemplateComponent
object
3 properties
1 required
WhatsAppContactName
object
The contact's name, in the parts their device supplied. Every part is optional: WhatsApp sends what the card holds and omits the rest.
6 properties
WhatsAppEventList
object
1 property
1 required
WhatsAppMessage
object
30 properties
6 required
WhatsAppInteractiveListRowSend
object
One option in a list's menu. Choosing it sends slug back as an inbound message, which reads as an interactivereply.
3 properties
2 required
WhatsAppContactCard
object
A contact card on this message: one the contact shared, or one this workspace sent. Nothing here is required. WhatsApp sends the parts the card holds and omits…
9 properties
WhatsAppReactionEvent
object
One change to a reaction on a message: a reaction placed, replaced by a different emoji, or taken back. Entries are never edited, so a sender who reacts twice…
6 properties
5 required
WhatsAppTemplateID
string
WhatsAppAudioSend
object
Free-form audio to send, either as a voice note or as a basic audio file. Deliverable only inside an open 24-hour customer service window; outside one, send a…
2 properties
1 required
WhatsAppImageSend
object
A free-form image to send, with an optional caption. Deliverable only inside an open 24-hour customer service window; outside one, send a template instead.
2 properties
1 required
WhatsAppContactCardSend
object
A contact card to send. WhatsApp shows the name on the card and the rest in a profile view the recipient opens from it. A card carrying a phone number renders…
7 properties
1 required
WhatsAppInteractiveList
object
The menu the message offered: a button that opens it, and the groups of options behind it.
2 properties
2 required
WhatsAppContactUrl
object
One website on a shared contact card.
2 properties
WhatsAppError
objectnull
Failure detail for a message that could not be delivered or was rejected.
4 properties
3 required
WhatsAppSticker
object
Sticker content of a WhatsApp message.
WhatsAppVideoSend
object
A free-form video to send, with an optional caption. Deliverable only inside an open 24-hour customer service window; outside one, send a template instead.
2 properties
1 required
WhatsAppContactPhone
object
One phone number on a shared contact card.
2 properties
WhatsAppEventID
string
WhatsAppContactAddressSend
object
One postal address to put on a contact card.
7 properties
WhatsAppText
object
Text content of a WhatsApp message.
1 property
1 required
WhatsAppMedia
object
Fields shared by every media content object on a WhatsApp message.
3 properties
WhatsAppInteractiveButtonType
string
Which kind of button this is, and which field carries it. - quickreply: sends its own identifier back as an inbound message. - ctaurl: opens a link in the reci…
Error
object
1 property
1 required
WhatsAppMessageStatus
string
Delivery status: - accepted: Accepted and queued for sending. - sent: Handed to the WhatsApp network. - delivered: Confirmed as delivered to the recipient's de…
LanguageTag
string
A language tag in BCP-47 form, for example en or pt-BR.
WhatsAppEventType
string
Message timeline event type: - whatsapp.accepted: The API accepted the request. - whatsapp.sent: The message reached the WhatsApp network. - whatsapp.delivered…
WhatsAppInteractiveHeader
object
What the interactive message showed above its body. type names the kind and the field that carries it: text for a line of copy, url for the file every other ki…
3 properties
1 required
WhatsAppTemplateCategory
string
Meta's content classification for a template. - authentication: delivers one-time passcodes. - utility: delivers transaction-triggered updates (receipts, order…
WhatsAppInteractiveCard
object
One card the carousel showed, in the position it appeared in.
3 properties
2 required
WhatsAppMessageTemplateCardComponent
object
The values that fill one block of one carousel card.
2 properties
1 required
WhatsAppAudio
object
Audio content of a WhatsApp message.
WhatsAppInteractiveCtaUrl
object
The link button the message offered: its label and the address it opens.
2 properties
2 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Bird 12
Other APIs Bird publishes across the network.
Bird Customer Data API
Bird Phone Numbers API
Bird Identity Verification API
Bird Touchpoints API
Bird Accounts API
Bird FAQ API
Bird Intent API
Bird SMS Messaging API
Bird Channels API
Bird Contacts API
Bird Conversations API
Bird Legacy MessageBird API
#whatsapp-messages
Where this information came from
This is an independent, third-party profile of Bird Whatsapp Messages API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.