Send WhatsApp marketing template with media

Send an approved WhatsApp marketing template whose header is an image, through Meta's Marketing Messages API. The request has the same shape as Send WhatsApp marketing 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.

Requirements. The sender must be a WhatsApp Business number with marketing enabled in TextPeak, and the template must be a saved template.

Errors. HTTP 403 with 0x35 (marketing_not_enabled) rejects the whole request when no sender of the channel has marketing enabled. Otherwise each recipient is checked on its own, and a failed one comes back as an entry in the HTTP 200 response.

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 with marketing enabled. Defaults to the channel's sender.

The approved marketing 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