Send images, videos, and documents on WhatsApp

A WhatsApp template can carry a media header: one image, video, or document displayed above the message body. Notify sends it through the document field on the send endpoint. The template is fixed, the media is per message. Register the template once, then pass a different URL on every send: this customer’s invoice, this passenger’s boarding pass, this week’s product photo.

Media headers require a WhatsApp Business Account connected to Prelude. See the WhatsApp BSP guide to connect yours.

How it works

The WhatsApp template on your WABA needs a header component with the format IMAGE, VIDEO, or DOCUMENT, and its name must match your Prelude template ID. Your Customer Success Manager sets this up with you.

Meta approves the template

Prelude reads the header format from the approved template and stores it on the template. Until that sync lands, a send with document returns document_not_supported.

Send a media URL on every message

Pass document.url with each send. Prelude checks the URL against the registered header format and sends it as the matching WhatsApp parameter, so an image renders as an image and a video renders as a playable clip.

Supported formats

The header format registered with Meta decides what you can send. You don’t declare the media type in the request. Prelude resolves it from the template.

Header format	Extensions Prelude accepts	`filename`	Meta size limit
`IMAGE`	`.png`, `.jpg`, `.jpeg`, `.webp`	Ignored	5 MB
`VIDEO`	`.mp4`, `.3gp`	Ignored	16 MB
`DOCUMENT`	PDF and Office formats, no extension check	Required	100 MB

Size limits are Meta’s, not ours. See Meta’s supported media types for the full list.

Sending a message with media

{
  "template_id": "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  "to": "+33612345678",
  "preferred_channel": "whatsapp",
  "variables": { "order_id": "12345" },
  "document": {
    "url": "https://cdn.example.com/invoices/12345.pdf",
    "filename": "invoice-12345.pdf"
  }
}

string

required

HTTPS URL of the media file. WhatsApp downloads it at send time, so it has to be publicly reachable.

string

The filename WhatsApp displays to the recipient. Required for DOCUMENT headers, ignored for IMAGE and VIDEO.

SDK examples

const response = await client.notify.send({
  template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  to: "+33612345678",
  preferred_channel: "whatsapp",
  variables: { order_id: "12345" },
  document: {
    url: "https://cdn.example.com/invoices/12345.pdf",
    filename: "invoice-12345.pdf",
  },
});

response = client.notify.send(
    template_id="template_01k8ap1btqf5r9fq2c8ax5fhc9",
    to="+33612345678",
    preferred_channel="whatsapp",
    variables={"order_id": "12345"},
    document={
        "url": "https://cdn.example.com/invoices/12345.pdf",
        "filename": "invoice-12345.pdf",
    },
)

response, err := client.Notify.Send(context.TODO(), prelude.NotifySendParams{
    TemplateID:       prelude.F("template_01k8ap1btqf5r9fq2c8ax5fhc9"),
    To:               prelude.F("+33612345678"),
    PreferredChannel: prelude.F(prelude.NotifySendParamsPreferredChannelWhatsapp),
    Variables:        prelude.F(map[string]string{"order_id": "12345"}),
    Document: prelude.F(prelude.NotifySendParamsDocument{
        URL:      prelude.F("https://cdn.example.com/invoices/12345.pdf"),
        Filename: prelude.F("invoice-12345.pdf"),
    }),
})

URL requirements

The URL has to be fetchable by WhatsApp, without credentials, at the moment you send. Files behind an authenticated endpoint or on a private network fail at delivery, not at request time. Prelude reads the file extension from the URL path and ignores the query string. A signed URL like https://cdn.example.com/invoices/12345.pdf?token=abc123 passes. A URL with no extension in the path, like https://cdn.example.com/files?id=12345, is rejected with invalid_document_media_type for image and video templates.

The extension check catches obvious mismatches early, such as an .mp4 on a template with an image header. WhatsApp enforces the final list of accepted file types and sizes.

Media becomes mandatory

Once a template has a media header, every send to that template needs a document. A send without one returns document_required. There is no text-only mode for a media template. The reverse also holds: sending document to a template with no media header, or a text header, returns document_not_supported.

Bulk sends

Send bulk messages takes a single document shared by every recipient in the batch, and validates it per recipient. Use it for one campaign asset going out to a list. For per-recipient media, such as a personal invoice, send the messages individually.

Channel fallback

The attachment only travels over WhatsApp. If Prelude falls back to SMS or RCS, the recipient gets the text of the message with no media. Set preferred_channel to whatsapp when the media carries the point of the message, and keep the body understandable on its own for the cases where it doesn’t reach WhatsApp.

Error handling

Error Code	Description	Action
`document_required`	The template has a media header and the request has no `document`	Add a `document` object with a `url`
`document_not_supported`	The template has no media header	Remove the `document` object, or check that Meta has approved the media template
`invalid_document_url`	The URL is not a valid HTTP or HTTPS URL	Send an absolute HTTPS URL with a hostname
`invalid_document_media_type`	The extension in the URL path doesn’t match the template’s header format	Send a file type the header accepts
`missing_document_filename`	The template has a `DOCUMENT` header and `filename` is empty	Add the filename to display to the recipient

For a complete list of errors, see the Error documentation.

Limitations

Media headers apply to outbound template messages only. Replies sent with Reply to an inbound message are text.
Inbound WhatsApp media is not forwarded. See 2-Way Messaging with WhatsApp.
One media item per message, in the header. WhatsApp templates don’t support media in the body.
Prelude fills the header and body of a template. Dynamic button parameters, carousels, and location headers are not supported.

Send a message - The full request reference
WhatsApp BSP - Connect your WhatsApp Business Account
2-Way Messaging with WhatsApp - Receive inbound messages and reply

Documentation

API Reference

Send images, videos, and documents on WhatsApp

How it works

Supported formats

Sending a message with media

SDK examples

URL requirements

Media becomes mandatory

Bulk sends

Channel fallback

Error handling

Limitations

​How it works

​Supported formats

​Sending a message with media

​SDK examples

​URL requirements

​Media becomes mandatory

​Bulk sends

​Channel fallback

​Error handling

​Limitations

​Related documentation

How it works

Supported formats

Sending a message with media

SDK examples

URL requirements

Media becomes mandatory

Bulk sends

Channel fallback

Error handling

Limitations

Related documentation