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

# Envie Imagens, Vídeos e Arquivos pela API do WhatsApp

> Envie imagens, áudio, vídeo e documentos pelo WhatsApp usando POST /v1/messages/send com media + mediaType. Suporta URLs públicas e base64 (conforme o provedor).

Envie imagens, vídeos, documentos e áudio pelo WhatsApp com o mesmo endpoint usado para todo o resto: `POST /v1/messages/send`. Não existe um endpoint de mídia separado — a mídia é um dos três modos de envio mutuamente exclusivos:

1. **Envio de template** — `templateId` (+ `media` opcional para sobrescrever)
2. **Envio de texto livre** — `text`
3. **Envio direto de mídia** — `media` + `mediaType`, sem `templateId` e sem `text`

## Envio direto de mídia

Forneça `media` + `mediaType` sem `templateId` ou `text`. Nesse modo, `buttons`, `header`, `footer` e `variables` **não são permitidos**. Um `caption` opcional é permitido para `image`, `video` e `document` — mas **não** para `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>

## Campos `media` e `mediaType`

* `media` — uma **URL http(s) pública** ou um **data URI base64** (`data:<mime>;base64,...`).
* `mediaType` — `image`, `video`, `document` ou `audio`. Defina-o explicitamente quando a extensão da URL não for óbvia (ex.: um PDF cuja URL não termina em `.pdf`).

### Base64 vs. URL por provedor

| Provedor                       | URL pública | Data URI base64     |
| ------------------------------ | ----------- | ------------------- |
| Meta Cloud API                 | ✓           | ✓                   |
| Não oficial (Pilot Status web) | ✓           | ✗ — **use uma URL** |

## Áudio é uma mensagem de voz (PTT)

Quando `mediaType` é `audio`, o arquivo é entregue como uma **mensagem de voz (PTT)** do WhatsApp em todos os provedores. Em números não oficiais (Pilot Status web), o destinatário vê brevemente um **indicador de presença "gravando áudio"** antes da entrega; a Meta Cloud API não possui API de presença de saída, então nenhum indicador aparece nos envios pela Meta.

## Mídia com templates

Adicione `media` (+ `mediaType`) a um envio de template para anexar ou sobrescrever a mídia — ela tem precedência sobre qualquer URL de mídia embutida no template:

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

Observe que `media`/`mediaType` não podem ser combinados com um envio de `text` livre. A API aceita `buttons` junto com `mediaType: "video"` ou `"document"`, embora a Meta possa rejeitar botões em algumas mensagens de vídeo/PDF dependendo do cliente do destinatário.

## Relacionado

* [Enviar Mensagens](/pt-BR/guides/send-messages)
* [Templates](/pt-BR/concepts/templates)