Pular para o conteúdo
D-APITestar grátis

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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.