Pular para o conteúdo
apiwpp

Como enviar PDF, imagem, áudio e vídeo pelo WhatsApp via API

Envie PDF, imagem, vídeo, áudio, mensagem de voz e figurinha pelo WhatsApp com a API: payload de cada tipo, mimetype, legenda e mídia recebida no webhook.

Equipe apiwpp · 10 min de leitura

Mandar texto pelo WhatsApp a partir do seu sistema é o primeiro passo. Logo depois vem o pedido que todo projeto recebe: anexar o boleto em PDF, mandar a foto do produto, o vídeo de instrução, o áudio de boas-vindas. E aí surgem as dúvidas práticas: o arquivo vai no corpo da requisição ou por link? Qual campo diz que é um documento? Por que o PDF chegou sem nome? Como receber a foto que o cliente mandou de volta?

Na apiwpp, a mídia sempre viaja por URL: você informa onde o arquivo está, e o gateway baixa e entrega no WhatsApp na hora em que a mensagem sai da fila. Não existe upload de arquivo no corpo do envio. Isso simplifica o seu código, mas traz duas regras que valem para qualquer tipo de arquivo: a URL precisa ser https e pública, e precisa continuar válida até o envio acontecer.

Este tutorial mostra o payload de cada tipo (imagem, vídeo, áudio, mensagem de voz, documento e figurinha), os campos que mudam de um para outro, os erros mais comuns e como tratar a mídia que chega no seu webhook.

Como o envio de mídia funciona

Todo envio passa pela mesma rota, POST /connections/{id}/send, com a mesma chave de API (escopo messages:send) e a mesma resposta. A diferença está no conteúdo: em vez do campo message, você manda um objeto media.

Campo de mediaObrigatórioPara que serve
typeSimimage, video, audio, document ou sticker
urlSimEndereço https público do arquivo
mimetypeSó em documentTipo do arquivo, como application/pdf
fileNameNãoNome que o destinatário vê no documento
captionNãoLegenda de imagem, vídeo ou documento
pttNãotrue envia um áudio como mensagem de voz

A requisição não espera o arquivo ser baixado. Ela coloca a mensagem na fila do número e responde 202 na hora, com o job:

{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 3 }

scheduledAt é quando o envio está previsto (unix em milissegundos) e position é o lugar na fila. A fila respeita o ritmo que protege o número (por padrão, 3 envios por minuto, 60 por hora e 200 por dia, com 3 a 8 segundos entre um e outro), então o download do arquivo acontece no momento do envio, não no momento da requisição. Os detalhes do ritmo estão em fila com ritmo anti-bloqueio.

O seu sistema manda só a URL; o gateway baixa o arquivo quando a mensagem sai da fila e entrega no WhatsApp.

Por que a URL precisa ser pública

O gateway baixa o arquivo com segurança: aceita apenas https e recusa endereços privados ou internos, como localhost, IPs de rede interna e endereços de metadados de nuvem. Um link para o seu servidor de homologação atrás da VPN, portanto, não funciona.

Para arquivos que não podem ficar abertos para qualquer pessoa (boletos, notas, contratos), use uma URL assinada do seu armazenamento, como as de S3, R2 ou Google Cloud Storage. Só dê a ela uma validade folgada: se a fila do número estiver cheia, o envio pode acontecer bem depois da requisição, e um link que expira em 60 segundos pode já estar morto quando chegar a vez da mensagem.

Enviar imagem e vídeo

Imagem é o caso mais simples: type, url e, se quiser, uma legenda.

curl -s -X POST "https://api.apiwpp.com/connections/$ID/send" \
  -H "Authorization: Bearer $APIWPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511988887777",
    "media": {
      "type": "image",
      "url": "https://cdn.exemplo.com.br/produtos/tenis-azul.jpg",
      "caption": "Chegou o tamanho 42 que você pediu!"
    },
    "clientRef": "produto-8812-foto"
  }'

Vídeo segue exatamente o mesmo formato, trocando o type:

{
  "to": "5511988887777",
  "media": {
    "type": "video",
    "url": "https://cdn.exemplo.com.br/tutoriais/instalacao.mp4",
    "caption": "Passo a passo da instalação em 2 minutos."
  },
  "clientRef": "pedido-4410-video-instalacao"
}

O to é o número com código do país e DDD, só dígitos. Antes de enviar, o gateway pergunta ao WhatsApp em qual endereço aquele número está registrado, então contas antigas sem o nono dígito também recebem. Um número que não está no WhatsApp falha na hora, sem novas tentativas.

