Envio de imagem, vídeo, áudio e documentos
Envie imagens, vídeos, áudios, mensagens de voz, PDFs e figurinhas pelo WhatsApp a partir de uma URL https, e receba a mídia dos clientes no webhook.
Atualizado em
Muita comunicação útil no WhatsApp não é texto: o boleto em PDF, a foto do produto, o comprovante, o áudio explicando um passo, a figurinha de boas-vindas. Na apiwpp, toda essa mídia sai pela mesma rota das mensagens de texto, entra na mesma fila do número e tem o resultado contado pelos mesmos webhooks.
A diferença é o campo: em vez de message, você manda media, com o tipo e a URL do arquivo.
Os tipos de mídia
type | Para que serve | Campos úteis |
|---|---|---|
image | Fotos, prints, cardápios, comprovantes | caption |
video | Vídeos curtos, demonstrações | caption |
audio | Áudios; com ptt: true, sai como mensagem de voz | ptt |
document | PDF, planilhas, contratos, boletos | mimetype (obrigatório), fileName, caption |
sticker | Figurinhas |
Um exemplo completo, enviando um boleto em PDF com nome de arquivo e legenda:
curl -s -X POST "https://api.apiwpp.com/connections/$CONNECTION_ID/send" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"to": "5511988887777",
"media": {
"type": "document",
"url": "https://cdn.example.com/boletos/1234.pdf",
"mimetype": "application/pdf",
"fileName": "boleto-1234.pdf",
"caption": "Segue o seu boleto."
},
"clientRef": "boleto-1234"
}'
A resposta é a mesma do texto: 202 com jobId, scheduledAt e position. O arquivo é baixado e enviado quando chega a vez dele na fila.
A mídia vai por URL, não no corpo da requisição
A apiwpp não recebe o arquivo dentro da chamada: você informa uma URL https pública, e a API baixa o arquivo na hora do envio. Isso mantém as requisições pequenas e rápidas, e combina com o que a maioria dos sistemas já tem: arquivos num bucket, numa CDN ou gerados por uma rota do seu próprio servidor.
Algumas boas práticas:
- Use links que continuem válidos até o envio. Como a mensagem espera a vez na fila, uma URL assinada que expira em poucos segundos pode vencer antes do download. Dê uma validade confortável ao link.
- Informe o
mimetypecerto em documentos. Ele é obrigatório paradocumente é o que faz o WhatsApp mostrar o ícone e abrir o arquivo com o aplicativo correto. - Dê um
fileNamelegível. É o nome que o cliente vê na conversa e ao salvar o arquivo:boleto-1234.pdfé melhor quea8f3e1.pdf.
Download seguro
Baixar arquivos a partir de URLs informadas por terceiros é uma porta clássica para ataques contra a infraestrutura interna. Por isso, a apiwpp recusa endereços privados ou internos e só aceita URLs https públicas. Na prática, você não precisa se preocupar com isso, desde que o arquivo esteja num endereço acessível pela internet.
Áudio como mensagem de voz
Um áudio comum aparece na conversa como um arquivo de áudio. Com ptt: true, ele chega como mensagem de voz, com a onda sonora e o botão de reproduzir, igual a um áudio gravado no celular:
{
"to": "5511988887777",
"media": { "type": "audio", "url": "https://cdn.example.com/audios/boas-vindas.ogg", "ptt": true }
}
Receber mídia dos clientes
O caminho inverso também funciona. Quando um cliente manda uma foto, um áudio ou um documento para o número, o seu servidor recebe um evento message.incoming com a mídia em data.media.url: uma URL assinada e temporária do arquivo, válida até data.media.expiresAt.
Três cuidados com essa URL:
- Baixe o arquivo quando o evento chegar, em vez de guardar a URL para depois.
- Use a URL exatamente como veio, sem credencial extra.
- Trate a URL como um segredo: não registre em logs nem repasse para outros sistemas.
Com isso, fica simples guardar comprovantes enviados por clientes, anexar fotos a um chamado de suporte ou transcrever áudios no seu sistema.
Mídia e o ritmo da fila
Mensagens com mídia seguem as mesmas regras de ritmo do texto: por padrão, 3 por minuto, 60 por hora e 200 por dia por número, com intervalos aleatórios entre os envios. Não há cobrança por arquivo: a apiwpp cobra por número conectado, e as mensagens são ilimitadas dentro desses limites.
Use também o clientRef nos envios de mídia. Se a sua requisição for repetida, a API devolve o job original em vez de mandar o mesmo boleto duas vezes, e o identificador volta nos eventos message.delivery e message.send_failed.
Para exemplos em mais linguagens, leia o tutorial como enviar PDF, imagem, áudio e vídeo pelo WhatsApp via API. Para o envio de texto, localização e templates, veja envio de mensagens, ou todos os recursos da apiwpp.
Perguntas frequentes
Posso enviar o arquivo direto no corpo da requisição?
Não. A mídia é enviada a partir de uma URL https pública, que a apiwpp baixa na hora do envio. Coloque o arquivo num bucket, numa CDN ou numa rota do seu servidor e informe o endereço no campo url.
Por que o meu envio de documento foi recusado?
O tipo document exige o campo mimetype, como application/pdf. Confira também se a URL é https e pública: endereços privados ou internos são recusados.
Como envio um áudio que aparece como mensagem de voz?
Envie com type: "audio" e ptt: true. Sem o ptt, o áudio chega como arquivo de áudio comum.
Consigo receber as fotos e documentos que os clientes enviam?
Sim. Eles chegam no webhook message.incoming, com uma URL assinada e temporária do arquivo. Baixe o arquivo assim que o evento chegar, antes de a URL expirar.
Outros recursos
Todos: Recursos →POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. A API resolve o endereço do destinatário, mostra o "digitando…" e avisa o resultado pelo webhook message.delivery.
Cada evento do número chega no seu servidor com um POST assinado com HMAC-SHA256. A entrega é feita pelo menos uma vez, com novas tentativas, registro de cada entrega e reenvio.
Depois do pareamento, a sessão do número fica salva e criptografada nos servidores da apiwpp. Reinícios, atualizações e quedas de rede não pedem um novo QR code, e o celular não precisa ficar ligado.