Provado em aparelho real em 10/11/2026: imagem, documento, voz, áudio como arquivo e figurinha. Vídeo segue em beta: pode mudar. Os limites abaixo são os da API (o WhatsApp aceita arquivos maiores) e valem hoje.
Atualização de 12/11/2026 (provado em aparelho real): imagem por base64, documento (PDF), voz (PTT), áudio como arquivo e figurinha foram provados pela API pública. Não provados: vídeo e imagem por URL.
Toda mensagem com arquivo usa a mesma ideia: você diz para quem (to), qual arquivo (media) e, quando existir, uma legenda. A base é https://proxybox.com.br/api/whatsapp/v1 e a chave vai no cabeçalho apikey, como nos primeiros passos. O destino é um telefone com código do país (5547999999999, também aceita +55 (47) 99999-9999) ou um grupo, como em [email protected].
Quais são as rotas e os limites de cada tipo?
Cinco rotas, uma por tipo de mídia, cada uma com o seu limite de tamanho e os formatos aceitos.
| Rota | Tipos aceitos | Tamanho máximo |
|---|---|---|
POST /messages/image |
jpeg, png, webp, gif | 10 MB |
POST /messages/video |
mp4, 3gp, mov, webm | 16 MB |
POST /messages/audio |
ogg, opus, mp3, m4a, aac, wav, amr, webm | 16 MB |
POST /messages/document |
qualquer tipo, menos executável, script e página HTML | 25 MB |
POST /messages/sticker |
webp, png, jpg, gif | 1 MB |
A API confere o tipo pelo conteúdo do arquivo, e não pela extensão nem pelo cabeçalho do servidor. Um .jpg que na verdade é outra coisa é recusado.
Como entrego o arquivo: por url ou por base64?
Por url, quando o arquivo já está na internet (a ProxyBox baixa na hora do envio), ou por base64, quando o arquivo está com o seu sistema. O campo media aceita as duas formas.
O campo media aceita duas formas.
Por endereço (url). A ProxyBox baixa o arquivo na hora do envio.
{ "to": "5547999999999", "media": { "url": "https://exemplo.com.br/fotos/pedido-123.jpg" }, "caption": "Seu pedido" }
O endereço precisa ser https, público e responder em até 20 segundos. A API segue no máximo três redirecionamentos e confere cada destino. Se o arquivo passar do limite do tipo, o download para no meio e você recebe media_too_large.
Em base64. Você manda o próprio arquivo dentro do JSON.
{ "to": "5547999999999", "media": { "base64": "iVBORw0KGgo…", "mime": "image/png", "filename": "foto.png" } }
Aceita base64 puro ou no formato data:image/png;base64,…. O base64 aumenta o arquivo em cerca de um terço no tráfego, então prefira url para arquivos grandes. O corpo da requisição de envio de mídia tem teto de 40 MB.
Quais campos cada rota aceita?
Além de to e media, cada tipo tem os seus campos: legenda, visualização única, qualidade, laço de GIF, voz e nome do arquivo.
| Rota | Campos além de to e media |
|---|---|
| imagem | caption (até 1.024 caracteres), view_once (visualização única), hd, reply_to (id da mensagem a responder), mentions |
| vídeo | caption, view_once, hd, gif (toca em laço e sem som), reply_to, mentions |
| áudio | voice (padrão true: vai como mensagem de voz), reply_to |
| documento | filename (nome mostrado no WhatsApp), caption, reply_to, mentions |
| figurinha | nenhum |
mentions é uma lista de telefones, ou "everyone" em grupo.
A resposta de sucesso é a mesma do texto:
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-10T14:03:22-03:00" }
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisHá exemplos prontos em cURL, Node, Python e PHP?
Sim: quatro exemplos abaixo, com url e com base64. Em Go, Java, C# e Ruby, há o envio de imagem.
cURL: imagem por endereço
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/image" \
-H "apikey: SUA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-123-foto" \
-d '{"to":"5547999999999","media":{"url":"https://exemplo.com.br/fotos/pedido-123.jpg"},"caption":"Seu pedido saiu."}'
Node.js: documento em base64
import { readFileSync } from "node:fs";
const arquivo = readFileSync("./comprovante.pdf");
const resp = await fetch("https://proxybox.com.br/api/whatsapp/v1/messages/document", {
method: "POST",
headers: { apikey: process.env.WA_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
to: "5547999999999",
media: { base64: arquivo.toString("base64"), mime: "application/pdf", filename: "comprovante.pdf" },
caption: "Seu comprovante",
}),
});
console.log(resp.status, await resp.json());
Python: vídeo por endereço
import os, requests
r = requests.post(
"https://proxybox.com.br/api/whatsapp/v1/messages/video",
headers={"apikey": os.environ["WA_KEY"]},
json={
"to": "5547999999999",
"media": {"url": "https://exemplo.com.br/videos/tutorial.mp4"},
"caption": "Tutorial de uso",
},
timeout=60,
)
print(r.status_code, r.json())
PHP: imagem em base64
<?php
$arquivo = file_get_contents(__DIR__ . '/foto.png');
$corpo = json_encode([
'to' => '5547999999999',
'media' => ['base64' => base64_encode($arquivo), 'mime' => 'image/png', 'filename' => 'foto.png'],
'caption' => 'Olá!',
]);
$ch = curl_init('https://proxybox.com.br/api/whatsapp/v1/messages/image');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['apikey: ' . getenv('WA_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => $corpo,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
echo curl_exec($ch), PHP_EOL, curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
Como envio um áudio como mensagem de voz?
Mande POST /messages/audio com voice igual a true (o padrão). Se a instância não tiver o conversor de áudio, a API responde 501 unsupported e não manda o arquivo como áudio comum.
Por padrão, POST /messages/audio manda a mídia como mensagem de voz (a bolinha com a onda). Isso exige que o áudio seja convertido para o formato que o WhatsApp usa em voz. Se a instância não tiver o conversor de áudio disponível, a API responde 501 unsupported e não envia o arquivo como áudio comum no lugar, para você não ser surpreendido por uma mensagem diferente da que pediu.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/audio" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"to":"5547999999999","media":{"url":"https://exemplo.com.br/audios/aviso.ogg"},"voice":true}'
Se você prefere mandar o áudio como arquivo de música ou gravação, use "voice": false. A voz não foi provada em todos os formatos de entrada; quando possível, mande ogg com codec opus, que é o formato nativo da voz do WhatsApp.
Como envio uma figurinha?
Com POST /messages/sticker e media em webp, png, jpg ou gif de até 1 MB.
A figurinha aceita webp, png, jpg ou gif de até 1 MB. Para ter o melhor resultado, use webp quadrado com fundo transparente. Figurinha animada não foi provada.
Como envio mídia pelo n8n?
Com o nó HTTP Request e o corpo JSON abaixo; se o arquivo vem de uma etapa anterior, converta-o antes para base64.
- Se o arquivo vem de uma etapa anterior (um PDF gerado, uma foto de formulário), passe por um nó Extract From File com a operação Move File to Base64 String. O n8n em modo de arquivos em disco não entrega o base64 direto na propriedade binária.
- No nó HTTP Request, método POST, credencial Header Auth com o nome
apikey, corpo JSON:
{
"to": "{{ $json.telefone }}",
"media": { "base64": "{{ $json.data }}", "mime": "application/pdf", "filename": "{{ $json.arquivo }}" },
"caption": "Segue o seu documento."
}
- Para arquivos que já estão num endereço público, é mais simples e mais leve usar
{ "url": "…" }e deixar a ProxyBox baixar.
O passo a passo completo, com fluxos prontos, está em WhatsApp no n8n.
Que erros posso receber?
Os de mídia são media_unavailable, media_too_large e unsupported; os demais seguem a tabela geral.
| HTTP | error |
O que fazer |
|---|---|---|
| 422 | media_unavailable |
O endereço não abriu, foi negado, ou o tipo não é aceito. Teste o link num navegador anônimo e confira o tipo do arquivo |
| 422 | media_too_large |
O arquivo passou do limite do tipo. Reduza ou comprima |
| 422 | number_not_on_whatsapp |
O telefone de destino não tem WhatsApp |
| 422 | invalid_request |
Falta campo ou o campo é inválido; veja fields |
| 501 | unsupported |
O recurso não está disponível nesta instância (por exemplo, voz sem conversor) |
| 409 | new_contacts_locked |
A instância está com a trava de contato novo ligada; veja erros e limites |
| 429 | rate_limited ou daily_limit |
Respeite retry_after |
Cada mídia conta como uma mensagem no ritmo da instância (padrão: 10 por minuto e 500 por dia, com pausa de 3 a 10 segundos). Para mandar o mesmo arquivo a muita gente, a regra do WhatsApp é a mesma do texto: só para quem espera receber.
Para enviar num horário marcado, use o campo schedule (veja agendar uma mensagem); no agendamento, a mídia só vale por url.
Veja também
- Reagir, editar, apagar e status: API de WhatsApp
- Guardar mídia do WhatsApp no S3, R2 ou MinIO
- Erros e limites da API de WhatsApp
- Ler conversas e baixar mídia no WhatsApp via API
Índice completo: documentação. Sobre o produto: a oferta de API de WhatsApp da ProxyBox.
Autoria: equipe técnica da ProxyBox. Revisado em 11/11/2026 contra a versão 1.1 da API.