Templates
Meta approves the words. You fill in the blanks.
A WhatsApp template is a message structure Meta reviewed in advance: a slug, a category, one copy per language, and placeholders you fill at send time. Bird ships a managed catalog you can send on your first day, and your own templates once your business account is connected.
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"A template is the only way in.
Templates are how the Bird WhatsApp API starts a conversation. Outside an open customer service window, an approved template is the only content WhatsApp will deliver, so the slug you name on the send is the gate. Name it, pick a language, pass the placeholder values, and the send is one call.
const 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);What a template carries.
One identity holding a copy of the message per language. Meta reviews, prices, and pauses each language on its own, so the template's own status is an aggregate and the detail sits one level down.
- 01
An immutable slug
The handle a send names the template by. It never changes, and handles beginning with bird_ are reserved for Bird's built-in catalog.
- 02
One of three categories
Authentication for one-time passcodes, utility for transaction-triggered updates, marketing for promotional content. The category is fixed once the template exists, and it decides both the sender number and the price.
- 03
A copy per language
One slug, many languages, each keyed by its BCP-47 tag. Meta applies its own category per language and can move one, and that is what the message is priced at.
- 04
Placeholders you fill at send time
Values ride in on a components array. Parameters can be named, matched by key, or positional, matched by index. Named parameters survive a change to the template's variable order.
- 05
A version history
A draft you edit, a pending version awaiting Meta's verdicts, and the live version Meta is serving. A version goes live as a unit the moment any of its languages is approved.
Approval is per language, not per template.
A template reading active can still hold a rejected or paused language: the aggregate says something is sendable, and the languages map says which. available_languages is the set a send can resolve right now, and it shrinks for reasons you did not cause when Meta pauses or limits a language.
{
"slug": "order_update",
"name": "Order update",
"category": "utility",
"status": "active",
"default_language": "en",
"on_missing_language": "fail",
"available_languages": ["en", "es"],
"languages": {
"en": { "status": "approved", "editable_at": "2026-07-27T16:40:00Z" },
"es": { "status": "approved", "editable_at": null },
"pt": { "status": "paused" },
"de": {
"status": "rejected",
"rejection": {
"category": "invalid_format",
"reason": "Parameters are adjacent.",
"recommendation": "Add text between the two parameters."
}
}
},
"live_version_id": "wtv_01krdgeqcxet5s7t44vh8rt9mg",
"pending_version_id": null
}
Name the language, or let the template resolve one.
A send can pick a language explicitly or leave it to the template. On WhatsApp on_missing_language defaults to fail rather than falling back, because every language is separately approved and separately priced: a silent fallback would send content the recipient did not expect at a rate you did not choose.
await bird.whatsapp.send({
to: "+15551234567",
template: {
slug: "bird_delivery_update",
language: "es",
components: [
{
type: "body",
parameters: [
{ type: "text", name: "ref", text: "BRD-49217" },
{ type: "text", name: "date", text: "10 Jul 2026" },
],
},
],
},
});
Bird's catalog first, your own next.
Built-in templates ship pre-approved on a WhatsApp Business Account Bird shares across workspaces, so a first send needs no review and no number of your own. Authoring your own is a dashboard step once your business account is connected, and a template you authored has to sit on the same business account as the sender you name.
Editing an approved language has a budget.
Meta allows one edit per approved language per day, and caps it at ten edits per rolling 30 days. The language reports editable_at when today's edit is spent, so a build can wait rather than guess. A language nobody sends is reclaimed after twelve months and stays recoverable for another 28 days.
Template questions, answered.
Categories, approval, languages, and placeholders.
What is a WhatsApp template?
Who approves templates?
What are the template categories?
How do I fill in template variables?
Can I create my own templates?
The rest of the WhatsApp platform
One API, one set of keys. Explore the other capabilities.
Send an approved template in five minutes.
Bird's managed catalog is already approved and already stocked in dozens of languages, so your first WhatsApp message goes out before you author anything of your own.