Send a WhatsApp message
/v1/whatsapp/messagesconst msg = await bird.whatsapp.send({
to: "+15551234567",
template: {
slug: "bird_otp",
components: [{ type: "body", parameters: [{ type: "text", text: "123456" }] }],
},
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+31612345678",
template="bird_otp",
language="en",
components=[{"type": "body", "parameters": [{"type": "text", "text": "123456"}]}],
)
print(msg.id, msg.status)code := "123456"
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+15551234567",
Template: "bird_otp",
Language: "en",
Components: []bird.WhatsAppMessageTemplateComponent{{
Type: "body",
Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Text: &code}},
}},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)$message = $bird->whatsapp->send(
to: '+15551234567',
template: 'bird_otp',
language: 'en',
components: [
(new WhatsAppMessageTemplateComponent())
->setType('body')
->setParameters([
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setText('123456'),
]),
],
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--components '[{"parameters":[{"text":"1234","type":"text"}],"type":"body"},{"parameters":[{"text":"1234","type":"text"}],"type":"button"}]' \
--language en \
--template bird_otp \
--to +31612345678curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": "+31612345678",
"template": {
"slug": "bird_otp",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "1234"
}
]
},
{
"type": "button",
"parameters": [
{
"type": "text",
"text": "1234"
}
]
}
]
}
}'{
"id": "wam_01kya19eknftrs2s6p82asmvnh",
"direction": "outbound",
"from": {
"phone_number": "+15550001111"
},
"to": {
"group_id": "wag_01krdgeqcxet5s7t44vh8rt9mg"
},
"text": {
"body": "The route sheet for Tuesday is up."
},
"status": "accepted",
"recipient_count": 2,
"delivered_count": 0,
"read_count": 0,
"created_at": "2026-09-15T14:03:10Z"
}
Sends one WhatsApp message to one recipient. The request carries exactly one
kind of content: a message template, or free-form text, image, video,
audio, sticker, document, location, contact_cards or
interactive. A request carrying none is rejected with a 422, and one
carrying more than one is too.
A template is the only content WhatsApp delivers outside an open
customer service window, so it is what starts a conversation. Name the
template, optionally pick its language variant, and fill its placeholders in
components. A Bird-managed template selects its sender number from its
category, so the request carries no from; a template your workspace
authored requires one. Browse your workspace's templates in the Bird
dashboard.
Free-form content is deliverable only inside an open 24-hour customer
service window, which the contact opens by messaging or calling you and
resets each time they do it again. Bird tracks that window, so a send into a
closed one is refused with a 422 WhatsAppServiceWindowClosed before
anything is created or charged;
send a template instead, which reopens the window once the contact replies.
A window that closes between accept and dispatch still fails
asynchronously, carrying service_window_expired on the message's
last_error. Every free-form send requires from.
Interactive content gives the recipient something to tap. interactive
names its kind in type and carries that kind's own field: reply buttons,
a list menu, a cta_url link button, or cards for a carousel;
location_request_message and request_contact_info are each a single
button asking the recipient for something, so body_text is the whole
message. A tap on a reply button or a list row comes back as an inbound
message carrying interactive_reply. The other kinds answer in their own
shape: a cta_url link opens in the recipient's browser and sends nothing
back, and the two request kinds come back as the thing they asked for, an
inbound location or contact_cards message.
Interactive content is free-form, so the customer service window and the
from requirement above both apply.
Contact cards share up to five contacts in one message. Each card's
name needs formatted_name plus at least one other part, and a
phone_number in E.164 earns that card a button opening a chat with it.
Contact cards are free-form too, so the same window and from rules apply.
A group send addresses a WhatsApp group ID in to and carries no
from: the group sends on its own number, and the response reports the
fan-out.
recipient_count is the group's membership when the send was accepted,
delivered_count and read_count count against it, and status turns
delivered only once every participant has it. WhatsApp delivers neither
interactive content nor an authentication template to a group, and a
Bird-managed template sends from a number no group is scoped to.
Set in_reply_to_message_id to quote a message the contact sees above this
one, the way replying in the WhatsApp client does. Any content quotes, and
the quoted message must be one from this same conversation.
The 202 response is the accepted message, echoing the resolved content; it
is not a delivery confirmation. Follow delivery with
Get a WhatsApp message, the
per-message timeline from
List events for a WhatsApp message,
or whatsapp.* webhook events.
Each of these returns a 422:
- A template slug or language the catalogue does not stock.
- Parameter values that do not match the template's declared placeholders.
- A
fromthis workspace cannot send from. - A recipient that is neither a valid phone number nor a business-scoped user ID.
- Free-form content sent into a closed customer service window
(
WhatsAppServiceWindowClosed). - Interactive content or an authentication template addressed to a group
(
WhatsAppGroupContentNotSupported).
A group to naming no group this workspace holds fails with a 404
WhatsAppGroupNotFound, and one whose group is not active with a 409
WhatsAppGroupNotActive. A send from a workspace with no wallet balance
fails with a 402.
Corps de la requête
toThe message recipient: a phone number in E.164 format (for example +31612345678), the recipient's business-scoped user ID (for example US.13491208655302741918), which addresses a WhatsApp user whose phone number you do not have, or a WhatsApp group ID (for example wag_01krdgeqcxet5s7t44vh8rt9mg), which sends to every participant of that group. A value that is none of these returns a 422 WhatsAppInvalidRecipient. One-time-passcode templates require a phone number and return a 422 WhatsAppRecipientNotSupportedForTemplate when sent to a business-scoped user ID. A group ID naming no group this workspace holds returns a 404 WhatsAppGroupNotFound, and one whose group is not active returns a 409 WhatsAppGroupNotActive. Content a group cannot take is refused ahead of both, so a group ID paired with interactive content returns the 422 below whether or not the group exists.
fromThe business phone number to send from, in E.164 format. Omit it for a Bird-managed template, which selects its own number from its category: setting it there returns a 422 WhatsAppSenderNotAllowed. Every other send, whether free-form content of any kind or a template your workspace authored, requires it, and the number must be one this workspace owns. Omitting it returns a 422 WhatsAppSenderRequired, and naming a number this workspace cannot send from returns a 422 WhatsAppSenderNotFound. Naming a number this workspace owns but that sits on a different WhatsApp Business Account than an authored template returns a 422 WhatsAppSenderWABAMismatch. A number this workspace holds but has not finished connecting returns a 422 WhatsAppSenderNotConnected. Omit it for a group send too: the group sends on its own number, so naming one returns a 422 WhatsAppSenderNotAllowed.
templateThe template to send. A Bird-managed template selects the sender number from the template's category, so from must be omitted. A template is the only content deliverable outside a customer service window. A group send takes a template your workspace authored in any category but authentication: WhatsApp does not deliver an authentication template to a group, which returns a 422 WhatsAppGroupContentNotSupported. A Bird-managed template sends from a Bird-owned number that no group is scoped to, so addressing one to a group returns a 422 WhatsAppInvalidRecipient.
textFree-form text to send instead of a template. Deliverable only inside an open 24-hour customer service window, which the contact opens by messaging or calling you and resets each time they do it again. A send into a closed window is refused with a 422 WhatsAppServiceWindowClosed before anything is created or charged; one whose window closes between accept and dispatch fails asynchronously, with service_window_expired on the message's last_error.
imageA free-form image to send instead of a template. Deliverable only inside an open 24-hour customer service window, which the contact opens by messaging or calling you and resets each time they do it again. A send into a closed window is refused with a 422 WhatsAppServiceWindowClosed before anything is created or charged; one whose window closes between accept and dispatch fails asynchronously, with service_window_expired on the message's last_error.
videoA free-form video to send instead of a template. Deliverable only inside an open 24-hour customer service window, which the contact opens by messaging or calling you and resets each time they do it again. A send into a closed window is refused with a 422 WhatsAppServiceWindowClosed before anything is created or charged; one whose window closes between accept and dispatch fails asynchronously, with service_window_expired on the message's last_error.
audioFree-form audio to send instead of a template. Deliverable only inside an open 24-hour customer service window, which the contact opens by messaging or calling you and resets each time they do it again. A send into a closed window is refused with a 422 WhatsAppServiceWindowClosed before anything is created or charged; one whose window closes between accept and dispatch fails asynchronously, with service_window_expired on the message's last_error.
stickerA free-form sticker to send instead of a template. Deliverable only inside an open 24-hour customer service window, which the contact opens by messaging or calling you and resets each time they do it again. A send into a closed window is refused with a 422 WhatsAppServiceWindowClosed before anything is created or charged; one whose window closes between accept and dispatch fails asynchronously, with service_window_expired on the message's last_error.
documentA free-form document to send instead of a template. Deliverable only inside an open 24-hour customer service window, which the contact opens by messaging or calling you and resets each time they do it again. A send into a closed window is refused with a 422 WhatsAppServiceWindowClosed before anything is created or charged; one whose window closes between accept and dispatch fails asynchronously, with service_window_expired on the message's last_error.
locationA free-form location to send instead of a template. Deliverable only inside an open 24-hour customer service window, which the contact opens by messaging or calling you and resets each time they do it again. A send into a closed window is refused with a 422 WhatsAppServiceWindowClosed before anything is created or charged; one whose window closes between accept and dispatch fails asynchronously, with service_window_expired on the message's last_error.
interactiveFree-form interactive content to send instead of a template: body text plus reply buttons, a menu, a link button, media cards, or a single button asking the recipient to share their location or their phone number. Deliverable only inside an open 24-hour customer service window, which the contact opens by messaging or calling you and resets each time they do it again. A send into a closed window is refused with a 422 WhatsAppServiceWindowClosed before anything is created or charged; one whose window closes between accept and dispatch fails asynchronously, with service_window_expired on the message's last_error. WhatsApp does not deliver interactive content to a group, so a group recipient returns a 422 WhatsAppGroupContentNotSupported.
contact_cardsContact cards to send instead of a template. Up to five: WhatsApp accepts far more, and a message that opens as one name plus a count of the rest is not a card the recipient will read.
in_reply_to_message_idQuote a message the contact will see above this one, the way replying in the WhatsApp client does. Name a message from the same conversation: one this workspace sent to this recipient, or received from them. Any content quotes, template or free-form. The quote is resolved before the send is accepted, so a quote WhatsApp cannot render fails this request rather than the message. An id naming no message this workspace holds, or one older than the 15 days we keep provider ids for, answers 404; a message that never reached WhatsApp, or one from a different conversation than this send's to and from, answers 422. Nothing is charged either way.
tagsStructured {name, value} labels for filtering. Tags become first-class query dimensions: filter the list endpoint by tag name. Maximum 20 tags per send. Use tags for low-cardinality dimensions (category, experiment_variant). For arbitrary structured context you do not need as a filter dimension, use metadata instead.
metadataArbitrary JSON object stored on the message and returned on API reads. Maximum 2 KB serialized. Use metadata for per-send context like internal IDs and foreign keys. For low-cardinality filterable labels, use tags instead.
Contenu de la réponse
idID of the message, assigned when the send is accepted. Pass it as message_id to the get-message and list-events endpoints.
directionWhether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
fromSender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
toRecipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
templateThe template the message was sent from. For authentication templates the filled-in values are not returned.
contact_cardsContact cards on this message: cards the contact shared, either by tapping a button that asked for their number or by sending one from their address book, or the cards this workspace sent.
interactiveInteractive content the message carried. Outbound only: a contact cannot send one. A tap on a reply button or a list row reads back as interactive_reply on the contact's inbound message; a cta_url link sends nothing back, and the two request kinds are answered by an inbound location or contact_cards message.
in_reply_to_message_idThe message this one answers. On an inbound message it is what WhatsApp reports as the reply's target: a tap on a button or a list row, and equally a text or media message the contact sent as a quoted reply. An outbound message echoes the in_reply_to_message_id it was sent with. Absent when the message answers nothing, and absent on an inbound message whose target we cannot match to a message we hold, which is the case for one sent before this workspace started recording them or one already past the 15-day window we keep provider ids for.
interactive_replyWhat the contact tapped, on a message answering an interactive message or a template's quick-reply button. Inbound only.
unsupportedSet when the contact sent content we do not model, naming the WhatsApp content type so the message is not silently empty. Inbound only.
reactionsEmoji reactions standing on this message right now, one per sender. Absent when the message has none. A reaction that was replaced by a different emoji, or taken back, is not listed; the message's reaction log keeps that history. WhatsApp accepts a reaction on a message up to 30 days old, and we keep provider ids for 15, so a reaction placed on a message older than that cannot be matched to it and does not appear here.
statusrecipient_countHow many recipients a group send was addressed to, taken when the send was accepted. It is the group's membership at that moment, not its membership now: someone joining through the invite link while the message is in flight does not receive it and does not change this count.
Absent on a one-to-one message, along with delivered_count and
read_count. A message with one recipient has no fan-out to report, and
its delivery is what status, delivered_at and read_at already say.
Absent for the same reason on a group message sent before Bird recorded
the count, and on a send to a group nobody had joined yet: there is no
denominator to report, and none can be recovered after the fact, since
membership has moved on. to.group_id is what tells a group message from
a one-to-one one in every case, including those two. With no denominator
to resolve against, status is read as stored, the way a one-to-one
message's is: it reaches sent when the message is handed to WhatsApp and
stops there, because delivery is confirmed per participant and a send with
no participants collects no confirmations.
It is also the denominator status is resolved against: on a group
message status reports the furthest point every recipient has
reached, so it turns delivered only once delivered_count equals this
number, and stays sent while some have confirmed and others have not.
failed and rejected are never per recipient: there is one hand-off to
the WhatsApp network and one way for that to be refused. delivered_at
and read_at are the first recipient's, not the last.
delivered_countHow many of the recipient_count recipients WhatsApp has confirmed the
message reached. A recipient who reported only a read counts here too:
WhatsApp skips the delivery receipt when someone is already looking at
the chat, so waiting for one would leave that person uncounted for ever.
Absent on a one-to-one message, which has no fan-out to count, and on a
group message with no recipient_count to count against.
read_countHow many of the recipient_count recipients have opened the message.
Read receipts do not move status, which has no read value; they
surface here and in read_at.
Absent on a one-to-one message, which has no fan-out to count, and on a
group message with no recipient_count to count against.
last_errorFailure detail for a message that did not reach the recipient. Present only when the message failed or was rejected.
created_atWhen the message was accepted for delivery.
sent_atWhen the message was handed to the WhatsApp network. Null until then.
delivered_atWhen delivery was confirmed. Null until then.
read_atWhen the message was read. On an outbound message this is the recipient opening it. On an inbound one it is when Bird acknowledged the message to WhatsApp for the business, which a read receipt sets. Null until then.
costWhat the message cost, split into Bird's charge and any third-party fees passed through. Null on an inbound message, which is never priced, on an outbound message that has not been priced yet, and on one rejected before pricing. The rate depends on the message category and the recipient's country.
tagsStructured {name, value} filter labels applied to this message.
metadataArbitrary JSON metadata stored on the message.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet.