POST/api/public/v1/messages

Send media template

An approved template with an image, video or document header.

Identical to a text template apart from one field: the media URL for the header. Which field you use is fixed by the format the template was approved with — you cannot send a video to a template approved with an image header, and the wrong field is rejected with a message naming the right one.

Header formats

Approved as	Send in	Notes
IMAGE	headerImage	JPEG or PNG. Shown above the body text.
VIDEO	headerVideo	MP4 or 3GPP, playable inline in the chat.
DOCUMENT	headerDocument	Any file WhatsApp accepts, usually PDF. Pair with `headerFilename` to control the name shown.

Body parameters

Field	Type	Required	Description
to	string	Required	Recipient number in international format, digits only — `919876543210`, not `+91 98765 43210`.
type	string	Required	Must be `template`.
template.name	string	Required	Exact approved template name, from Settings → WhatsApp templates.
template.language	string	Required	The locale the template was approved in, e.g. `en`, `en_US`, `hi`. Must match exactly — WhatsApp looks up a template by name and language, so the wrong code fails even when the name is right.
template.headerImage	string	optional	Public `https://` URL — required when the header was approved as `IMAGE`.
template.headerVideo	string	optional	Public `https://` URL — required for a `VIDEO` header.
template.headerDocument	string	optional	Public `https://` URL — required for a `DOCUMENT` header.
template.headerFilename	string	optional	Filename shown for a document header. Defaults to the URL's last path segment.
template.bodyParams	string[]	optional	Values for the body's `{{1}}`, `{{2}}`... placeholders, in order.
template.buttonParams	object[]	optional	Values for buttons that carry one — see Buttons below.

Image header

cURL — image header

bash

curl -X POST 'https://api.bigradar.io/api/public/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "919876543210",
    "type": "template",
    "template": {
      "name": "order_shipped",
      "language": "en",
      "headerImage": "https://cdn.example.com/banner.jpg",
      "bodyParams": ["Mohit", "#4521"]
    }
  }'

Video header

Only the field name changes. Buttons, body values and everything else behave exactly as they do elsewhere.

cURL — video header with a dynamic URL button

bash

curl -X POST 'https://api.bigradar.io/api/public/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "919876543210",
    "type": "template",
    "template": {
      "name": "product_demo",
      "language": "en",
      "headerVideo": "https://cdn.example.com/clip.mp4",
      "bodyParams": ["Mohit"],
      "buttonParams": [
        { "index": 0, "text": "4521" }
      ]
    }
  }'

Document header

Documents are the one format with a second field. headerFilename is what the customer sees in the chat bubble — without it, WhatsApp falls back to the last segment of the URL, which is often a hash.

cURL — document header

bash

curl -X POST 'https://api.bigradar.io/api/public/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "919876543210",
    "type": "template",
    "template": {
      "name": "invoice_ready",
      "language": "en",
      "headerDocument": "https://cdn.example.com/inv-4521.pdf",
      "headerFilename": "Invoice-4521.pdf",
      "bodyParams": ["Mohit", "#4521"]
    }
  }'

Response · 200

200 OK

json

{
  "success": true,
  "message": "Template message sent successfully",
  "data": {
    "message_id": "wamid.HBgM...",
    "conversation_id": "a1b2c3d4-...",
    "to": "919876543210",
    "status": "queued",
    "timestamp": "2026-06-25T12:30:45Z"
  }
}

Errors

Code	Status	Means
missing_header_media	400	No URL for the format this template was approved with. If you sent a different media field, the hint names it.
invalid_media_url	400	Not a valid URL, or not https. WhatsApp refuses plain http.
unexpected_header_param	400	You sent header fields for a template that has no header.
template_not_found	404	No template with that name on this workspace. Check spelling and case.
template_not_approved	409	The template exists but Meta has not approved it yet.
missing_template_params	400	Fewer values than the template has placeholders. The message names the count.
whatsapp_not_connected	409	No WhatsApp Business account is connected. Connect one in the dashboard.