API Documentation

WhatsApp API reference

MessagesChatGroupsConnectionWebhooksn8n ExamplesBest Practices

Send messages, manage chats, and control your WhatsApp number. Find your Base URL, Number ID, and API Key on your dashboard.

Header for all requests
apikey: YOUR_API_KEY

Messages

All message endpoints follow the pattern POST /message/{type}/{numberID}

Chat Operations

Groups

To message a group, use any send endpoint with the group JID as the number (e.g. [email protected]).

Connection Management

Reconnect flow
  1. Call getQR to get a QR code. Display it for the user to scan
  2. Poll connectionState until it returns open, or listen for the connection.update webhook

Your API key stays the same after reconnecting.

Webhooks

Set a webhook URL on your dashboard to receive incoming messages and status changes. Events are forwarded as POST requests to your URL.

Webhook payload format
{
  "event": "messages.upsert",
  "instance": "your-number-id",
  "data": {
    "key": {
      "remoteJid": "[email protected]",
      "fromMe": false,
      "id": "3EB0A0..."
    },
    "message": {
      "conversation": "Hey, is this available?"
    },
    "messageTimestamp": "1709312400"
  },
  "timestamp": "2026-03-02T10:00:00.000Z"
}
Events
messages.upsert New incoming or outgoing message
connection.update Number connected, disconnected, or reconnecting
qrcode.updated New QR code generated for reconnection

To get the sender phone number: take data.key.remoteJid and strip @s.whatsapp.net.

n8n Examples

The most common setup is an n8n workflow with a Webhook trigger node and an HTTP Request node.

Receive messages in n8n
  1. Add a Webhook node, copy the production URL
  2. Paste that URL in your WhatsApp dashboard under Webhook
  3. Incoming messages now trigger your n8n workflow

Message text is in $json.data.message.conversation. Sender is in $json.data.key.remoteJid.

Send a reply from n8n

Add an HTTP Request node after your logic:

Method: POST
URL: YOUR_SERVER_URL/message/sendText/YOUR_NUMBER_ID

Headers:
  apikey: YOUR_API_KEY
  Content-Type: application/json

Body:
{
  "number": "{{ $json.data.key.remoteJid.replace('@s.whatsapp.net', '') }}",
  "text": "Thanks for your message! We'll get back to you soon."
}
AI chatbot (with Claude/GPT)

Webhook, AI node, HTTP Request. 3 nodes for a full WhatsApp AI chatbot.

AI node input (extract message)
Message: {{ $json.data.message.conversation }}
Sender: {{ $json.data.key.remoteJid.replace('@s.whatsapp.net', '') }}
HTTP Request node (send AI reply)
Method: POST
URL: YOUR_SERVER_URL/message/sendText/YOUR_NUMBER_ID

Headers:
  apikey: YOUR_API_KEY
  Content-Type: application/json

Body:
{
  "number": "{{ $json.data.key.remoteJid.replace('@s.whatsapp.net', '') }}",
  "text": "{{ $json.output }}"
}

Best Practices

Rate limits

WhatsApp enforces its own rate limits. New numbers can send around 250 messages per day. Send with 1-2 second delays between messages.

Avoid bans

Don't send unsolicited bulk messages to numbers that haven't messaged you first. Reply-based flows (chatbots, support) are safe. Cold outreach to strangers is the #1 ban reason.

Warm up new numbers

Start with low volume (10-20 messages/day) for the first week. Gradually increase. Numbers with existing chat history get more lenient limits.

Use a dedicated number

Don't use your personal number. Get a separate SIM or virtual number. If something goes wrong, your personal WhatsApp stays safe.

Check numbers before sending

Use the checkNumbers endpoint to verify a number is on WhatsApp before sending.

Phone number format

Full international format without + or spaces: 1234567890 (US), 5511999999999 (Brazil). No dashes, no parentheses.