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
Sending media requires an active paid subscription. Without one the API returns 402 with code SUBSCRIPTION_REQUIRED_FOR_MEDIA.

​
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. 
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"
  }'

​
media and mediaType fields

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

ProviderPublic URLBase64 data URI
Meta Cloud API✓✓
Evolution v2✓✓
Evolution GO✓✗ — URL only

​
Audio is a voice note (PTT)

When mediaType is audio, the file is delivered as a WhatsApp voice note (PTT) on all providers. On Evolution v2 and Evolution GO 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.

​
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, and buttons are incompatible with mediaType: "video" or "document" (WhatsApp does not support buttons on video/PDF messages).