Send a WhatsApp message via API with curl: ready examples

A ZapZap account, an instance connected with a QR code, the API key and secret (in the dashboard, under Settings and API) and the instance ID. Authentication uses only two headers, with no OAuth. Keep the three values in environment variables so you do not paste secrets into commands or leave them in the terminal history.

The second command prints only the HTTP code: 200 means the key and secret are right; 401 means one of them is wrong.

# 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"

The number goes with country code and digits only, with no +, spaces or dashes: 5511999999999 for a mobile in Sao Paulo. The minimum body has number and text. The synchronous answer carries messageId and status, which keep the trail of the message in your system.

By default, the API shows 'typing...' proportional to the text length before sending, which humanizes the send. If you need a faster answer, send digitando as false; to delay the send in milliseconds, 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"}

The /send/media endpoint takes the type (image, video, audio, document, sticker and others) and the public URL of the file in the file field. For image and video, the text field becomes the caption. For documents, docName is required and becomes the file name the customer sees.

If the URL is not public, the send fails: the file must be reachable without a login. For private files, generate a temporary signed link in your 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"}'

Sending is half the way. Register a public HTTPS URL on the instance webhook endpoint and the API starts POSTing to it on each event, such as a received message and a status change. Use excludeMessages so you do not get back the messages you sent yourself.

During development, a local URL receives nothing. See why the webhook does not reach localhost and, for production, idempotency and retry on the 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}'

The script below reads a CSV (number and name) and sends one message at a time, with a random pause of 8 to 20 seconds between them. Never in parallel. It is the lowest-risk pattern for a list of people who already asked to hear from you, and it suits reminders and confirmations, not cold campaigns.

No interval removes the ban risk, because ZapZap uses an unofficial channel. For larger volumes, read the guides on mass sending and anti-ban.

# 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: wrong key or secret, or a header with a swapped name. 404: the instance ID is wrong or was pasted twice in the URL. 400: invalid body, such as number with letters or a missing required field. 429 and 5xx: transient errors, worth retrying with growing waits; 400, 401 and 403 do not improve by repeating.

If the API answered 'sent' and the customer did not receive it, the problem is usually after the send. See WhatsApp sent but the customer did not receive it. The full field reference is in send message and in the API reference.