> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Images, Videos, and Files via the WhatsApp API

> Send images, audio, video, documents over WhatsApp using POST /v1/messages/send with media + mediaType. Supports public URLs and base64 (per provider).

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`

<Note>
  Sending media requires an active paid subscription. Without one the API returns `402` with code `SUBSCRIPTION_REQUIRED_FOR_MEDIA`.
</Note>

## 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`.

<CodeGroup>
  ```bash Image with caption theme={null}
  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"
    }'
  ```

  ```bash Voice note (audio) theme={null}
  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"
    }'
  ```

  ```bash Base64 image theme={null}
  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"
    }'
  ```
</CodeGroup>

## `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

| Provider       | Public URL | Base64 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:

```json theme={null}
{
  "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).

## Related

* [Send Messages](/guides/send-messages)
* [Templates](/concepts/templates)