Send Images, Videos, and Files via the WhatsApp API

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:

Template send — templateId (+ optional media override)
Free-form text send — text
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 allowed for image, video, and document — but not for audio, voice, or sticker.

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationNumber": "+5511999999999",
    "media": "https://cdn.example.com/photo.png",
    "mediaType": "image",
    "caption": "Check this out"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationNumber": "+5511999999999",
    "media": "https://cdn.example.com/voice.ogg",
    "mediaType": "audio"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationNumber": "+5511999999999",
    "media": "data:image/png;base64,iVBORw0...",
    "mediaType": "image"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationNumber": "+5511999999999",
    "media": "https://cdn.example.com/sticker.webp",
    "mediaType": "sticker"
  }'

`media` and `mediaType` fields

media — a public http(s) URL or a base64 data URI (data:<mime>;base64,...).
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

Provider	Public URL	Base64 data URI
Meta Cloud API	✓	✓
Unofficial (Pilot Status web)	✓	✗ — use a URL

Audio is a voice note (PTT)

When mediaType is audio, the file is delivered as a WhatsApp voice note (PTT) on all providers. On unofficial (Pilot Status web) numbers the recipient briefly sees a “recording audio” presence indicator before delivery; Meta Cloud API has no outbound presence API, so no indicator appears on Meta sends.

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:

Sticker	Dimensions	Max size
Static `.webp`	512×512	100 KB
Animated `.webp`	512×512	500 KB

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:

{
  "templateId": "promo-template",
  "destinationNumber": "+5511999999999",
  "variables": { "name": "John" },
  "media": "https://example.com/promo.png",
  "mediaType": "image"
}

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.

Get Started

Core Concepts

Guides

Integrations

Dashboard

Trust & Data

Plans & Support

Changelog

Send Images, Videos, and Files via the WhatsApp API

Direct media send

`media` and `mediaType` fields

Base64 vs. URL per provider

Audio is a voice note (PTT)

Stickers

Media with templates

​Direct media send

​media and mediaType fields

​Base64 vs. URL per provider

​Audio is a voice note (PTT)

​Stickers

​Media with templates

​Related

Direct media send

`media` and `mediaType` fields

Base64 vs. URL per provider

Audio is a voice note (PTT)

Stickers

Media with templates

Related