Sending messages
One endpoint sends every WhatsApp message type. Messages are queued, paced to WhatsApp's limits and tracked through webhooks.
Request body
tostringoptionalRecipient phone with country code, with or without+(numbers without one are read in your organization's country). One ofto,recipientorcontact_idis required. A contact is created automatically for new numbers.recipientstringoptionalWhatsApp business-scoped user id (BSUID), for users who hide their number.contact_iduuidoptionalAn Engage contact id.phone_number_iduuidoptionalEngage id of the sending number (fromGET /v1/numbers). Defaults to your default number, otherwise the first one connected.typeenumrequiredtext·template·image·video·audio·document·sticker·location·contacts·interactive·reaction{type}objectrequiredAn object named after the type with its content, e.g.text,image.reply_touuidoptionalEngage message id to quote as a reply.client_refstringoptionalYour own reference, up to 128 characters. Returned byGET /v1/messages/{id}.scheduled_fordatetimeoptionalSend later: between 5 seconds and 60 days from now. The response status is then scheduled.ttl_secondsintegeroptionalGive up if the message can't be delivered within this many seconds (30 – 2,592,000).
{
"id": "0f9b1c7e-5a43-4c1d-9d0e-6f2a8b3c4d51",
"status": "queued",
"conversation_id": "a81c2e4f-…",
"contact_id": "b1e7c3d9-…"
}template requires an open 24-hour window — i.e. the customer messaged you in the last 24 hours.Why a send is refused
Besides field errors, these return 422 validation_failed with the reason in message:
- The contact is blocked.
- A
MARKETINGtemplate to a contact who opted out. - An
AUTHENTICATIONtemplate to a contact known only by WhatsApp username (no phone). - The template isn't
APPROVEDfor the sending number's account, or no number is connected yet. - A reply or reaction to a message WhatsApp hasn't acknowledged yet.
The message object
GET /v1/messages/{id} returns the message with its current status and timestamps:
{
"id": "0f9b1c7e-5a43-4c1d-9d0e-6f2a8b3c4d51",
"conversation_id": "a81c2e4f-…",
"phone_number_id": "1c2d3e4f-…",
"contact_id": "b1e7c3d9-…",
"direction": "out",
"type": "template",
"status": "delivered",
"content": {
"type": "template",
"template": {
"name": "order_shipped",
"language": {
"code": "en"
},
"components": [
"…"
]
},
"category": "UTILITY"
},
"wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSM0Q…",
"error": null,
"sent_by": null,
"campaign_id": null,
"client_ref": "order-48213",
"reply_to_wamid": null,
"pricing": {
"category": "utility",
"billable": true,
"type": "regular"
},
"scheduled_for": null,
"created_at": "2026-11-11T10:42:00Z",
"sent_at": "2026-11-11T10:42:01Z",
"delivered_at": "2026-11-11T10:42:07Z",
"read_at": null,
"failed_at": null
}Text
Up to 4,096 characters. WhatsApp formatting is supported: *bold*, _italic_, ~strike~, ```mono```. Set preview_url to render a link preview.
{
"to": "14155550101",
"type": "text",
"text": {
"body": "Hi Jane! Your order *#48213* has shipped 🚚 Track it: https://example.com/t/48213",
"preview_url": true
}
}Template
Templates can be sent at any time. Reference them by name (plus language when the template exists in several) or by Engage template_id. The template must be APPROVED on the sending number's WhatsApp account. Fill its parameters with the variables map:
{
"to": "14155550101",
"type": "template",
"template": {
"name": "order_shipped",
"language": "en",
"variables": {
"1": "Jane",
"2": "#48213",
"header.link": "https://cdn.example.com/orders/48213.jpg",
"button.0": "48213"
}
}
}Prefer full control? Pass Meta's components array instead of variables and Engage forwards it unchanged.
Media
Send image, video, audio, document or sticker with either an Engage media_id (from POST /v1/media) or a public HTTPS link. Captions are up to 1,024 characters; audio and stickers can't have one.
{
"to": "14155550101",
"type": "image",
"image": {
"link": "https://cdn.example.com/sale.jpg",
"caption": "Festive sale — 30% off today only"
}
}See Media for uploading files.
Location
{
"to": "14155550101",
"type": "location",
"location": {
"latitude": 12.9716,
"longitude": 77.5946,
"name": "Example Store",
"address": "1 Example Street, Bengaluru"
}
}Contacts
{
"to": "14155550101",
"type": "contacts",
"contacts": [
{
"name": {
"formatted_name": "Example Support",
"first_name": "Example Store"
},
"phones": [
{
"phone": "+14155550100",
"type": "WORK"
}
],
"emails": [
{
"email": "support@example.com",
"type": "WORK"
}
]
}
]
}The contacts array (1–20 cards) follows Meta's contact object schema.
Interactive
Pass Meta's interactive object as-is. Supported types: button (1–3 reply buttons, titles up to 20 characters), list (up to 10 sections and 1–10 rows), cta_url, flow, product, product_list, catalog_message, carousel, location_request_message, address_message and call_permission_request. Replies arrive as message.received webhooks with the chosen button or row id.
{
"to": "14155550101",
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "Confirm your delivery slot for Saturday, 9–11 AM?"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "slot_confirm",
"title": "Confirm"
}
},
{
"type": "reply",
"reply": {
"id": "slot_change",
"title": "Change slot"
}
}
]
}
}
}Reaction
React to a message you received. Send an empty emoji to remove the reaction.
{
"to": "14155550101",
"type": "reaction",
"reaction": {
"message_id": "8b2e3f1a-…",
"emoji": "👍"
}
}Replying to a message
Add reply_to with the Engage id of an inbound message to show it as a quoted reply.
{
"to": "14155550101",
"type": "text",
"reply_to": "8b2e3f1a-…",
"text": {
"body": "Yes — the blue variant is back in stock!"
}
}Bulk send
Send up to 1,000 messages per request. Your monthly message allowance is checked once for the whole batch (one 402 if it doesn't fit); after that each item is validated on its own. The response is 202 with one result per item, in order, each carrying its index.
{
"messages": [
{ "to": "14155550101", "type": "template", "template": { "name": "order_shipped", "language": "en", "variables": { "1": "Jane", "2": "#48213" } } },
{ "to": "+91000", "type": "text", "text": { "body": "Hi" } }
]
}
// → 202
{
"data": [
{ "index": 0, "id": "0f9b1c7e-…", "status": "queued" },
{ "index": 1, "error": { "code": "validation_failed", "message": "Enter the phone number with country code, e.g. +91 XXXXX XXXXX.", "details": { "fields": { "to": "…" } } } }
]
}For large audiences, prefer campaigns — they handle audience expansion, opt-outs and reporting for you.