Enviar mensagem de WhatsApp por API com curl: exemplos prontos

Uma conta no ZapZap, uma instância conectada por QR code, a chave e o segredo da API (no painel, em Configurações e API) e o ID da instância. A autenticação usa só dois cabeçalhos, sem OAuth. Guarde as três informações em variáveis de ambiente para não colar segredo em comando nem deixar no histórico do terminal.

O teste do segundo comando devolve só o código HTTP: 200 indica que a chave e o segredo estão certos; 401 indica que um deles está errado.

# Keep credentials out of the command and out of the shell history
export ZAPZAP_INSTANCE="your-instance-id"
export ZAPZAP_API_KEY="your-api-key"
export ZAPZAP_API_SECRET="your-api-secret"

# Quick check: a 401 here means key or secret is wrong, not the instance
curl -s -o /dev/null -w "%{http_code}\n" "https://api.zapzapapi.com/api/v1/account" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"

O número vai com DDI e só dígitos, sem +, espaços ou traços: 5511999999999 para um celular de São Paulo. O corpo mínimo tem number e text. A resposta síncrona traz o messageId e o status, que guardam o rastro da mensagem no seu sistema.

Por padrão, a API exibe o 'digitando...' proporcional ao tamanho do texto antes de enviar, o que humaniza o envio. Se precisar de resposta mais rápida, envie digitando como false; para atrasar o envio em milissegundos, use delay.

curl -X POST "https://api.zapzapapi.com/api/v1/$ZAPZAP_INSTANCE/send/text" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" \
  -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"number":"5511999999999","text":"Hello! Your order left for delivery."}'
# Expected answer: {"messageId":"ABCDEF123456","status":"sent"}

O endpoint /send/media recebe o tipo (image, video, audio, document, sticker e outros) e a URL pública do arquivo no campo file. Em imagem e vídeo, o campo text vira legenda. Em documento, docName é obrigatório e vira o nome do arquivo que o cliente vê.

Se a URL não for pública, o envio falha: o arquivo precisa estar acessível sem login. Para arquivos privados, gere um link temporário assinado no seu storage.

# Image with caption (the file must be a public URL)
curl -X POST "https://api.zapzapapi.com/api/v1/$ZAPZAP_INSTANCE/send/media" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"number":"5511999999999","type":"image","file":"https://example.com/promo.jpg","text":"This week offer"}'

# PDF: type document, and docName is required
curl -X POST "https://api.zapzapapi.com/api/v1/$ZAPZAP_INSTANCE/send/media" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"number":"5511999999999","type":"document","file":"https://example.com/quote.pdf","docName":"quote.pdf"}'

Enviar é metade do caminho. Registre uma URL HTTPS pública no endpoint de webhook da instância e a API passa a fazer POST nela a cada evento, como mensagem recebida e mudança de status. Use excludeMessages para não receber de volta as mensagens que você mesmo enviou.

Durante o desenvolvimento, uma URL local não recebe nada. Veja por que o webhook não chega no localhost e, para produção, idempotência e retry no webhook.

# Receive replies: register your HTTPS URL on the instance
curl -X PUT "https://api.zapzapapi.com/api/v1/instances/$ZAPZAP_INSTANCE/webhook" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"webhook_url":"https://yoursite.com/webhook","events":"messages,status","excludeMessages":true}'

O script abaixo lê um CSV (número e nome) e manda uma mensagem por vez, com pausa aleatória de 8 a 20 segundos entre elas. Nunca em paralelo. É o padrão de menor risco para uma lista de quem já pediu para receber, e serve para lembrete e confirmação, não para campanha fria.

Nenhum intervalo elimina o risco de bloqueio, porque a ZapZap usa um canal não oficial. Para volumes maiores, leia o guia de disparo em massa e o de anti-bloqueio.

# Small list, human pace: one message every 8 to 20 seconds, never in parallel
while IFS=, read -r number name; do
  curl -s -X POST "https://api.zapzapapi.com/api/v1/$ZAPZAP_INSTANCE/send/text" \
    -H "Content-Type: application/json" \
    -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
    -d "{\"number\":\"$number\",\"text\":\"Hi $name, your appointment is tomorrow. Reply 1 to confirm.\"}" \
    -w " -> HTTP %{http_code}\n"
  sleep $(( (RANDOM % 13) + 8 ))
done < contacts.csv

401: chave ou segredo errados, ou cabeçalho com nome trocado. 404: o ID da instância está errado ou foi colado duas vezes na URL. 400: corpo inválido, como number com letras ou campo obrigatório ausente. 429 e 5xx: erro transitório, vale tentar de novo com espera crescente; 400, 401 e 403 não melhoram repetindo.

Se a API respondeu 'sent' e o cliente não recebeu, o problema costuma estar depois do envio. Veja WhatsApp enviado e cliente não recebe. A referência completa de campos está em enviar mensagem e em referência da API.