Send WhatsApp template with media

Send an approved WhatsApp Business template whose header is an image. The request has the same shape as Send WhatsApp text template, with one more field on each recipient: the header image, as header_image_url or header_media_id.

The image. Each recipient carries exactly one of these two fields, and each recipient can have a different image (JPEG or PNG):

  • header_image_url: a public https URL. WhatsApp downloads the file when the message is sent, so it must be reachable without a login.
  • header_media_id: an image you uploaded. Call WhatsApp upload file first and pass the media_id it returns, for example "header_media_id": "01d1e10f-2b3c-4d5e-6f70-3707906010e2". Use it when the image has no public URL. The media_id is valid for 20 minutes; a send that uses it before the upload has been processed, or after it expires, fails.

A recipient with both fields, or with neither, is rejected with HTTP 422.

Supply the template's text variables in template_variables by section (body, buttons), as on the other template endpoints.

sender is the WhatsApp Business number the template is sent from; it defaults to the channel's sender.

Template variables. template_variables has up to three sections. Send only the ones your template has placeholders in:

  • header: values for a text header, { "1": "4821" }.
  • body: values for the body text, { "1": "John", "2": "4821" }. A named placeholder such as {{first_name}} is keyed by its name: { "first_name": "John" }.
  • buttons: a list with one item per button, in the template's button order: [ { "1": "track-1001" } ].

Response. HTTP 200 with a task_id and one entry per message. status is false when any message failed: failed entries come first and carry error (hex code) and details; accepted entries carry message_uuid (and conversation_uuid on two-way channels). Match entries by internal_id. Final delivery status is sent asynchronously to your configured webhook.

Authentication: channel token in the Authorization header (see Authentication in the API Overview).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

WhatsApp Business sender phone number. Defaults to the channel's sender.

The approved WhatsApp template, by its eventKey on the channel. Its header must be an image. Required unless every recipient sets event.

recipients
array of objects
required
length ≤ 250

The recipients, up to 250 per request.

Recipients*
Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json