WA Gateway Docs

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

  1. Get a tokenAdd a WhatsApp number in the dashboard. You get its API token.
  2. Scan the QRLink the number from WhatsApp on the phone, like WhatsApp Web.
  3. Call the APISend messages with the token. We queue and deliver them.
  4. Get webhooksReplies and delivery updates are POSTed to your server.
Base URLhttps://wagateway.io/api/v1
Auth headerAuthorization: Bearer YOUR_TOKEN
FormatJSON in, JSON out
What is an "instance"? In the API, an instance is one WhatsApp number connected to your account. Each number has its own token, webhook and daily limit. You never pass a "from" number: the token decides which number sends.

1 Get your API token

  1. Create an account or log in.
  2. Open Numbers and click New WhatsApp number. Give it a name (for example "Sales") and save.
  3. 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.

Lost the token? Numbers → open the number → Regenerate API token. The old one stops working right away.

2 Connect your WhatsApp number

Right after you save, the dashboard shows a QR code.

  1. On the phone, open WhatsApp → Settings → Linked devices → Link a device.
  2. 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"

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 👋"}'

You get 202 Accepted right away:

JSON
{
  "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.

Safe retries: add an 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
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:

JSON
{
  "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();
});

Use 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"}'

The user receives "MyApp: كود التحقق: 482913 …" (Arabic by default; add "language": "en" for English). You get back an otp_id:

JSON
{
  "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"}'

The 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.

OptionWhat it does
lengthDigits in the code, 4–8 (default 6).
expires_inSeconds the code works, 60–1800 (default 300).
languagear (default) or en.
brandYour app name, shown before the message.
messageYour own text; must contain {code}.
linkA "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.

  1. Create a code. You get a WhatsApp link with the message already typed.
  2. Show the link as a button (on mobile) or as a QR code (on desktop).
  3. The user taps Send in WhatsApp. We match the code and tell you: an otp.verified webhook, or ask with GET /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 ✅"}'

Then wait for the webhook (sent to your webhook URL whatever events you picked):

JSON
{
  "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
curl https://wagateway.io/api/v1/otp/01jb2x4m0f8a9c3d7e6g5h4k2n \
  -H "Authorization: Bearer YOUR_TOKEN"

# → "status": "pending" | "verified" | "expired", and "phone" once verified

Add "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 sendEndpointMain fields
TextPOST /messages/texttext
ImagePOST /messages/imageurl, caption
Document (PDF …)POST /messages/documenturl, filename, mimetype
VideoPOST /messages/videourl, caption
Audio / voice notePOST /messages/audiourl, voice_note
LocationPOST /messages/locationlatitude, longitude, name
PollPOST /messages/pollquestion, options, multiple
Reaction (emoji)POST /messages/{id}/reactemoji

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

Terminal
composer require wa-gateway/laravel-notification-channel
.env
WA_GATEWAY_URL=https://wagateway.io
WA_GATEWAY_TOKEN=wai_...
PHP
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):

JSON
{
  "success": false,
  "data": null,
  "error": {
    "code": "validation_failed",
    "message": "The to field is required.",
    "fields": { "to": ["The to field is required."] }
  }
}
StatusCodeWhat to do
401unauthorizedCheck the token and the Bearer header.
402otp_limit_reachedThis month's OTP codes are used up: add an OTP package in Billing.
403account_inactiveRenew the subscription in Billing.
409instance_not_connectedReconnect the number (scan the QR again).
422validation_failedFix the fields listed in error.fields.
423new_chat_limit_reached, account_restrictedWhatsApp is not letting the number start new chats for now; existing chats still work. Wait until data.until.
429rate_limitedSlow down; retry after the Retry-After header.
503engine_unavailableTemporary: 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.