Skip to main content
Send images, videos, documents, and audio over WhatsApp with the same endpoint used for everything else: POST /v1/messages/send. There is no separate media endpoint — media is one of the three mutually exclusive send modes:
  1. Template send — templateId (+ optional media override)
  2. Free-form text send — text
  3. Direct media send — media + mediaType, no templateId and no text

​
Direct media send

Provide media + mediaType without templateId or text. In this mode buttons, header, footer, and variables are not allowed. An optional caption is supported for image, video, and document — but not for audio, voice, or sticker (see Audio and voice notes).

​
media and mediaType fields

  • media — a public http(s) URL or a base64 data URI (data:<mime>;base64,...). Base64 is capped by decoded size: 50 MiB when mediaType is document, 16 MiB for every other type (and when mediaType is omitted); above that the request is refused with 400 Validation error. Send larger files by URL — on Meta Cloud API numbers a URL is held to Meta’s own ceilings instead (document 100 MB, video and audio 16 MB, image 5 MB).
  • mediaType — image, video, document, audio, voice, or sticker. Set it explicitly when the URL extension is not obvious (e.g. a PDF whose URL does not end in .pdf).

​
Base64 vs. URL per provider

​
Audio and voice notes

How audio and voice arrive depends on the number: To send a voice note on any number, use voice. Use audio only when you want an audio file on an official number. On official numbers, PLAYED (the recipient listened to it) is reported only for voice notes — an audio send there does not reach PLAYED. The audio is converted before it is sent: to AAC in MP4 (audio/mp4) on official numbers, and to Ogg/Opus on unofficial numbers. Captions are not supported for either type. audio with a caption returns 400. With voice, a caption is not rejected, but it is dropped on unofficial numbers and its rendering on official numbers is not guaranteed — don’t send one. Just before delivery the contact sees a presence indicator: “recording audio…” on unofficial numbers, and “typing…” on official numbers. The Cloud API has no recording indicator, and it shows typing only when the conversation has a recent message from the contact to attach it to.

​
Stickers

mediaType: "sticker" sends a WhatsApp sticker. It is a direct media send only — never with templateId, and it takes no caption and no mediaFilename (both return 400), because a sticker carries no text. The file must be image/webp and exactly 512×512 pixels: 512×512 is a hard requirement, not a recommendation — any other size is rejected, including a near-square one like 361×363. Any other format or an oversized file is rejected by WhatsApp, not by this API — the send is accepted with 202 and the failure arrives later in the message.failed webhook. Convert before sending rather than relying on the API to catch it.

​
Media with templates

Add media (+ mediaType) to a template send to attach or override media — it takes precedence over any media URL embedded in the template:
Note that media/mediaType cannot be combined with a free-form text send. The API does accept buttons alongside mediaType: "video" or "document", though Meta may reject buttons on some video/PDF messages depending on the recipient’s client.