Enviar arquivo pela API do WhatsApp: guia

Atualizado em 25/10/2026

Para enviar um arquivo pela API do WhatsApp, você faz um POST no endpoint de mensagens com type igual a image, document, audio ou video e indica o arquivo de duas formas: pelo id de uma mídia enviada antes ao endpoint /media ou por um link público. A Meta recomenda o upload com id, aceita imagens JPEG e PNG até 5 MB, áudio e vídeo até 16 MB e documentos até 100 MB. Fora da janela de 24 horas, a mídia só vai como cabeçalho de um template aprovado.

Este guia mostra os formatos aceitos, quando usar upload ou link, quanto tempo um media ID vale, como receber e baixar arquivos que o cliente manda e exemplos prontos em cURL, Node.js e Python.

Upload ou link: as duas formas de enviar mídia

Toda mensagem de mídia da Cloud API tem um objeto com o nome do tipo (image, document, audio, video ou sticker). Dentro dele vai um destes campos, nunca os dois:

Campo	O que é	Quando usar
`id`	ID devolvido pelo endpoint `POST /<PHONE_NUMBER_ID>/media` depois do upload	Recomendado pela Meta. Arquivo reutilizado em muitos envios, campanhas, arquivos privados
`link`	URL HTTPS pública onde o arquivo está hospedado	Envios pontuais, arquivos que já estão num CDN. A Meta marca essa opção como “não recomendada” por desempenho

Com link, os servidores da Meta precisam baixar o arquivo do seu servidor no momento do envio. Se a URL exige login, redireciona para uma página HTML ou devolve um Content-Type diferente do arquivo real, o envio falha. Com id, o arquivo já está na Meta e o envio não depende do seu servidor estar no ar.

Na prática, muitos sistemas fazem assim: o arquivo que vai para muita gente (o catálogo em PDF, o vídeo do tutorial) é enviado uma vez ao /media, e o id é reutilizado enquanto valer. Arquivos gerados na hora (um boleto, uma nota) podem ir por link assinado de curta duração ou por upload logo antes do envio.

Formatos e limites de tamanho oficiais

A tabela abaixo resume a página de mídia da Cloud API:

Tipo	Formatos (MIME)	Tamanho máximo
Imagem	`image/jpeg`, `image/png` (8 bits, RGB ou RGBA)	5 MB
Documento	`application/pdf`, `text/plain`, Word (`.doc`, `.docx`), Excel (`.xls`, `.xlsx`), PowerPoint (`.ppt`, `.pptx`)	100 MB
Áudio	`audio/aac`, `audio/amr`, `audio/mpeg` (MP3), `audio/mp4` (M4A), `audio/ogg` (somente codec OPUS, mono)	16 MB
Vídeo	`video/mp4`, `video/3gpp` (vídeo H.264 e áudio AAC)	16 MB
Sticker	`image/webp`	100 KB estático, 500 KB animado

Alguns detalhes que causam falha com frequência:

Legenda. caption vai até 1.024 caracteres em imagem, vídeo e documento. Áudio não tem legenda.
Documento. O campo filename define o nome exibido, e a extensão dele escolhe o ícone no app. Só os tipos da tabela têm exibição garantida; outros podem ser enviados, mas a Meta não garante que apareçam corretamente.
Vídeo no Android. A Meta avisa que o perfil H.264 “High” com B-frames não é suportado pelo WhatsApp no Android. Use o perfil “Main” sem B-frames ou “Baseline” e coloque o átomo moov antes do mdat (no ffmpeg, -movflags faststart).
MIME errado. Se a extensão ou o tipo declarado não bate com o conteúdo real do arquivo, o envio falha com o erro 131053. No Linux ou macOS, file -I arquivo.png mostra o tipo real.

Exemplo de conversão de vídeo para o formato mais compatível:

ffmpeg -i entrada.mov -c:v libx264 -profile:v main -bf 0 \
  -c:a aac -ac 2 -movflags faststart saida.mp4

Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →

Áudio comum x mensagem de voz

A Cloud API diferencia dois tipos de áudio, segundo a documentação de mensagens de áudio:

Áudio comum. Aparece com ícone de download e de música. Aceita qualquer formato da tabela.
Mensagem de voz. Envie "voice": true dentro do objeto audio. O arquivo precisa ser .ogg com codec OPUS, mono. A mensagem aparece com a foto do perfil da empresa e o ícone de microfone, baixa automaticamente e pode ser transcrita no app do cliente. O botão de play só aparece em arquivos de até 512 KB; acima disso, o cliente vê o ícone de download.

Para converter um MP3 em nota de voz compatível:

ffmpeg -i audio.mp3 -c:a libopus -ac 1 -b:a 32k voz.ogg

Passo 1: fazer o upload e obter o media ID

O upload é um multipart/form-data com três campos obrigatórios: file, type (o MIME) e messaging_product=whatsapp.

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/media" \
  -H "Authorization: Bearer $WHATSAPP_TOKEN" \
  -F "file=@catalogo.pdf;type=application/pdf" \
  -F "type=application/pdf" \
  -F "messaging_product=whatsapp"

