When a contact messages or calls your WhatsApp number, a 24-hour customer service window opens and free-form replies become deliverable. Inbound messages land in the same message list as your sends, on the same API, with the same tags and metadata.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY!,
});
const msg = await bird.whatsapp.send({
to: "+15551234567",
template: {
slug: "bird_delivery_update",
components: [{ type: "body", parameters: [
{ type: "text", name: "ref", text: "#4821" },
{ type: "text", name: "date", text: "Wednesday" },
] }],
},
});
console.log(msg.id, msg.status);
// → "wam_01krdgeqcxet5s7t44vh8rt9mg", "accepted"Inbound is the same resource as outbound.
Two-way is part of the Bird WhatsApp API. An inbound message is a WhatsApp message with direction set to inbound: same list endpoint, same filters, same event timeline. Nothing about receiving is a second integration, and a reply is the send call you already wrote.
An inbound message, in full.
Filter the message list by direction to read what came back. On an inbound message the from is the contact and the to is your number, the reverse of a send. The content sits on the field that matches what they sent, and content WhatsApp models and we do not reads back as unsupported, naming the type rather than coming back empty.
{
"id": "wam_01krdgeqcxet5s7t44vh8rt9mg",
"direction": "inbound",
"from": { "phone_number": "+15551234567", "bsuid": "US.13491208655302741918" },
"to": { "phone_number": "+13124495648" },
"text": { "body": "Where is my order?" },
"status": "delivered",
"created_at": "2026-05-19T15:42:08.114Z"
}
How the 24-hour window works.
WhatsApp does not let a business message whoever it likes whenever it likes. What you may send depends on whether the contact opened a conversation, and Meta calls that open period the customer service window.
- 01
The contact opens it
The window opens when a WhatsApp user messages or calls you, and it runs for 24 hours. Nothing you send opens one on its own terms.
- 02
Every reply from them resets it
A new message or call from the same user resets the clock to a fresh 24 hours, so an active back-and-forth keeps the window open indefinitely.
- 03
Inside it, free-form content is deliverable
Text, images, video, audio, stickers, documents, and locations, with no prior approval, because the customer started the exchange.
- 04
Outside it, only a template
An approved template is the only content that still reaches them, and it reopens the window for free-form replies once they answer.
- 05
Bird does not track the window
A free-form send outside one is accepted and then fails, carrying service_window_expired on the message. The clock started when their message arrived, not when someone picked it up.
Reply from the number they wrote to.
A reply is a send with from and to swapped. Free-form content always names the number it comes from, so the conversation stays on one number of your own and the contact sees a thread rather than a new sender each time.
// Their message opened a 24-hour window, so a free-form reply is deliverable.
// Free-form always names the number it comes from.
await bird.whatsapp.send({
to: inbound.from.phone_number,
from: inbound.to.phone_number,
text: { body: "It shipped this morning: https://example.com/track/A1B2C3" },
});
// Outside the window this same call is accepted and then fails, with
// `service_window_expired` on the message. Send a template instead.
Inbound needs a number of your own.
Bird's managed sender numbers are shared across workspaces and carry managed templates only, so a message sent to one belongs to no single workspace. Connecting your own number is what makes inbound yours, and it is the same step that unlocks free-form content and templates you authored.
Three ways to watch what comes in.
Poll the message list filtered by direction, read one message's timeline from its events endpoint, or open the dashboard's inbound metrics for volume by day, hour, and number. Outbound delivery, on the other hand, reports itself on webhooks you subscribe once.
Go deeper in the docs.
Read the customer service window for when free-form content is deliverable, WhatsApp events for the timeline and the message log, and phone number setup for connecting the number inbound arrives on.
Event questions, answered.
The lifecycle, read receipts, failures, and how to consume them.
Quali eventi emette un messaggio WhatsApp?
Una conferma di lettura equivale a una consegna?
Qual è la differenza tra failed e rejected?
Come posso consumare gli eventi?
The rest of the WhatsApp platform
One API, one set of keys. Explore the other capabilities.
Answer the question you were asked.
Two-way is one capability of the Bird WhatsApp API: templates, sending, numbers, and analytics ship with it, on infrastructure we have run for a decade.