Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Enviar e receber

Enviar mídia pela API de WhatsApp: imagem, vídeo, áudio, voz, documento e figurinha

Como enviar imagem, vídeo, áudio, mensagem de voz, documento e figurinha pela API de WhatsApp, por URL ou base64, com limites de tamanho e erros.

5 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Use POST /messages/image, /video, /audio, /document ou /sticker com to e media, que é { "url": "https://…" } ou { "base64": "…", "mime": "…" }. Os limites são imagem 10 MB, vídeo e áudio 16 MB, documento 25 MB e figurinha 1 MB. A voz depende do conversor de áudio da instância.

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.

json
{ "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.

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:

json
{ "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átis

Há 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

bash
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

js
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

python
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
<?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.

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

  1. 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.
  2. No nó HTTP Request, método POST, credencial Header Auth com o nome apikey, corpo JSON:
json
{
  "to": "{{ $json.telefone }}",
  "media": { "base64": "{{ $json.data }}", "mime": "application/pdf", "filename": "{{ $json.arquivo }}" },
  "caption": "Segue o seu documento."
}
  1. 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

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

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp