Pular para o conteúdo
apiwpp
Recurso

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

typePara que serveCampos úteis
imageFotos, prints, cardápios, comprovantescaption
videoVídeos curtos, demonstraçõescaption
audioÁudios; com ptt: true, sai como mensagem de vozptt
documentPDF, planilhas, contratos, boletosmimetype (obrigatório), fileName, caption
stickerFigurinhas

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:

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:

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.

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.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.