Como enviar imagem, documento e áudio pela API oficial do WhatsApp

Resposta curta: mídia sai pelo mesmo endpoint das mensagens de texto, POST https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages, mudando só o type e o objeto correspondente. Existem dois caminhos para apontar o arquivo: link, com a URL pública do arquivo, ou identificador, subindo o arquivo antes e usando o id devolvido. Link é o caminho mais rápido para começar. E tem um detalhe que separa quem manda áudio de quem manda bolha de voz: o arquivo precisa ser .ogg com codec Opus e o corpo precisa de "voice": true. Sem os dois, o áudio chega como anexo com botão de download.

Principais pontos

• Um endpoint para tudo. O envio de imagem, áudio, vídeo e documento usa a mesma rota de mensagens, trocando o type.
• Link é o caminho simples. Você aponta a URL do arquivo no corpo, sem upload prévio e sem multipart.
• Identificador serve para reuso. Suba uma vez com POST /v1/{phone_number_id}/media e reaproveite o id por 30 dias.
• Bolha de voz tem duas condições. Arquivo .ogg com codec Opus e "voice": true no corpo. Acima de 512 KB o ícone de tocar vira ícone de download.
• Mídia sem template é mensagem de serviço. Ela só chega a quem falou com você nas últimas 24 horas. Fora da janela, o caminho é template.

Antes de começar: os seus identificadores

O envio precisa do phone_number_id, e quem só tem o token descobre esse valor por uma chamada:

GET https://cloud.datafyapi.com.br/me
Authorization: Bearer sk_live_xxx

{
  "cliente_id": "uuid-do-cliente",
  "phone_number_id": "106540352242922",
  "waba_id": "366634483210360",
  "business_id": "123456789"
}

Guarde o phone_number_id. Ele entra na URL de todo envio, e é o campo que mais desaparece quando a gente monta o teste na pressa.

Onde encontrar os exemplos prontos

Na documentação, o caminho é a seção Messages, operação de enviar mensagens. No seletor de exemplo aparecem as variações por tipo, e em imagem existem duas: imagem por mídia e imagem por URL. Essa é exatamente a escolha entre identificador e link.

O botão test request dispara a chamada dali mesmo, com os campos preenchidos na tela: o token, o phone_number_id e o destino. Do lado dos guias, a mesma estrutura aparece em mensagens de serviço, em tipos de mensagem, com um exemplo por formato.

Vale insistir num ponto: é o mesmo endpoint em todos os casos. Os exemplos separados existem para você não precisar montar o corpo na mão, e o que você copia dali funciona igual no n8n, no Make ou no seu código.

Como enviar mídias pela API oficial do WhatsAppCanal DATA7 · 7 min · assistir no YouTube

Caminho 1: enviar por link

Imagem com legenda, que é o exemplo mais comum:

POST https://cloud.datafyapi.com.br/v1/106540352242922/messages
Authorization: Bearer sk_live_xxx
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "image",
  "image": {
    "link": "https://files.datafyapi.com.br/uuid-cliente/2026/09/foto.jpg",
    "caption": "Segue a foto"
  }
}

A resposta confirma que a Meta aceitou a requisição:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
  "messages": [{ "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjBBRkZ..." }]
}

Aceitou não é entregou. O status real chega pelo webhook, e é lá que você vê sent, delivered, read ou failed.

Caminho 2: subir o arquivo e usar o identificador

Quando você vai mandar o mesmo arquivo muitas vezes, ou quando não tem onde hospedar, o upload resolve:

POST https://cloud.datafyapi.com.br/v1/106540352242922/media
Authorization: Bearer sk_live_xxx
Content-Type: multipart/form-data

messaging_product=whatsapp
type=image/jpeg
file=@foto.jpg

{ "id": "1037543291543636" }

No envio, o id entra no lugar do link:

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "image",
  "image": { "id": "1037543291543636", "caption": "Segue a foto" }
}

O arquivo fica hospedado no servidor da Meta e o identificador vale 30 dias. O upload tem limite próprio de 60 requisições por minuto na Datafy, contra 500 por minuto no envio de mensagens. São camadas diferentes, e a camada de upload é a mais estreita: quem gera arquivo a cada envio esbarra nela antes de esbarrar em qualquer limite da Meta.

Quando usar link e quando usar identificador

A aba de mídias do painel existe justamente para o último caso: você sobe o arquivo, clica em copiar o link e usa esse link no corpo do envio. Os arquivos da aba também expiram em 30 dias, então é hospedagem de trabalho, não arquivo morto.

Documento com nome de arquivo

Documento tem um campo que os outros tipos não têm, e ignorá-lo deixa o PDF com um nome ilegível na conversa do cliente:

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "document",
  "document": {
    "link": "https://files.datafyapi.com.br/uuid-cliente/2026/09/proposta.pdf",
    "caption": "Segue a proposta conforme combinado",
    "filename": "Proposta comercial"
  }
}

O filename é o nome que aparece no balão da mensagem. O caption é o texto que acompanha o arquivo. São coisas diferentes e as duas valem a pena preencher.

Documento é o tipo com o maior teto de tamanho, 100 MB, e por isso é o que mais estoura tempo de envio em conexão ruim.

Áudio: o que separa bolha de voz de anexo

Esse é o ponto que gera mais dúvida. O corpo é simples:

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "audio",
  "audio": {
    "link": "https://files.datafyapi.com.br/uuid-cliente/2026/09/audio.ogg",
    "voice": true
  }
}

