Como enviar imagem, áudio, vídeo e documento pela API de WhatsApp

Por que mídia muda o resultado da conversa

Um boleto em PDF resolve mais do que um link para ele. A foto do produto vende melhor que a descrição. Um áudio curto do vendedor soa mais próximo que três parágrafos. Em sistemas de gestão, o comprovante que o cliente fotografa e manda de volta precisa chegar ao financeiro sem ninguém baixar e subir arquivo na mão.

Uma API de WhatsApp trata os dois sentidos: seu sistema anexa arquivos nas mensagens que envia e recebe os arquivos que os clientes mandam, já prontos para salvar ou processar.

Endpoints de envio por tipo de mídia

Todas as rotas ficam em https://api.d-api.cloud/api/v1 e exigem sessionId e to, com o número no formato internacional sem sinal de mais, como 5511999999999.

Exemplos de envio

Documento com nome amigável

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": "financeiro",
    "to": "5511999999999",
    "document": "https://arquivos.suaempresa.com/faturas/8812.pdf",
    "fileName": "fatura-setembro.pdf",
    "mimetype": "application/pdf"
  }'

Sem fileName, o cliente vê um nome genérico e desconfia. É um detalhe pequeno que reduz a pergunta "isso é golpe?" no atendimento.

Imagem, voz e álbum com o SDK de Node

import { DApi } from 'd-api-sdk'

const dapi = new DApi({ apiKey: process.env.DAPI_KEY })

await dapi.messages.sendImage({
  sessionId: 'loja',
  to: '5511999999999',
  image: 'https://cdn.suaempresa.com/produtos/tenis-azul.jpg',
  caption: 'Chegou no seu tamanho. Quer que eu separe?',
})

await dapi.messages.sendAudio({
  sessionId: 'loja',
  to: '5511999999999',
  audio: 'https://cdn.suaempresa.com/audios/boas-vindas.ogg',
  ptt: true,
})

await dapi.messages.sendAlbum({
  sessionId: 'loja',
  to: '5511999999999',
  media: [
    { type: 'image', url: 'https://cdn.suaempresa.com/produtos/frente.jpg', caption: 'Frente' },
    { type: 'image', url: 'https://cdn.suaempresa.com/produtos/lateral.jpg', caption: 'Lateral' },
  ],
})

O SDK é um cliente fino sobre a mesma API REST, então tudo acima também funciona com qualquer cliente HTTP. Mais detalhes na página do SDK de Node.js.

URL pública ou base64: como decidir

Nos envios individuais, o campo do arquivo aceita dois formatos, e cada um tem seu lugar. No álbum, os itens vão sempre por URL.

• URL pública: o arquivo fica num storage ou CDN e você passa o link. A requisição fica leve, o mesmo arquivo serve para vários destinatários e você não trafega megabytes a cada chamada. O link precisa responder sem login e sem redirecionar para uma página de autenticação.
• Base64: o conteúdo vai dentro do JSON. Faz sentido para arquivos gerados na hora, como um recibo montado pelo sistema, ou quando o documento tem dado sensível e você não quer deixá-lo num link acessível. O custo é um payload maior.

Se optar por URL com dado sensível, use links assinados com expiração curta. A API só precisa buscar o arquivo no momento do envio.

Receber e baixar a mídia que o cliente envia

Quando o cliente manda foto, áudio ou documento, o evento messages.received chega no seu webhook com type igual a image, audio, video, document ou sticker. O media_url normalmente já traz um link do arquivo armazenado, e media_data traz tipo, tamanho, legenda, duração e, em áudio, se é mensagem de voz.

Se você precisa do conteúdo em base64 (para mandar a um OCR ou a um modelo de transcrição, por exemplo) ou o link não veio preenchido, use o download. O WhatsApp entrega a mídia criptografada, e o endpoint decifra usando os metadados que vieram no evento:

curl -X POST https://api.d-api.cloud/api/v1/media/download \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "financeiro",
    "direct_path": "<do webhook>",
    "media_key": "<do webhook>",
    "mimetype": "image/jpeg",
    "base64": true
  }'

Sem base64: true, o arquivo é salvo em storage e a resposta devolve media_url. Para arquivos grandes, o parâmetro async faz o download em segundo plano. Quem quer guardar tudo no próprio bucket pode usar a integração nativa com S3 ou MinIO.

Erros comuns ao enviar mídia

• Link que exige login ou expira rápido demais: o envio falha ou chega vazio. Teste a URL numa aba anônima.
• Áudio sem ptt quando a ideia era parecer voz: o cliente recebe um arquivo, não um recado.
• Mandar a mesma mídia pesada em lote para muita gente: além do custo de banda, volume atípico de envio é um dos sinais que levam a bloqueio. Leia como evitar banimento antes de automatizar campanhas.
• Processar a mídia antes de responder o webhook: baixe e trate o arquivo num worker, depois de devolver 200.

Se você quer disparar mídia a partir de gatilhos do seu sistema sem escrever código, veja a API de WhatsApp para automação. Para combinar mídia com opções clicáveis, continue em botões e listas.