Resposta:

{ "id": "1037543291543636" }

O token precisa ter a permissão whatsapp_business_messaging. Em produção, use um token permanente de usuário do sistema em vez do token temporário do painel.

Quanto tempo o media ID vale

Origem do ID	Validade
Upload feito por você	30 dias (a mídia fica armazenada criptografada até ser apagada ou expirar)
Mídia recebida no webhook	7 dias para baixar
URL de download obtida com `GET /<MEDIA_ID>`	5 minutos

Guarde a data do upload junto do id e refaça o upload antes dos 30 dias se o arquivo for usado por mais tempo. Para apagar antes, use DELETE /<MEDIA_ID>.

Passo 2: enviar a mensagem de mídia

Com o id em mãos, o envio é igual ao de uma mensagem de texto pela API, trocando o tipo:

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $WHATSAPP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5584999999999",
    "type": "document",
    "document": {
      "id": "1037543291543636",
      "filename": "catalogo-outubro.pdf",
      "caption": "Segue o catálogo de outubro"
    }
  }'

A resposta traz o wamid da mensagem. Ela só confirma que a Meta aceitou o pedido; a entrega, a leitura e as falhas chegam depois pelo webhook, como explicado no artigo sobre status de mensagem via webhook.

Exemplo em Node.js (upload + envio)

Usa fetch, FormData e Blob nativos do Node.js 18 ou superior:

import { readFile } from 'node:fs/promises';

const GRAPH = 'https://graph.facebook.com/v26.0';
const PHONE_ID = process.env.PHONE_NUMBER_ID;
const TOKEN = process.env.WHATSAPP_TOKEN;