O campo voice com valor true vem da documentação da Meta e é ele que pede a apresentação de mensagem de voz, com a onda sonora. Mas ele não trabalha sozinho. A documentação de mensagens de áudio da Meta traz três regras:

Formato. Mensagem de voz exige arquivo .ogg com codec Opus. Áudio em aac, mp3, m4a ou amr é aceito no envio, mas chega como arquivo de áudio comum.

Tamanho. O ícone de tocar aparece somente em arquivos de 512 KB ou menos. Acima disso, o mesmo áudio chega como ícone de download.

Sem os dois. Sem Opus e sem voice, o resultado é um anexo com botão de download, o que costuma soar frio no meio de um atendimento.

Israel Henrique, CTO da Datafy, mostra o comportamento de tamanho na prática e é honesto sobre o limite do que sabia de cabeça: "existe um limite de tamanho. Se o áudio for muito grande, ele não vai ir com as ondinhas, ele vai ir como se tivesse encaminhado." O valor exato é o da documentação, e é 512 KB para o ícone de tocar.

Na prática: se o seu produto gera áudio com voz sintetizada e você quer que pareça gravado na hora, converta para Opus em ogg e vigie o tamanho. Um minuto de fala em Opus cabe com folga em 512 KB.

Vídeo e figurinha

Vídeo segue exatamente a mesma lógica, com type: "video" e objeto video, aceitando link ou id e caption. Figurinha usa type: "sticker", sem legenda, e o formato é webp.

Formatos e tetos, todos da Meta:

A janela de 24 horas vale para mídia também

Aqui está a regra que decide se o seu envio chega ou não. Mídia enviada sem template é mensagem de serviço, e mensagem de serviço só sai dentro da janela de 24 horas, que é aberta pela mensagem do cliente.

O terceiro e o quarto item são os que mais surpreendem. Quem renova a janela é sempre o cliente, e a resposta HTTP 200 não é garantia de nada: o failed chega depois, com o motivo. Como enviar template com mídia no cabeçalho está aqui.

Sobre custo, vale a mesma regra de qualquer mensagem: a Meta cobra por mensagem entregue, pela categoria e pelo país do destinatário. Mídia dentro da janela é serviço, e a partir de 1º de outubro de 2026 cada número passa a ter 1.000 mensagens de serviço gratuitas por mês, com cobrança a partir da milésima primeira, na faixa de R$ 0,035 no Brasil. Enviar uma imagem em vez de um texto não muda essa conta: o que conta é a categoria da mensagem, não o formato.

O que muda com a Datafy

Não muda: formato, tamanho, marcação de voz, janela de 24 horas e cobrança são regras da Meta.

Muda onde hospedar. A aba de mídias do painel dá o link do arquivo sem você subir infraestrutura, por 30 dias.

Muda o esforço de montar o corpo. Os exemplos separados por tipo, com test request na própria tela, tiram a etapa de descobrir qual campo cada formato aceita.

Muda o recebimento, que é o lado mais trabalhoso: a mídia que o cliente manda chega criptografada, e uma chamada devolve a URL pronta. Como receber está aqui.

Perguntas frequentes

Link ou identificador: qual é melhor?

Os dois funcionam no mesmo endpoint. Link é uma requisição só e serve para arquivo já publicado. Identificador vale a pena quando o mesmo arquivo vai para muita gente, porque você sobe uma vez e reaproveita por 30 dias.

Meu áudio não chega com onda sonora. O que está errado?

Confira as duas condições da Meta: arquivo .ogg com codec Opus e "voice": true no corpo. Depois confira o tamanho, porque acima de 512 KB o ícone de tocar vira ícone de download.

Posso enviar mídia para quem nunca falou comigo?

Não como mensagem de serviço. Fora da janela de 24 horas só sai template aprovado, e nesse caso a mídia vai no cabeçalho do template.

Quanto tempo vale o identificador que eu subo?

30 dias, segundo a documentação da Meta. Passado o prazo, o envio com aquele id falha e é preciso subir o arquivo de novo.

Qual o tamanho máximo de cada tipo?

Imagem 5 MB, áudio 16 MB, vídeo 16 MB, documento 100 MB e figurinha 500 KB.

O upload tem limite de requisições?

Tem, e é diferente do envio: 60 requisições por minuto no upload de mídia, contra 500 por minuto no envio de mensagens. Excedeu, a resposta é 429, com a indicação de quantos segundos aguardar.

Onde hospedo o arquivo se eu não tenho servidor?

Na aba de mídias do painel. Você sobe o arquivo, copia o link e usa no corpo do envio. O arquivo fica disponível por 30 dias.

Resumo para a sua integração

Comece pelo caminho mais curto: GET /me para pegar o phone_number_id, uma mensagem sua do celular para abrir a janela, e um envio de imagem por link com legenda. Isso prova a rota inteira em duas chamadas.

Depois separe os casos. Para arquivo que você já publica, fique no link. Para catálogo repetido ou arquivo gerado na hora, use o upload e guarde o id com a data, porque ele vence em 30 dias. Para áudio que precisa parecer gravado na hora, padronize a saída do seu sistema em ogg com Opus e mantenha abaixo de 512 KB.

Por último, trate o retorno com honestidade no seu código: guarde o wamid que voltou e espere o webhook de status. É o único lugar onde você descobre que a mídia realmente chegou.

Leia também

• Como receber mídia na API oficial do WhatsApp
• A primeira mensagem na API oficial do WhatsApp
• Como enviar template pela API
• Como a Datafy API funciona: um espelho da Cloud API