Enviar PDF e outros documentos

Documento é o tipo que mais gera erro, porque tem uma exigência a mais: o mimetype é obrigatório. Sem ele, a resposta é 400 com { "error": "media.mimetype is required for documents" } e nada entra na fila.

{
  "to": "5511988887777",
  "media": {
    "type": "document",
    "url": "https://arquivos.exemplo.com.br/boletos/1234.pdf?assinatura=abc123",
    "mimetype": "application/pdf",
    "fileName": "boleto-pedido-1234.pdf",
    "caption": "Segue o boleto do pedido 1234, com vencimento na sexta."
  },
  "clientRef": "pedido-1234-boleto"
}

Três cuidados que fazem diferença para quem recebe:

  • Sempre mande fileName. Sem ele, o arquivo chega com um nome genérico, e o cliente não encontra o boleto depois na conversa. Inclua a extensão (.pdf, .xlsx, .zip).
  • Use o mimetype certo para o arquivo. Os mais comuns:
Arquivomimetype
PDFapplication/pdf
Planilha Excel (.xlsx)application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Documento Word (.docx)application/vnd.openxmlformats-officedocument.wordprocessingml.document
CSVtext/csv
ZIPapplication/zip
  • Escreva a legenda como mensagem. "Segue o boleto do pedido 1234" explica o anexo para quem vê a notificação no celular; um PDF sozinho, de um número que a pessoa não reconhece, parece suspeito.

Se você envia notas e boletos em volume, o post sobre notificações de pedido para e-commerce mostra como encaixar o PDF no fluxo de confirmação, pagamento e entrega.

Enviar áudio e mensagem de voz

O WhatsApp trata de dois jeitos um arquivo de áudio. Como arquivo de áudio, ele aparece como anexo com um player. Como mensagem de voz, aparece igual a um áudio gravado no próprio aplicativo, com a onda sonora. A diferença é um campo: ptt: true.

{
  "to": "5511988887777",
  "media": {
    "type": "audio",
    "url": "https://cdn.exemplo.com.br/audios/boas-vindas.ogg",
    "ptt": true
  },
  "clientRef": "cliente-771-boas-vindas"
}

Sem ptt (ou com ptt: false), o mesmo arquivo vai como anexo de áudio. Áudio não leva legenda: se precisar de texto junto, mande uma mensagem de texto separada, com um clientRef próprio.

Na prática, mensagens de voz em formato OGG com codec Opus são as que o WhatsApp exibe de forma mais natural, porque é o formato que o próprio aplicativo grava. Se o seu áudio está em MP3 ou WAV, converta antes de publicar, por exemplo com ffmpeg -i entrada.mp3 -c:a libopus saida.ogg.

Figurinhas

Figurinha (sticker) usa só type e url, sem legenda:

{ "to": "5511988887777", "media": { "type": "sticker", "url": "https://cdn.exemplo.com.br/stickers/obrigado.webp" } }

O formato das figurinhas no WhatsApp é WebP, de preferência quadrado. Use com parcimônia: numa conversa de atendimento, uma figurinha de agradecimento cai bem; numa cobrança, não.

O mesmo envio em Node.js e Python

Nos seus sistemas, vale ter uma função única que recebe o tipo, a URL e os campos opcionais. Em Node.js 18 ou mais recente, com o fetch nativo:

// send-media.mjs
const API = 'https://api.apiwpp.com'

export async function sendMedia(connectionId, to, media, clientRef) {
  const response = await fetch(`${API}/connections/${connectionId}/send`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.APIWPP_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ to, media, clientRef }),
  })

  const body = await response.json()
  if (response.status === 429) {
    const wait = response.headers.get('Retry-After')
    throw new Error(`Limite atingido (${body.error}); tente de novo em ${wait} s`)
  }
  if (!response.ok) throw new Error(`Envio recusado: ${response.status} ${body.error}`)
  return body // { jobId, scheduledAt, position }, ou o job original com duplicate: true
}

await sendMedia(process.env.APIWPP_CONNECTION_ID, '5511988887777', {
  type: 'document',
  url: 'https://arquivos.exemplo.com.br/boletos/1234.pdf',
  mimetype: 'application/pdf',
  fileName: 'boleto-pedido-1234.pdf',
  caption: 'Segue o boleto do pedido 1234.',
}, 'pedido-1234-boleto')