async function uploadMidia(caminho, mime) {
  const form = new FormData();
  form.append('messaging_product', 'whatsapp');
  form.append('type', mime);
  form.append('file', new Blob([await readFile(caminho)], { type: mime }), caminho.split('/').pop());

  const r = await fetch(`${GRAPH}/${PHONE_ID}/media`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${TOKEN}` },
    body: form,
  });
  const corpo = await r.json();
  if (!r.ok) throw new Error(JSON.stringify(corpo.error));
  return corpo.id;
}

async function enviarImagem(para, mediaId, legenda) {
  const r = await fetch(`${GRAPH}/${PHONE_ID}/messages`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: para,
      type: 'image',
      image: { id: mediaId, caption: legenda },
    }),
  });
  return r.json();
}

const id = await uploadMidia('./produto.jpg', 'image/jpeg');
console.log(await enviarImagem('5584999999999', id, 'Chegou o modelo novo'));

Exemplo em Python (link público e nota de voz)

import os
import requests

GRAPH = "https://graph.facebook.com/v26.0"
PHONE_ID = os.environ["PHONE_NUMBER_ID"]
HEADERS = {"Authorization": f"Bearer {os.environ['WHATSAPP_TOKEN']}"}


def enviar(payload: dict) -> dict:
    payload = {"messaging_product": "whatsapp", **payload}
    r = requests.post(f"{GRAPH}/{PHONE_ID}/messages", json=payload, headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()


# Vídeo hospedado no seu CDN
enviar({
    "to": "5584999999999",
    "type": "video",
    "video": {"link": "https://cdn.minhaempresa.com.br/tutorial.mp4", "caption": "Como instalar"},
})

# Nota de voz a partir de um upload
with open("voz.ogg", "rb") as f:
    up = requests.post(
        f"{GRAPH}/{PHONE_ID}/media",
        headers=HEADERS,
        data={"messaging_product": "whatsapp", "type": "audio/ogg"},
        files={"file": ("voz.ogg", f, "audio/ogg")},
        timeout=60,
    )
up.raise_for_status()
enviar({"to": "5584999999999", "type": "audio", "audio": {"id": up.json()["id"], "voice": True}})

Mídia fora da janela de 24 horas: cabeçalho de template

Mensagens de imagem, vídeo, áudio e documento são mensagens livres. Elas só podem ser enviadas com a janela de 24 horas aberta pelo cliente. Para mandar um arquivo a quem não falou com você nas últimas 24 horas, crie um template com cabeçalho de mídia (imagem, vídeo ou documento) e preencha o arquivo no envio:

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "template",
  "template": {
    "name": "segunda_via_boleto",
    "language": { "code": "pt_BR" },
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "document", "document": { "id": "1037543291543636", "filename": "boleto.pdf" } }
        ]
      },
      { "type": "body", "parameters": [{ "type": "text", "text": "Maria" }] }
    ]
  }
}

O artigo sobre templates da API do WhatsApp explica criação, categorias e aprovação.

Receber e baixar arquivos enviados pelo cliente

Quando o cliente manda uma foto, um PDF ou um áudio, o webhook traz o objeto do tipo com id, mime_type e sha256 (e caption ou filename, quando houver):

{
  "from": "5584999999999",
  "id": "wamid.HBgM...",
  "type": "image",
  "image": { "id": "1489362375523190", "mime_type": "image/jpeg", "sha256": "8f2c..." }
}

Para baixar, são duas chamadas:

# 1. Obter a URL temporária (vale 5 minutos)
curl "https://graph.facebook.com/v26.0/1489362375523190" \
  -H "Authorization: Bearer $WHATSAPP_TOKEN"

# 2. Baixar o binário da URL devolvida, com o mesmo token
curl -L "URL_DEVOLVIDA" -H "Authorization: Bearer $WHATSAPP_TOKEN" -o foto.jpg

Sem o header Authorization, o download falha. Se der 404, peça uma URL nova e tente de novo. Baixe logo e salve no seu storage: o ID recebido expira em 7 dias. O limite de mídia recebida é de 100 MB; acima disso, o webhook chega com o erro 131052, e o ideal é pedir ao cliente um arquivo menor. Os detalhes do formato dos eventos estão no guia de webhooks da API do WhatsApp.

Erros mais comuns ao enviar mídia

Sintoma	Causa provável	O que fazer
Erro `131053`	MIME declarado diferente do conteúdo, formato não suportado	Confira o tipo real do arquivo e use um formato da tabela
Erro `131052` (mídia recebida)	Arquivo do cliente acima de 100 MB	Peça um arquivo menor
Envio com `link` falha	URL privada, redirecionamento para HTML, certificado inválido	Teste a URL com `curl -I` fora da sua rede ou use upload
Envio com `id` falha	ID expirado (mais de 30 dias) ou de outro número	Refaça o upload pelo mesmo `phone_number_id`
Vídeo não abre no Android	H.264 High com B-frames	Recodifique em Main ou Baseline
Áudio chega sem botão de play	Arquivo acima de 512 KB ou fora de OGG OPUS	Reduza o bitrate e envie como `voice`

Para a lista completa de códigos, veja o artigo sobre erros da API do WhatsApp.

Como fazer com a Vectalk

Na Vectalk, os payloads de mídia são os mesmos da Cloud API. Muda a URL base e o token:

Upload: POST https://apis.vectalk.com.br/api/media (multipart, com file, type e messaging_product), usando um token de instância.
Envio: POST https://apis.vectalk.com.br/api/messages com o mesmo JSON de imagem, documento, áudio ou vídeo.
Mídia recebida: GET /api/media/{mediaId} devolve a URL temporária, e GET /api/media/{mediaId}/download devolve o binário direto.
Excluir: DELETE /api/media/{mediaId}.

curl -X POST https://apis.vectalk.com.br/api/media \
  -H "Authorization: Bearer $VECTALK_TOKEN" \
  -F "file=@produto.jpg" \
  -F "type=image/jpeg" \
  -F "messaging_product=whatsapp"

As rotas estão em Upload de Mídia e Imagem na documentação. O custo das mensagens entra na fatura da Vectalk, sem cartão cadastrado na Meta. Para começar, crie sua conta em apps.vectalk.com.br/register. Se você ainda está entendendo a plataforma como um todo, comece pelo guia da API oficial do WhatsApp.

Perguntas frequentes

Posso enviar imagem em WebP?

Não como mensagem de imagem. A Cloud API aceita JPEG e PNG para imagens. WebP é usado apenas em stickers. Converta antes do upload.

Qual o tamanho máximo de um PDF pela API do WhatsApp?

100 MB, o mesmo limite de todos os documentos suportados (PDF, TXT, Word, Excel e PowerPoint).

Enviar mídia custa mais que enviar texto?

Não. A Meta cobra por mensagem entregue conforme a categoria, e não pelo tipo de conteúdo. Uma imagem enviada dentro da janela de atendimento é uma mensagem de serviço, como um texto livre: desde 1º de outubro de 2026, cada número tem 1.000 mensagens de serviço grátis por mês, e a cobrança começa na 1.001ª. Os valores estão no artigo de preço da API do WhatsApp no Brasil.

Posso reutilizar o mesmo media ID para milhares de envios?

Sim, enquanto ele valer (30 dias após o upload). É a forma recomendada para campanhas com o mesmo arquivo, porque evita que a Meta baixe o arquivo do seu servidor a cada envio.

Como enviar mais de um arquivo na mesma mensagem?

Não há envio de álbum. Cada arquivo é uma mensagem separada, com o seu próprio wamid e status.

Fontes oficiais consultadas em 25/10/2026: Media (Cloud API), Image messages, Document messages, Audio messages, Video messages, Documentação da Vectalk: Upload de Mídia.

Teste a API oficial do WhatsApp hoje

Crie sua conta, gere o token e envie a primeira mensagem seguindo o guia da documentação. Mesmos payloads e webhooks da Cloud API da Meta.

Criar conta grátis

Ler a documentação

Como enviar imagem, PDF, áudio e vídeo pela API do WhatsApp