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 recipient: a phone number in E.164 format (for example +14155550100), a business-scoped user ID (for example US.13491208655302741918) for a WhatsApp user whose number you do not have, or a WhatsApp group ID (for example wag_01krdgeqcxet5s7t44vh8rt9mg). One-time-passcode templates need a phone number. Bird tracks the customer service window per identity and business number, so reply to the identity a contact's message came from, from the number it reached.
fromThe business phone number to send from, in E.164 format: a connected number this workspace owns, on the same WhatsApp Business Account as an authored template. Omit it for a Bird-managed template or a group send, which use their own number; every other send requires it.
templateThe template to send, the only content deliverable outside the customer service window. A group takes only templates your workspace authored, outside the authentication category.
textFree-form text. Deliverable only inside an open customer service window.
imageA free-form image. Deliverable only inside an open customer service window.
videoA free-form video. Deliverable only inside an open customer service window.
audioFree-form audio. Deliverable only inside an open customer service window.
stickerA free-form sticker. Deliverable only inside an open customer service window.
documentA free-form document. Deliverable only inside an open customer service window.
locationA free-form location. Deliverable only inside an open customer service window.
interactiveFree-form interactive content: reply buttons, a list menu, a link button, media cards, or a request for the recipient's location or contact details. Deliverable only inside an open customer service window, and never to a group.
contact_cardsUp to five contact cards, each name carrying formatted_name plus at least one other part. Deliverable only inside an open customer service window.
in_reply_to_message_idAn earlier message to quote above this one: one from the same conversation, between this to and from, in the last 15 days.
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 a message that did not come from a Bird send carries content we do not model, naming the WhatsApp content type so the message is not silently empty. Never on a message sent through Bird.
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.
statusoriginWhere the message came from when it did not come through Bird live. Absent when your workspace sent the message through Bird, or the contact sent it to Bird.
recipient_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.