Skip to content

Sending messages

One endpoint sends every WhatsApp message type. Messages are queued, paced to WhatsApp's limits and tracked through webhooks.

Request body

Body parameters
  • tostringoptional
    Recipient phone with country code, with or without + (numbers without one are read in your organization's country). One of to, recipient or contact_id is required. A contact is created automatically for new numbers.
  • recipientstringoptional
    WhatsApp business-scoped user id (BSUID), for users who hide their number.
  • contact_iduuidoptional
    An Engage contact id.
  • phone_number_iduuidoptional
    Engage id of the sending number (from GET /v1/numbers). Defaults to your default number, otherwise the first one connected.
  • typeenumrequired
    text · template · image · video · audio · document · sticker · location · contacts · interactive · reaction
  • {type}objectrequired
    An object named after the type with its content, e.g. text, image.
  • reply_touuidoptional
    Engage message id to quote as a reply.
  • client_refstringoptional
    Your own reference, up to 128 characters. Returned by GET /v1/messages/{id}.
  • scheduled_fordatetimeoptional
    Send later: between 5 seconds and 60 days from now. The response status is then scheduled.
  • ttl_secondsintegeroptional
    Give up if the message can't be delivered within this many seconds (30 – 2,592,000).
Response · 202 Accepted
{
  "id": "0f9b1c7e-5a43-4c1d-9d0e-6f2a8b3c4d51",
  "status": "queued",
  "conversation_id": "a81c2e4f-…",
  "contact_id": "b1e7c3d9-…"
}
Customer service window
Every type except 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 MARKETING template to a contact who opted out.
  • An AUTHENTICATION template to a contact known only by WhatsApp username (no phone).
  • The template isn't APPROVED for 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:

JSON
{
  "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
}
StatusMeaning
scheduledWaiting for scheduled_for
queuedAccepted, waiting to be sent
sendingBeing handed to WhatsApp
retryingA temporary error; Engage will try again
sentAccepted by WhatsApp
deliveredDelivered to the phone
readRead by the customer
playedA voice note was played
failedNot delivered — see error ({ code, title, detail }, Meta's error code)
cancelledA scheduled message was cancelled
receivedInbound messages from the customer

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:

KeyFills
body.1, body.first_nameBody parameters by position or name. A bare 1 or first_name means the same.
header.1The variable in a TEXT header
header.media_id / header.linkThe file for an IMAGE, VIDEO or DOCUMENT header — an Engage media id or a public HTTPS URL. header.media accepts either. Add header.filename for documents.
header.latitudeLOCATION headers, with header.longitude, header.name, header.address
button.0The button at that index: the dynamic part of a URL button, the code of a copy-code button (required), the OTP for an authentication button (defaults to body.1), a quick-reply payload or a flow token
Template with an image header
{
  "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.

TypeFormatsMax size
imageJPEG, PNG5 MB
videoMP4, 3GPP (H.264 + AAC)16 MB
audioAAC, MP3, M4A, AMR, OGG (Opus)16 MB
documentPDF, DOC(X), XLS(X), PPT(X), TXT100 MB
stickerWebP500 KB
{
  "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

JSON
{
  "to": "14155550101",
  "type": "location",
  "location": {
    "latitude": 12.9716,
    "longitude": 77.5946,
    "name": "Example Store",
    "address": "1 Example Street, Bengaluru"
  }
}

Contacts

JSON
{
  "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.

JSON
{
  "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.

JSON
{
  "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.

POST /v1/messages/bulk
{
  "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.

Something unclear or missing on this page? Tell us at contact@swastik.ai