Em Python, com requests:

import os
import requests

API = "https://api.apiwpp.com"

def send_media(connection_id: str, to: str, media: dict, client_ref: str) -> dict:
    response = requests.post(
        f"{API}/connections/{connection_id}/send",
        headers={"Authorization": f"Bearer {os.environ['APIWPP_KEY']}"},
        json={"to": to, "media": media, "clientRef": client_ref},
        timeout=15,
    )
    if response.status_code == 429:
        raise RuntimeError(f"Limite atingido; tente de novo em {response.headers.get('Retry-After')} s")
    response.raise_for_status()
    return response.json()

send_media(
    os.environ["APIWPP_CONNECTION_ID"],
    "5511988887777",
    {"type": "image", "url": "https://cdn.exemplo.com.br/produtos/tenis-azul.jpg", "caption": "Seu pedido!"},
    "pedido-1234-foto",
)

O clientRef é o que torna esse código seguro para repetir. Se a rede cair e o seu sistema mandar a mesma requisição de novo, a resposta é 200 com o job original e "duplicate": true, e o cliente não recebe o boleto duas vezes. A chave fica reservada por 7 dias. O tutorial de envio com Node.js detalha os outros erros (400, 401, 403) e o cliente TypeScript gerado da especificação OpenAPI; a página de integração com Python reúne o mesmo para quem usa Flask ou FastAPI.

Quando o arquivo não chega

A resposta 202 só diz que o envio entrou na fila. Se o arquivo não puder ser baixado quando chegar a vez da mensagem (link expirado, endereço interno, servidor fora do ar), o gateway tenta de novo e, esgotadas as tentativas, desiste. Com clientRef, o seu webhook recebe message.send_failed com reason: attempts_exhausted e o mesmo clientRef, e você sabe exatamente qual anexo precisa de um link novo.

Os erros mais comuns e o que fazer:

SintomaCausa provávelO que fazer
400 com media.mimetype is required for documentsdocument sem mimetypeInclua o mimetype do arquivo
400 com Connection not ready (status: close)O número não está conectadoReconecte e acompanhe o evento connection.status
message.send_failed com attempts_exhaustedO arquivo não pôde ser baixado na hora do envioConfira se a URL é https, pública e ainda válida
message.send_failed com not_on_whatsappO número não tem WhatsAppVerifique a base antes com POST /connections/{id}/contacts/check
429 com new_recipient_cap_reachedTeto de destinatários novos em 24 h atingidoEspere o tempo do cabeçalho Retry-After

Quando o envio sai, o message.delivery informa a mudança de status (sent, delivered, read ou failed) com o messageId e o clientRef. O post sobre webhooks do WhatsApp mostra como receber e validar esses eventos.

Localização e templates: outras formas de conteúdo

Nem toda informação precisa de um arquivo. Para indicar onde fica a loja ou o ponto de retirada, mande uma localização, que abre direto no mapa do celular:

{
  "to": "5511988887777",
  "location": { "latitude": -23.5614, "longitude": -46.6559, "name": "Loja Paulista", "address": "Av. Paulista, 1000" }
}

E para mensagens que se repetem com poucos dados diferentes, como "seu pedido saiu para entrega", use um template: crie uma vez com POST /connections/{id}/templates, com variáveis entre chaves duplas, e envie pelo nome.

{ "to": "5511988887777", "template": "pedido_enviado", "variables": { "nome": "Ana", "pedido": "1234" } }

Se faltar alguma variável, a resposta é 400 com a lista em missingVariables. Os templates da apiwpp são mensagens salvas por você, sem aprovação da Meta; veja a diferença em templates de mensagem.

Receber mídia no webhook

O caminho de volta também importa: o cliente responde com a foto do comprovante, o áudio com a dúvida, o PDF assinado. Tudo chega no evento message.incoming, no mesmo envelope dos outros eventos (type, connectionId, tenantId, externalId, timestamp, data). Quando a mensagem traz mídia, data.media vem preenchido:

{
  "type": "message.incoming",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "loja-42",
  "timestamp": "2026-07-08T12:00:00.000Z",
  "data": {
    "jid": "[email protected]",
    "phone": "+5511988887777",
    "body": "Segue o comprovante",
    "timestamp": 1790251200,
    "raw": { "key": { "remoteJid": "[email protected]", "fromMe": false, "id": "IN-IMG-1" } },
    "media": {
      "type": "image",
      "url": "https://…/media/8b1d4e7f-…/IN-IMG-1.jpg?exp=1790337600&sig=…",
      "mimetype": "image/jpeg",
      "fileName": "IN-IMG-1.jpg",
      "fileSize": 48213,
      "expiresAt": 1790337600000
    }
  }
}

