Developer guide
Send WhatsApp messages and verification codes from your app in four steps. Every example is ready to copy: replace YOUR_TOKEN and the phone number, and it works.
How it works
- Get a tokenAdd a WhatsApp number in the dashboard. You get its API token.
- Scan the QRLink the number from WhatsApp on the phone, like WhatsApp Web.
- Call the APISend messages with the token. We queue and deliver them.
- Get webhooksReplies and delivery updates are POSTed to your server.
https://wagateway.io/api/v1Authorization: Bearer YOUR_TOKENJSON in, JSON out1 Get your API token
- Create an account or log in.
- Open Numbers and click New WhatsApp number. Give it a name (for example "Sales") and save.
- A yellow box shows your API token. It starts with
wai_. Copy it now: it is shown only once.
Keep the token on your server (in .env), never in a website or mobile app: anyone with it can send messages from your number.
2 Connect your WhatsApp number
Right after you save, the dashboard shows a QR code.
- On the phone, open WhatsApp → Settings → Linked devices → Link a device.
- Scan the QR code. The status changes to Connected.
The phone can be offline afterwards: the number stays connected. Use a business number that has been in normal use for a while; brand-new numbers start with a lower daily limit for their first week.
To check the connection from your code, call Get instance status with the instance ID shown on the number's page in the dashboard:
curl https://wagateway.io/api/v1/instances/INSTANCE_ID/status \
-H "Authorization: Bearer YOUR_TOKEN"{
"success": true,
"data": {
"id": "01j9z8k2m3n4p5q6r7s8t9v0wx",
"status": "connected",
"phone": "201001234567",
"quota": { "daily_limit": 1000, "sent_today": 37, "remaining": 963 }
},
"error": null
}3 Send your first message
Send a text with POST /messages/text. The phone number is international, with or without +.
curl -X POST https://wagateway.io/api/v1/messages/text \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"to": "+201001234567", "text": "Hello from my app 👋"}'// Laravel
use Illuminate\Support\Facades\Http;
$response = Http::withToken(env('WA_TOKEN'))
->post('https://wagateway.io/api/v1/messages/text', [
'to' => '+201001234567',
'text' => 'Hello from my app 👋',
]);
$messageId = $response->json('data.message_id');const res = await fetch('https://wagateway.io/api/v1/messages/text', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.WA_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to: '+201001234567', text: 'Hello from my app 👋' }),
});
const { data } = await res.json();
console.log(data.message_id);import os, requests
res = requests.post(
'https://wagateway.io/api/v1/messages/text',
headers={'Authorization': f"Bearer {os.environ['WA_TOKEN']}"},
json={'to': '+201001234567', 'text': 'Hello from my app 👋'},
)
print(res.json()['data']['message_id'])You get 202 Accepted right away:
{
"success": true,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"status": "queued",
"scheduled_at": null
},
"error": null
}Why "queued"? To protect your number from being banned, messages go out one at a time with a short random pause and a "typing…" indicator, like a person. A message usually arrives within seconds. It then moves queued → sent → delivered → read (or failed). You get each change on your webhook (next step), or you can ask with Get a message.
Idempotency-Key header (for example order-1042-shipped). If your request times out and you send it again with the same key, the message is not sent twice.4 Receive messages and delivery updates
Tell us where to POST events: in the dashboard (Numbers → the number → Webhook URL), or by API. Copy the signing secret; you need it to check that a request really comes from us.
curl -X POST https://wagateway.io/api/v1/instances/INSTANCE_ID/webhook \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://your-app.com/wa-webhook", "events": ["message.received", "message.status"]}'When a customer writes to your number, your URL receives:
{
"id": "01J9Z9C4H7K2M5P8R1T4W7Y0B3",
"event": "message.received",
"instance_id": "01j9z8k2m3n4p5q6r7s8t9v0wx",
"data": {
"messageId": "01j9z9c4h7k2m5p8r1t4w7y0b3",
"from": "201001234567",
"senderName": "Ahmed",
"type": "text",
"text": "Hi, is my order ready?"
},
"occurred_at": "2026-10-12T10:20:00.412Z"
}Answer with any 2xx within 10 seconds. If you don't, we retry (after 10 s, 1 min, 5 min, 30 min, 2 h), so the same event can arrive twice: ignore an id you have already handled.
Check the signature
Every webhook has an X-Timestamp header and an X-Signature header = HMAC-SHA256 of timestamp + "." + raw body with your signing secret.
// Laravel route
Route::post('/wa-webhook', function (Illuminate\Http\Request $request) {
$timestamp = $request->header('X-Timestamp');
$expected = hash_hmac('sha256', $timestamp.'.'.$request->getContent(), env('WA_WEBHOOK_SECRET'));
if (! hash_equals($expected, (string) $request->header('X-Signature')) || abs(time() - (int) $timestamp) > 300) {
abort(401);
}
$event = $request->json()->all();
if ($event['event'] === 'message.received') {
// $event['data']['from'], $event['data']['text'] …
}
return response()->noContent();
});// Express: keep the raw body, the signature is over the exact bytes.
app.post('/wa-webhook', express.raw({ type: 'application/json' }), (req, res) => {
const ts = req.get('X-Timestamp') || '';
const expected = crypto.createHmac('sha256', process.env.WA_WEBHOOK_SECRET)
.update(`${ts}.${req.body}`).digest('hex');
const sig = req.get('X-Signature') || '';
const ok = sig.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
&& Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
if (!ok) return res.sendStatus(401);
const event = JSON.parse(req.body);
// event.event === 'message.received' → event.data.from, event.data.text
res.sendStatus(200);
});# Flask
import hmac, hashlib, os, time
from flask import request, abort
@app.post('/wa-webhook')
def wa_webhook():
ts = request.headers.get('X-Timestamp', '')
raw = request.get_data()
expected = hmac.new(os.environ['WA_WEBHOOK_SECRET'].encode(), ts.encode() + b'.' + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get('X-Signature', '')) or abs(time.time() - int(ts or 0)) > 300:
abort(401)
event = request.get_json()
return '', 204Use Send test webhook on the number's page to try your endpoint. All events (reactions, poll votes, connection changes …) are listed in the reference.
Send an OTP code
Verify a user's phone number with a one-time code sent on WhatsApp. We create the code, send it and check it: you only make two calls.
Step 1: send the code
curl -X POST https://wagateway.io/api/v1/otp \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"to": "+201001234567", "brand": "MyApp"}'$otp = Http::withToken(env('WA_TOKEN'))
->post('https://wagateway.io/api/v1/otp', ['to' => '+201001234567', 'brand' => 'MyApp'])
->json('data');
session(['otp_id' => $otp['otp_id']]); // keep it for step 2const res = await fetch('https://wagateway.io/api/v1/otp', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.WA_TOKEN}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ to: '+201001234567', brand: 'MyApp' }),
});
const { data } = await res.json(); // keep data.otp_id for step 2otp = requests.post(
'https://wagateway.io/api/v1/otp',
headers={'Authorization': f"Bearer {os.environ['WA_TOKEN']}"},
json={'to': '+201001234567', 'brand': 'MyApp'},
).json()['data'] # keep otp['otp_id'] for step 2The user receives "MyApp: كود التحقق: 482913 …" (Arabic by default; add "language": "en" for English). You get back an otp_id:
{
"success": true,
"data": {
"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n",
"to": "201001234567",
"expires_at": "2026-11-01T10:05:00Z",
"message_id": "01jb2x4m1a2b3c4d5e6f7g8h9j"
},
"error": null
}Step 2: check what the user typed
curl -X POST https://wagateway.io/api/v1/otp/verify \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n", "code": "482913"}'$result = Http::withToken(env('WA_TOKEN'))
->post('https://wagateway.io/api/v1/otp/verify', ['otp_id' => session('otp_id'), 'code' => $request->input('code')])
->json('data');
if ($result['valid']) {
// phone number verified
}const res = await fetch('https://wagateway.io/api/v1/otp/verify', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.WA_TOKEN}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ otp_id: otpId, code: userInput }),
});
const { data } = await res.json();
if (data.valid) { /* verified */ }result = requests.post(
'https://wagateway.io/api/v1/otp/verify',
headers={'Authorization': f"Bearer {os.environ['WA_TOKEN']}"},
json={'otp_id': otp_id, 'code': user_input},
).json()['data']
if result['valid']:
pass # verifiedThe answer is always 200: check data.valid. When it is false, data.reason tells you why: wrong_code (with attempts_left), expired, too_many_attempts, already_used or not_found.
| Option | What it does |
|---|---|
length | Digits in the code, 4–8 (default 6). |
expires_in | Seconds the code works, 60–1800 (default 300). |
language | ar (default) or en. |
brand | Your app name, shown before the message. |
message | Your own text; must contain {code}. |
link | A "magic link" such as https://your-app.com/login?code={code}, for one-tap login. |
A code works once and allows 5 tries. Per phone number: at most 3 codes in 10 minutes, 30 seconds apart (429 otp_rate_limited with data.retry_after).
Reference: Send a code · Verify a code
Reverse OTP: the user sends the code
Instead of us messaging the user, the user messages your number. It is safer for your number (it never starts a chat), faster for the user (one tap) and counts as half a code.
- Create a code. You get a WhatsApp link with the message already typed.
- Show the link as a button (on mobile) or as a QR code (on desktop).
- The user taps Send in WhatsApp. We match the code and tell you: an
otp.verifiedwebhook, or ask withGET /otp/{id}.
curl -X POST https://wagateway.io/api/v1/otp/reverse \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"brand": "MyApp", "reply": "You are verified ✅"}'{
"success": true,
"data": {
"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n",
"code": "482913",
"text": "MyApp - كود التحقق: 482913",
"link": "https://wa.me/201001234567?text=MyApp%20-%20...",
"expires_at": "2026-11-01T10:05:00Z"
},
"error": null
}Then wait for the webhook (sent to your webhook URL whatever events you picked):
{
"event": "otp.verified",
"data": {
"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n",
"mode": "reverse",
"status": "verified",
"phone": "201001234567",
"verified_at": "2026-11-01T10:01:12Z"
}
}Or poll every 2–3 seconds:
curl https://wagateway.io/api/v1/otp/01jb2x4m0f8a9c3d7e6g5h4k2n \
-H "Authorization: Bearer YOUR_TOKEN"
# → "status": "pending" | "verified" | "expired", and "phone" once verifiedAdd "phone": "+201001234567" to accept the code only from that number. reply is optional: we send it back to the user once their code arrives.
Reference: Create a reverse code · Get a code's status
Everything else you can send
Every send endpoint takes to, answers 202 with a message_id, and accepts send_at (schedule up to 30 days ahead) and reply_to (quote a message).
| To send | Endpoint | Main fields |
|---|---|---|
| Text | POST /messages/text | text |
| Image | POST /messages/image | url, caption |
| Document (PDF …) | POST /messages/document | url, filename, mimetype |
| Video | POST /messages/video | url, caption |
| Audio / voice note | POST /messages/audio | url, voice_note |
| Location | POST /messages/location | latitude, longitude, name |
| Poll | POST /messages/poll | question, options, multiple |
| Reaction (emoji) | POST /messages/{id}/react | emoji |
Media is downloaded by us from a public http(s) URL, up to 16 MB. You can also list messages, download received files, mark messages as read, cancel a scheduled message and check if a number is on WhatsApp.
Laravel package
On Laravel (11–13)? Our package sends WhatsApp messages as Laravel notifications. Packagist · GitHub and full guide
composer require wa-gateway/laravel-notification-channelWA_GATEWAY_URL=https://wagateway.io
WA_GATEWAY_TOKEN=wai_...use WaGateway\NotificationChannel\WaGatewayChannel;
use WaGateway\NotificationChannel\WaGatewayMessage;
class OrderShipped extends Notification
{
public function via(object $notifiable): array
{
return [WaGatewayChannel::class];
}
public function toWaGateway(object $notifiable): WaGatewayMessage
{
return WaGatewayMessage::create("Hi {$notifiable->name}, your order has shipped.");
}
}
// In your User model: where to send
public function routeNotificationForWaGateway(): ?string
{
return $this->phone; // +201001234567
}Errors and limits
Every response has the same shape. On errors, check error.code (not the message):
{
"success": false,
"data": null,
"error": {
"code": "validation_failed",
"message": "The to field is required.",
"fields": { "to": ["The to field is required."] }
}
}| Status | Code | What to do |
|---|---|---|
| 401 | unauthorized | Check the token and the Bearer header. |
| 402 | otp_limit_reached | This month's OTP codes are used up: add an OTP package in Billing. |
| 403 | account_inactive | Renew the subscription in Billing. |
| 409 | instance_not_connected | Reconnect the number (scan the QR again). |
| 422 | validation_failed | Fix the fields listed in error.fields. |
| 423 | new_chat_limit_reached, account_restricted | WhatsApp is not letting the number start new chats for now; existing chats still work. Wait until data.until. |
| 429 | rate_limited | Slow down; retry after the Retry-After header. |
| 503 | engine_unavailable | Temporary: retry in a few seconds. |
Limits: 60 requests per minute per number (30 for OTP, 20 for number checks). Each number also has a daily message limit from your plan; messages over it wait and go out the next day. All codes in the reference.
FAQ
Where is my instance ID?
On the number's page in the dashboard (Numbers → the number), with a copy button. You only need it for the number's own endpoints (status, webhook, settings); sending messages needs only the token.
Can I use several numbers?
Yes, as many as your plan allows. Each number has its own token: use the token of the number that should send.
Do I need to check if a number is on WhatsApp before sending?
No. Every send checks it; a number that is not on WhatsApp ends as failed with the error not_on_whatsapp.
Can I send bulk marketing messages?
No. Message people who expect to hear from you (orders, bookings, codes, support). Bulk messages to strangers get numbers banned by WhatsApp.
Can I create numbers from my own app?
Yes, for platforms that connect numbers for their own customers. Ask us for an account token (wat_); then Create an instance and show its QR code in your app.
Is there a Postman collection?
Yes: download it and import it in Postman, then set the baseUrl and your token. There is also an OpenAPI spec.