API documentation
Everything you need to send WhatsApp messages from your systems.
Getting started
- Create your account and link your WhatsApp in My numbers.
- In API keys, create a key. Keep it safe: it is shown only once.
- 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
| Parameter | Required | Description |
|---|---|---|
apikey | Yes | Your key. In the REST API it goes in the Authorization: Bearer header. |
phone or to | No | Recipient. Without it, the message goes to your own number: ideal for internal alerts. recipient is also accepted. |
group | No | ID of a WhatsApp group instead of a number. See Groups. |
from | No | Sender number if you have several: its ID, its name or the number. Without it, the main one is used. |
text | Yes, unless sending a file | Message text, up to 4,000 characters. Supports emojis and WhatsApp formatting: *bold*, _italic_. |
file | No | Public link to an image, PDF, video or audio. The text is sent as the caption. |
format | No | With json, the simple link answers in JSON instead of text. |
lang | No | Language 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}
| Code | Meaning | What to do |
|---|---|---|
| 400 | Missing text, invalid number or unknown sender | Check the parameters |
| 401 | Wrong or deleted key | Create a new key in your dashboard |
| 402 | The free trial has ended | Choose a plan in your dashboard |
| 403 | Account disabled, or a bot key used for another recipient | Contact support |
| 429 | Too many requests per minute or daily limit reached | Wait, 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
- Messages per day: according to your plan. You can see it on your dashboard home.
- Requests: up to 30 per minute per key.
- Messages from the same number are a few seconds apart so WhatsApp does not treat them as spam.
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'})