data.body traz a legenda (vazia quando a mídia veio sem texto). data.media.url é uma URL assinada e temporária: baixe o arquivo sem credencial, exatamente como veio, antes de expiresAt. Depois disso, ou se o link for alterado, a resposta é 404.

A mídia recebida chega como link assinado e temporário: baixe o arquivo para o seu armazenamento assim que o evento chegar.

Três regras para tratar esse link:

  1. Baixe na hora, não guarde a URL. Grave o arquivo no seu armazenamento e salve o caminho dele, não o link do gateway.
  2. Trate o link como segredo. Até expirar, qualquer pessoa com ele baixa o arquivo: não registre em log nem repasse.
  3. Processe de forma idempotente. A entrega de webhooks é "pelo menos uma vez": o mesmo evento pode chegar duas vezes, então use o identificador da mensagem, que em message.incoming fica em data.raw.key.id, para não baixar nem processar em dobro.

Um exemplo em Node.js, a ser chamado depois de verificar a assinatura HMAC do webhook e responder 2xx (o post de webhooks mostra essa verificação):

import { writeFile } from 'node:fs/promises'
import path from 'node:path'

export async function saveIncomingMedia(event) {
  if (event.type !== 'message.incoming' || !event.data.media) return

  const { url, fileName, expiresAt } = event.data.media
  if (Date.now() > expiresAt) return // o link já expirou

  const response = await fetch(url) // sem cabeçalho de autenticação
  if (!response.ok) throw new Error(`Download falhou: ${response.status}`)

  // O id da mensagem no nome do arquivo: um evento repetido sobrescreve, não duplica
  const id = event.data.raw?.key?.id ?? Date.now()
  const file = Buffer.from(await response.arrayBuffer())
  await writeFile(path.join('uploads', `${event.connectionId}-${id}-${path.basename(fileName)}`), file)
}

Em produção, troque o disco local pelo seu armazenamento de objetos e rode o download numa fila, para responder ao webhook rápido.

Como começar hoje

  1. Crie sua conta na apiwpp e conecte um número pelo QR code: o teste de 7 dias não pede cartão.
  2. Crie uma chave de API com o escopo messages:send e guarde numa variável de ambiente.
  3. Suba um PDF de teste num armazenamento com URL https pública ou assinada, com validade de algumas horas.
  4. Mande o documento com type, url, mimetype, fileName e caption, sempre com um clientRef.
  5. Configure o webhook do projeto, envie uma foto do celular para o número e baixe o arquivo a partir do message.incoming.

Perguntas frequentes

Posso enviar o arquivo direto no corpo da requisição, em base64?

Não. A apiwpp recebe mídia apenas por URL: você informa um endereço https público e o gateway baixa o arquivo na hora do envio. Para arquivos privados, use uma URL assinada do seu armazenamento, com validade suficiente para a mensagem sair da fila.

Por que o meu PDF foi recusado com erro 400?

O tipo document exige o campo mimetype. Sem ele, a resposta é 400 com media.mimetype is required for documents e nada entra na fila. Para PDF, use application/pdf e mande também o fileName com a extensão.

Como mandar um áudio que aparece como mensagem de voz?

Envie type: "audio" com ptt: true. Sem esse campo, o arquivo chega como anexo de áudio com player. Arquivos OGG com codec Opus são os que o WhatsApp exibe de forma mais natural como mensagem de voz.

Não. Por segurança, o gateway recusa endereços privados ou internos e aceita apenas https. O arquivo precisa estar num endereço público, como um CDN ou um bucket com URL assinada.

Como recebo as fotos e os documentos que os clientes enviam?

Pelo evento message.incoming do webhook, no campo data.media, com tipo, mimetype, nome, tamanho e uma URL assinada e temporária. Baixe o arquivo antes de expiresAt, guarde no seu armazenamento e trate o link como segredo.

Enviar mídia custa mais do que enviar texto?

Não. Na apiwpp o preço é por número conectado por mês, e as mensagens são ilimitadas dentro dos limites de ritmo, sejam de texto ou de mídia. Os valores de cada plano estão em preços.


Leia também:

Conecte seu primeiro número hoje.

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