API documentation

Everything you need to send WhatsApp messages from your systems.

Getting started

  1. Create your account and link your WhatsApp in My numbers.
  2. In API keys, create a key. Keep it safe: it is shown only once.
  3. Open this link in your browser, with your key. A message will reach you:
/api/send?text=Hello&apikey=YOUR_KEY

Send a message

There are two equivalent ways. Use whichever suits you.

Simple link (GET or form POST)

/api/send?phone=+447911123456&text=Your%20order%20ships%20today&apikey=YOUR_KEY

Parameters can go in the address or as a form (application/x-www-form-urlencoded). It also answers at /send.php.

REST API (JSON)

POST /api/v1/messages
Authorization: Bearer YOUR_KEY
Content-Type: application/json

{ "to": "+447911123456", "text": "Your order ships today" }

Parameters

ParameterRequiredDescription
apikeyYesYour key. In the REST API it goes in the Authorization: Bearer header.
phone or toNoRecipient. Without it, the message goes to your own number: ideal for internal alerts. recipient is also accepted.
groupNoID of a WhatsApp group instead of a number. See Groups.
fromNoSender number if you have several: its ID, its name or the number. Without it, the main one is used.
textYes, unless sending a fileMessage text, up to 4,000 characters. Supports emojis and WhatsApp formatting: *bold*, _italic_.
fileNoPublic link to an image, PDF, video or audio. The text is sent as the caption.
formatNoWith json, the simple link answers in JSON instead of text.
langNoLanguage of error messages: en, es, pt or fr.

Groups

Available on the Pro plan and above, and during the free trial. Your number must be a member of the group. In the dashboard, My numbers → See groups lists each group with its ID. You can also get them through the API:

GET /api/v1/groups
Authorization: Bearer YOUR_KEY

{"ok":true,"groups":[{"id":"120363012345678901","name":"Sales team","size":6}]}
/api/send?group=120363012345678901&text=Meeting%20at%2010&apikey=YOUR_KEY

In JSON, "to": "[email protected]" also works. Groups are available with numbers linked by QR.

Several numbers

If your account has several numbers, pick the sender with from. It accepts the ID shown in the dashboard, the name you gave it (for example Workshop) or the phone number itself.

/api/send?from=Workshop&phone=+447911123456&text=Your%20device%20is%20ready&apikey=YOUR_KEY

Each number has its own queue: messages from one number do not wait for another.

Images and documents

Add file with a link that can be downloaded without signing in. Maximum 16 MB.

/api/send?phone=+447911123456&text=Delivery%20note%20attached&file=https://drive.google.com/file/d/ID/view&apikey=YOUR_KEY

Google Drive links set to "Anyone with the link" are automatically converted to direct downloads.

API responses

Messages are not sent at request time: they enter a queue and go out in order, a few seconds apart, to protect your number. The response confirms the message is queued.

Simple link:  200  Message queued. id=123
REST API:     202  {"ok":true,"id":123,"status":"queued","to":"447911123456","from":5}
CodeMeaningWhat to do
400Missing text, invalid number or unknown senderCheck the parameters
401Wrong or deleted keyCreate a new key in your dashboard
402The free trial has endedChoose a plan in your dashboard
403Account disabled, or a bot key used for another recipientContact support
429Too many requests per minute or daily limit reachedWait, or upgrade your plan

Message status

GET /api/v1/messages/123
Authorization: Bearer YOUR_KEY

{"ok":true,"message":{"id":123,"status":"sent","attempts":1,"error":null, ...}}

Statuses: queued, sending, sent (delivered to WhatsApp) and failed (not sent, with the reason in error). If a number disconnects, its messages wait and are retried automatically.

Status of your numbers: GET /api/v1/status

Number format

Numbers from any country work. You can write them in international format (+44 7911 123456, 0044…) or in your country's local format (07911 123456). Without a country code, the country of your account is used; you can change it in Settings.

The system knows each country's numbering rules: it removes the leading 0 or national prefix when needed and adds the country code. For example, 06 12 34 56 78 in France becomes +33 6 12 34 56 78, and (11) 98765-4321 in Brazil becomes +55 11 98765 4321.

Limits

Only send messages your recipients expect. Mass messages to people who do not know you can lead WhatsApp to restrict your number.

Receive messages

In Settings you can enter an https:// address in your system. Every message any of your numbers receives will be forwarded like this:

POST https://your-system.com/webhook
Content-Type: application/json
X-Wagate-Signature: HMAC-SHA256 signature of the body

{"event":"message.received","number_id":5,"from":"+447911123456","message":"YES","name":"Luis","group":null,"at":1762440000000}

Examples

Google Apps Script

function sendWhatsApp(phone, text) {
  const r = UrlFetchApp.fetch('/api/send', {
    method: 'post',
    payload: { apikey: 'YOUR_KEY', phone: phone, text: text },
    muteHttpExceptions: true,
  });
  return r.getResponseCode() === 200;
}

AppSheet

Automation, Bot, "Call a webhook" task: URL /api/v1/messages, POST, JSON, header Authorization: Bearer YOUR_KEY and body:

{ "to": "<<[PHONE]>>", "text": "Hi <<[CUSTOMER]>>, your order is ready." }

PHP

file_get_contents('/api/send?' . http_build_query([
  'apikey' => 'YOUR_KEY', 'phone' => '+447911123456', 'text' => 'Hello from PHP',
]));

Python

import requests
requests.post('/api/v1/messages',
  headers={'Authorization': 'Bearer YOUR_KEY'},
  json={'to': '+447911123456', 'text': 'Hello from Python'})