Como enviar PDF, imagem, áudio e vídeo pelo WhatsApp via API
Envie PDF, imagem, vídeo, áudio, mensagem de voz e figurinha pelo WhatsApp com a API: payload de cada tipo, mimetype, legenda e mídia recebida no webhook.
Mandar texto pelo WhatsApp a partir do seu sistema é o primeiro passo. Logo depois vem o pedido que todo projeto recebe: anexar o boleto em PDF, mandar a foto do produto, o vídeo de instrução, o áudio de boas-vindas. E aí surgem as dúvidas práticas: o arquivo vai no corpo da requisição ou por link? Qual campo diz que é um documento? Por que o PDF chegou sem nome? Como receber a foto que o cliente mandou de volta?
Na apiwpp, a mídia sempre viaja por URL: você informa onde o arquivo está, e o gateway baixa e entrega no WhatsApp na hora em que a mensagem sai da fila. Não existe upload de arquivo no corpo do envio. Isso simplifica o seu código, mas traz duas regras que valem para qualquer tipo de arquivo: a URL precisa ser https e pública, e precisa continuar válida até o envio acontecer.
Este tutorial mostra o payload de cada tipo (imagem, vídeo, áudio, mensagem de voz, documento e figurinha), os campos que mudam de um para outro, os erros mais comuns e como tratar a mídia que chega no seu webhook.
Como o envio de mídia funciona
Todo envio passa pela mesma rota, POST /connections/{id}/send, com a mesma chave de API (escopo messages:send) e a mesma resposta. A diferença está no conteúdo: em vez do campo message, você manda um objeto media.
Campo de media | Obrigatório | Para que serve |
|---|---|---|
type | Sim | image, video, audio, document ou sticker |
url | Sim | Endereço https público do arquivo |
mimetype | Só em document | Tipo do arquivo, como application/pdf |
fileName | Não | Nome que o destinatário vê no documento |
caption | Não | Legenda de imagem, vídeo ou documento |
ptt | Não | true envia um áudio como mensagem de voz |
A requisição não espera o arquivo ser baixado. Ela coloca a mensagem na fila do número e responde 202 na hora, com o job:
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 3 }
scheduledAt é quando o envio está previsto (unix em milissegundos) e position é o lugar na fila. A fila respeita o ritmo que protege o número (por padrão, 3 envios por minuto, 60 por hora e 200 por dia, com 3 a 8 segundos entre um e outro), então o download do arquivo acontece no momento do envio, não no momento da requisição. Os detalhes do ritmo estão em fila com ritmo anti-bloqueio.
Por que a URL precisa ser pública
O gateway baixa o arquivo com segurança: aceita apenas https e recusa endereços privados ou internos, como localhost, IPs de rede interna e endereços de metadados de nuvem. Um link para o seu servidor de homologação atrás da VPN, portanto, não funciona.
Para arquivos que não podem ficar abertos para qualquer pessoa (boletos, notas, contratos), use uma URL assinada do seu armazenamento, como as de S3, R2 ou Google Cloud Storage. Só dê a ela uma validade folgada: se a fila do número estiver cheia, o envio pode acontecer bem depois da requisição, e um link que expira em 60 segundos pode já estar morto quando chegar a vez da mensagem.
Enviar imagem e vídeo
Imagem é o caso mais simples: type, url e, se quiser, uma legenda.
curl -s -X POST "https://api.apiwpp.com/connections/$ID/send" \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "5511988887777",
"media": {
"type": "image",
"url": "https://cdn.exemplo.com.br/produtos/tenis-azul.jpg",
"caption": "Chegou o tamanho 42 que você pediu!"
},
"clientRef": "produto-8812-foto"
}'
Vídeo segue exatamente o mesmo formato, trocando o type:
{
"to": "5511988887777",
"media": {
"type": "video",
"url": "https://cdn.exemplo.com.br/tutoriais/instalacao.mp4",
"caption": "Passo a passo da instalação em 2 minutos."
},
"clientRef": "pedido-4410-video-instalacao"
}
O to é o número com código do país e DDD, só dígitos. Antes de enviar, o gateway pergunta ao WhatsApp em qual endereço aquele número está registrado, então contas antigas sem o nono dígito também recebem. Um número que não está no WhatsApp falha na hora, sem novas tentativas.
Enviar PDF e outros documentos
Documento é o tipo que mais gera erro, porque tem uma exigência a mais: o mimetype é obrigatório. Sem ele, a resposta é 400 com { "error": "media.mimetype is required for documents" } e nada entra na fila.
{
"to": "5511988887777",
"media": {
"type": "document",
"url": "https://arquivos.exemplo.com.br/boletos/1234.pdf?assinatura=abc123",
"mimetype": "application/pdf",
"fileName": "boleto-pedido-1234.pdf",
"caption": "Segue o boleto do pedido 1234, com vencimento na sexta."
},
"clientRef": "pedido-1234-boleto"
}
Três cuidados que fazem diferença para quem recebe:
- Sempre mande
fileName. Sem ele, o arquivo chega com um nome genérico, e o cliente não encontra o boleto depois na conversa. Inclua a extensão (.pdf,.xlsx,.zip). - Use o
mimetypecerto para o arquivo. Os mais comuns:
| Arquivo | mimetype |
|---|---|
application/pdf | |
| Planilha Excel (.xlsx) | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
| Documento Word (.docx) | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| CSV | text/csv |
| ZIP | application/zip |
- Escreva a legenda como mensagem. "Segue o boleto do pedido 1234" explica o anexo para quem vê a notificação no celular; um PDF sozinho, de um número que a pessoa não reconhece, parece suspeito.
Se você envia notas e boletos em volume, o post sobre notificações de pedido para e-commerce mostra como encaixar o PDF no fluxo de confirmação, pagamento e entrega.
Enviar áudio e mensagem de voz
O WhatsApp trata de dois jeitos um arquivo de áudio. Como arquivo de áudio, ele aparece como anexo com um player. Como mensagem de voz, aparece igual a um áudio gravado no próprio aplicativo, com a onda sonora. A diferença é um campo: ptt: true.
{
"to": "5511988887777",
"media": {
"type": "audio",
"url": "https://cdn.exemplo.com.br/audios/boas-vindas.ogg",
"ptt": true
},
"clientRef": "cliente-771-boas-vindas"
}
Sem ptt (ou com ptt: false), o mesmo arquivo vai como anexo de áudio. Áudio não leva legenda: se precisar de texto junto, mande uma mensagem de texto separada, com um clientRef próprio.
Na prática, mensagens de voz em formato OGG com codec Opus são as que o WhatsApp exibe de forma mais natural, porque é o formato que o próprio aplicativo grava. Se o seu áudio está em MP3 ou WAV, converta antes de publicar, por exemplo com ffmpeg -i entrada.mp3 -c:a libopus saida.ogg.
Figurinhas
Figurinha (sticker) usa só type e url, sem legenda:
{ "to": "5511988887777", "media": { "type": "sticker", "url": "https://cdn.exemplo.com.br/stickers/obrigado.webp" } }
O formato das figurinhas no WhatsApp é WebP, de preferência quadrado. Use com parcimônia: numa conversa de atendimento, uma figurinha de agradecimento cai bem; numa cobrança, não.
O mesmo envio em Node.js e Python
Nos seus sistemas, vale ter uma função única que recebe o tipo, a URL e os campos opcionais. Em Node.js 18 ou mais recente, com o fetch nativo:
// send-media.mjs
const API = 'https://api.apiwpp.com'
export async function sendMedia(connectionId, to, media, clientRef) {
const response = await fetch(`${API}/connections/${connectionId}/send`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.APIWPP_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to, media, clientRef }),
})
const body = await response.json()
if (response.status === 429) {
const wait = response.headers.get('Retry-After')
throw new Error(`Limite atingido (${body.error}); tente de novo em ${wait} s`)
}
if (!response.ok) throw new Error(`Envio recusado: ${response.status} ${body.error}`)
return body // { jobId, scheduledAt, position }, ou o job original com duplicate: true
}
await sendMedia(process.env.APIWPP_CONNECTION_ID, '5511988887777', {
type: 'document',
url: 'https://arquivos.exemplo.com.br/boletos/1234.pdf',
mimetype: 'application/pdf',
fileName: 'boleto-pedido-1234.pdf',
caption: 'Segue o boleto do pedido 1234.',
}, 'pedido-1234-boleto')
Em Python, com requests:
import os
import requests
API = "https://api.apiwpp.com"
def send_media(connection_id: str, to: str, media: dict, client_ref: str) -> dict:
response = requests.post(
f"{API}/connections/{connection_id}/send",
headers={"Authorization": f"Bearer {os.environ['APIWPP_KEY']}"},
json={"to": to, "media": media, "clientRef": client_ref},
timeout=15,
)
if response.status_code == 429:
raise RuntimeError(f"Limite atingido; tente de novo em {response.headers.get('Retry-After')} s")
response.raise_for_status()
return response.json()
send_media(
os.environ["APIWPP_CONNECTION_ID"],
"5511988887777",
{"type": "image", "url": "https://cdn.exemplo.com.br/produtos/tenis-azul.jpg", "caption": "Seu pedido!"},
"pedido-1234-foto",
)
O clientRef é o que torna esse código seguro para repetir. Se a rede cair e o seu sistema mandar a mesma requisição de novo, a resposta é 200 com o job original e "duplicate": true, e o cliente não recebe o boleto duas vezes. A chave fica reservada por 7 dias. O tutorial de envio com Node.js detalha os outros erros (400, 401, 403) e o cliente TypeScript gerado da especificação OpenAPI; a página de integração com Python reúne o mesmo para quem usa Flask ou FastAPI.
Quando o arquivo não chega
A resposta 202 só diz que o envio entrou na fila. Se o arquivo não puder ser baixado quando chegar a vez da mensagem (link expirado, endereço interno, servidor fora do ar), o gateway tenta de novo e, esgotadas as tentativas, desiste. Com clientRef, o seu webhook recebe message.send_failed com reason: attempts_exhausted e o mesmo clientRef, e você sabe exatamente qual anexo precisa de um link novo.
Os erros mais comuns e o que fazer:
| Sintoma | Causa provável | O que fazer |
|---|---|---|
400 com media.mimetype is required for documents | document sem mimetype | Inclua o mimetype do arquivo |
400 com Connection not ready (status: close) | O número não está conectado | Reconecte e acompanhe o evento connection.status |
message.send_failed com attempts_exhausted | O arquivo não pôde ser baixado na hora do envio | Confira se a URL é https, pública e ainda válida |
message.send_failed com not_on_whatsapp | O número não tem WhatsApp | Verifique a base antes com POST /connections/{id}/contacts/check |
429 com new_recipient_cap_reached | Teto de destinatários novos em 24 h atingido | Espere o tempo do cabeçalho Retry-After |
Quando o envio sai, o message.delivery informa a mudança de status (sent, delivered, read ou failed) com o messageId e o clientRef. O post sobre webhooks do WhatsApp mostra como receber e validar esses eventos.
Localização e templates: outras formas de conteúdo
Nem toda informação precisa de um arquivo. Para indicar onde fica a loja ou o ponto de retirada, mande uma localização, que abre direto no mapa do celular:
{
"to": "5511988887777",
"location": { "latitude": -23.5614, "longitude": -46.6559, "name": "Loja Paulista", "address": "Av. Paulista, 1000" }
}
E para mensagens que se repetem com poucos dados diferentes, como "seu pedido saiu para entrega", use um template: crie uma vez com POST /connections/{id}/templates, com variáveis entre chaves duplas, e envie pelo nome.
{ "to": "5511988887777", "template": "pedido_enviado", "variables": { "nome": "Ana", "pedido": "1234" } }
Se faltar alguma variável, a resposta é 400 com a lista em missingVariables. Os templates da apiwpp são mensagens salvas por você, sem aprovação da Meta; veja a diferença em templates de mensagem.
Receber mídia no webhook
O caminho de volta também importa: o cliente responde com a foto do comprovante, o áudio com a dúvida, o PDF assinado. Tudo chega no evento message.incoming, no mesmo envelope dos outros eventos (type, connectionId, tenantId, externalId, timestamp, data). Quando a mensagem traz mídia, data.media vem preenchido:
{
"type": "message.incoming",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "loja-42",
"timestamp": "2026-07-08T12:00:00.000Z",
"data": {
"jid": "[email protected]",
"phone": "+5511988887777",
"body": "Segue o comprovante",
"timestamp": 1790251200,
"raw": { "key": { "remoteJid": "[email protected]", "fromMe": false, "id": "IN-IMG-1" } },
"media": {
"type": "image",
"url": "https://…/media/8b1d4e7f-…/IN-IMG-1.jpg?exp=1790337600&sig=…",
"mimetype": "image/jpeg",
"fileName": "IN-IMG-1.jpg",
"fileSize": 48213,
"expiresAt": 1790337600000
}
}
}
data.body traz a legenda (vazia quando a mídia veio sem texto). data.media.url é uma URL assinada e temporária: baixe o arquivo sem credencial, exatamente como veio, antes de expiresAt. Depois disso, ou se o link for alterado, a resposta é 404.
Três regras para tratar esse link:
- Baixe na hora, não guarde a URL. Grave o arquivo no seu armazenamento e salve o caminho dele, não o link do gateway.
- Trate o link como segredo. Até expirar, qualquer pessoa com ele baixa o arquivo: não registre em log nem repasse.
- Processe de forma idempotente. A entrega de webhooks é "pelo menos uma vez": o mesmo evento pode chegar duas vezes, então use o identificador da mensagem, que em
message.incomingfica emdata.raw.key.id, para não baixar nem processar em dobro.
Um exemplo em Node.js, a ser chamado depois de verificar a assinatura HMAC do webhook e responder 2xx (o post de webhooks mostra essa verificação):
import { writeFile } from 'node:fs/promises'
import path from 'node:path'
export async function saveIncomingMedia(event) {
if (event.type !== 'message.incoming' || !event.data.media) return
const { url, fileName, expiresAt } = event.data.media
if (Date.now() > expiresAt) return // o link já expirou
const response = await fetch(url) // sem cabeçalho de autenticação
if (!response.ok) throw new Error(`Download falhou: ${response.status}`)
// O id da mensagem no nome do arquivo: um evento repetido sobrescreve, não duplica
const id = event.data.raw?.key?.id ?? Date.now()
const file = Buffer.from(await response.arrayBuffer())
await writeFile(path.join('uploads', `${event.connectionId}-${id}-${path.basename(fileName)}`), file)
}
Em produção, troque o disco local pelo seu armazenamento de objetos e rode o download numa fila, para responder ao webhook rápido.
Como começar hoje
- Crie sua conta na apiwpp e conecte um número pelo QR code: o teste de 7 dias não pede cartão.
- Crie uma chave de API com o escopo
messages:sende guarde numa variável de ambiente. - Suba um PDF de teste num armazenamento com URL https pública ou assinada, com validade de algumas horas.
- Mande o documento com
type,url,mimetype,fileNameecaption, sempre com umclientRef. - Configure o webhook do projeto, envie uma foto do celular para o número e baixe o arquivo a partir do
message.incoming.
Perguntas frequentes
Posso enviar o arquivo direto no corpo da requisição, em base64?
Não. A apiwpp recebe mídia apenas por URL: você informa um endereço https público e o gateway baixa o arquivo na hora do envio. Para arquivos privados, use uma URL assinada do seu armazenamento, com validade suficiente para a mensagem sair da fila.
Por que o meu PDF foi recusado com erro 400?
O tipo document exige o campo mimetype. Sem ele, a resposta é 400 com media.mimetype is required for documents e nada entra na fila. Para PDF, use application/pdf e mande também o fileName com a extensão.
Como mandar um áudio que aparece como mensagem de voz?
Envie type: "audio" com ptt: true. Sem esse campo, o arquivo chega como anexo de áudio com player. Arquivos OGG com codec Opus são os que o WhatsApp exibe de forma mais natural como mensagem de voz.
Posso usar um link do meu servidor interno ou de localhost?
Não. Por segurança, o gateway recusa endereços privados ou internos e aceita apenas https. O arquivo precisa estar num endereço público, como um CDN ou um bucket com URL assinada.
Como recebo as fotos e os documentos que os clientes enviam?
Pelo evento message.incoming do webhook, no campo data.media, com tipo, mimetype, nome, tamanho e uma URL assinada e temporária. Baixe o arquivo antes de expiresAt, guarde no seu armazenamento e trate o link como segredo.
Enviar mídia custa mais do que enviar texto?
Não. Na apiwpp o preço é por número conectado por mês, e as mensagens são ilimitadas dentro dos limites de ritmo, sejam de texto ou de mídia. Os valores de cada plano estão em preços.
Leia também: