envio de mídia
Enviar imagem, áudio, vídeo e documento pela API de WhatsApp
Para enviar imagem, áudio, vídeo e documento pela API de WhatsApp da D-API, o seu SaaS passa uma URL ou um base64 e escolhe o formato: nota de voz, vídeo redondo, GIF, PDF com nome de arquivo ou álbum. A mídia recebida chega com link pronto no webhook.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
URL ou base64
Cada rota de mídia aceita uma URL http(s) pública ou uma data URI em base64. Para arquivos grandes, a URL deixa o request leve.
O formato certo para cada caso
Áudio como nota de voz com ptt, vídeo redondo com ptv, GIF com gifPlayback e documento com fileName e mimetype definidos por você.
Mídia recebida pronta para usar
Mídias que os contatos mandam chegam no webhook com media_url, um link do arquivo já salvo em storage, sem passo extra de download.
Enviar imagem, áudio, vídeo e documento pela API de WhatsApp é onde muita integração tropeça: arquivo que chega sem nome, áudio que aparece como anexo em vez de nota de voz, PDF de 20 MB que trava o request. Para um SaaS, cada um desses detalhes vira ticket de suporte. Na D-API, cada tipo de mídia tem a sua rota e os campos para controlar exatamente como a mensagem aparece no celular do contato.
Os exemplos abaixo usam casos reais de produto: o laudo em PDF que o software da clínica envia, o comprovante que o sistema de cobrança manda, a foto do prato que a plataforma de delivery anexa e o áudio gerado por um agente de IA.
Rotas de mídia e o campo de cada uma
Todas seguem o mesmo padrão do envio de texto: sessionId, to e o campo da mídia, com opções específicas por tipo.
| Rota | Campo da mídia | Opções |
|---|---|---|
POST /api/v1/messages/send/image |
image |
caption |
POST /api/v1/messages/send/video |
video |
caption, ptv, gifPlayback |
POST /api/v1/messages/send/audio |
audio |
ptt |
POST /api/v1/messages/send/document |
document |
caption, mimetype, fileName |
POST /api/v1/messages/send/sticker |
sticker |
|
POST /api/v1/messages/send/album |
lista de imagens e vídeos | legenda por item |
O campo da mídia aceita dois formatos. Uma URL http:// ou https:// acessível publicamente, que a D-API baixa no momento do envio, ou uma data URI em base64, como data:application/pdf;base64,JVBERi0.... Qualquer outra coisa, como um caminho de arquivo local, é recusada com erro de formato.
Enviar documento com nome de arquivo
O caso mais comum em SaaS B2B é o PDF: boleto, nota fiscal, laudo, contrato. O que separa uma integração caprichada de uma amadora é o nome que aparece para o contato.
curl -X POST https://api.d-api.cloud/api/v1/messages/send/document \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "clinica-vida-recepcao",
"to": "5511999999999",
"document": "https://arquivos.seu-saas.com/laudos/8841.pdf",
"fileName": "Laudo - Hemograma - 14-11.pdf",
"mimetype": "application/pdf",
"caption": "Marcos, seu resultado já está disponível."
}'
Sem fileName, o paciente recebe um arquivo com nome genérico e precisa abrir para saber do que se trata. Com ele, a conversa fica autoexplicativa e o arquivo é fácil de achar depois, na aba de documentos do WhatsApp.
Áudio como nota de voz
Um áudio pode aparecer de dois jeitos no celular: como arquivo anexado ou como a nota de voz com ondinha, igual a uma mensagem gravada na hora. Para lembretes falados ou respostas de um agente de IA, a nota de voz passa muito mais naturalidade. É o ptt: true.
{
"sessionId": "agente-ia-imobiliaria",
"to": "5511999999999",
"audio": "https://arquivos.seu-saas.com/tts/resposta-221.ogg",
"ptt": true
}
Vídeo, vídeo redondo e GIF
A rota de vídeo tem duas variações além do vídeo comum com legenda. ptv: true envia como vídeo redondo, o formato de recado em vídeo do WhatsApp, bom para uma mensagem de boas-vindas gravada pelo dono da academia. gifPlayback: true faz o vídeo tocar em loop, sem som, como um GIF, útil para mostrar um passo a passo curto do seu produto.
Imagem, figurinha e álbum
A imagem aceita caption e cobre a maior parte dos usos: foto do produto, comprovante, cardápio do dia. A documentação lista JPEG e PNG como formatos suportados.
Quando há várias fotos, o álbum agrupa imagens e vídeos numa única mensagem, como o WhatsApp faz ao selecionar várias da galeria. Para uma imobiliária que manda as fotos do apartamento, um álbum é bem melhor que dez mensagens soltas. E a figurinha tem rota própria, para quem usa em atendimento com tom mais leve.
Envio de mídia pesada sem travar o seu worker
Mídia demora mais que texto: a D-API precisa baixar o arquivo, enviar ao WhatsApp e só então confirmar. Para não segurar o request do seu sistema esse tempo todo, use async: true. A API responde na hora com um commandId, e o resultado chega no webhook command.result.
Combine com sequential: true quando a ordem importa. Sem ele, um texto enviado logo depois de um PDF pesado pode chegar antes do PDF. Com ele, os envios para o mesmo contato saem na ordem em que chegaram à API. A página de comandos assíncronos explica o fluxo completo.
Duas proteções do lado da D-API ajudam em escala. O download por URL tenta de novo até 3 vezes, com espera crescente, quando o seu servidor de arquivos responde com erro 5xx. E o upload de um mesmo arquivo ao WhatsApp é reaproveitado por 12 horas na conexão, então mandar o mesmo cardápio para 500 contatos pelo mesmo número não repete o upload 500 vezes.
Prefira URL a base64 para arquivos grandes. O payload fica pequeno, o request é mais rápido e você evita estourar limites do seu próprio proxy ou balanceador.
Receber mídia dos contatos
O caminho inverso é tão importante quanto o envio. O paciente manda a foto da receita, o cliente manda o comprovante do Pix, o lead manda um áudio. Tudo chega no webhook messages.received com o type da mídia, os metadados em media_data e um media_url do arquivo já salvo em storage:
{
"event": "messages.received",
"sessionId": "cobranca-acme",
"data": {
"id": "3EB0F61B5D1F94FAFCD306",
"type": "image",
"from": { "jid": "[email protected]", "name": "João" },
"media_data": {
"width": 1179,
"height": 1127,
"file_length": 108529,
"mimetype": "image/jpeg"
},
"media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/cobranca-acme/image/3EB0F61B5D1F94FAFCD306.jpg"
}
}
Com o media_url, o seu sistema anexa a imagem ao card do cliente sem baixar nada do WhatsApp. Para guardar os arquivos no bucket da sua empresa, há a integração com S3 e MinIO.
Quando você precisa do arquivo de novo, ou a conta usa a opção de não armazenar mídias, POST /api/v1/media/download descriptografa a mídia a partir dos metadados do webhook (media_key, mimetype, direct_path ou url e os hashes). Com base64: true, o conteúdo vem na resposta. Contas com armazenamento de mídias desligado não recebem media_url no webhook e obtêm o arquivo sempre por essa rota, em modo síncrono. A documentação da D-API detalha os campos.
Checklist de mídia para o seu SaaS
Antes de liberar o recurso para os seus clientes, vale revisar quatro pontos. Defina fileName em todo documento. Use ptt: true em áudios que simulam fala. Mande arquivos grandes por URL e com async: true. E trate a mídia recebida pelo media_url, com download pela rota unificada só quando necessário. A visão geral de todos os recursos está na página da API de WhatsApp.
Time D-API. Atualizado em .
Perguntas frequentes
Quais formatos de imagem posso enviar?
A documentação cita JPEG e PNG como formatos suportados. Para outros formatos, converta no seu backend antes do envio.
Posso salvar as mídias recebidas no meu próprio bucket?
Sim. A D-API tem upload automático de mídia para S3 ou MinIO, o que deixa os arquivos dos seus clientes no storage da sua empresa.
A mesma rota de mídia funciona na API Oficial?
Funciona. Nas conexões Cloud API a mídia recebida é identificada pelo media_id, que você usa em POST /api/v1/media/download no lugar de media_key e hashes.
Dá para corrigir a legenda depois de enviar?
Dá, com PUT /api/v1/messages/{messageId}. A edição vale para a legenda de imagem, vídeo ou documento e o WhatsApp aceita até 15 minutos depois do envio.