Introduction
Send and receive WhatsApp messages through your own connected number.
The full reference: every endpoint, field and response.
New here?
Start with the developer guide: get your token, connect a number, send your first message, receive webhooks and send OTP codes, with copy-ready examples in cURL, PHP, Node.js and Python. Using Laravel? See the Laravel package.
Instances
An instance is one WhatsApp number connected to your account. Each instance has its own API token, webhook, send queue and daily limit, so one account can run several numbers (as many as your plan allows) without them affecting each other. Every call made with an instance's token acts on that number: there is no "from" field when sending.
Response format
Every response, success or error, has the same envelope:
{ "success": true, "data": { "...": "..." }, "error": null }
{ "success": false, "data": null, "error": { "code": "validation_failed", "message": "...", "fields": { "to": ["..."] } } }
Branch on error.code, not on error.message. Common codes:
| Status | error.code |
Meaning |
|---|---|---|
| 401 | unauthorized |
Missing or wrong token. |
| 402 | otp_limit_reached |
This month's OTP codes are used up (package plus the overage limit). |
| 403 | account_inactive |
The account is suspended or the subscription has ended. |
| 403 | plan_limit_reached |
The plan has no room for another number. |
| 404 | not_found, message_not_found, otp_not_found |
No such resource on this number. |
| 409 | instance_not_connected |
The number is not connected right now. |
| 409 | idempotency_conflict |
A request with the same Idempotency-Key is still being processed. |
| 410 | media_expired |
The file was deleted after the retention period. |
| 422 | validation_failed |
Invalid input; see error.fields. |
| 423 | account_restricted, new_chat_limit_reached |
WhatsApp is not letting this number start new chats for now (see Messages). |
| 429 | rate_limited, otp_rate_limited |
Too many requests; retry after Retry-After (or data.retry_after) seconds. |
| 503 | engine_unavailable |
The WhatsApp service is briefly unavailable; retry. |
Phone numbers
Use international format: +201001234567, 00201001234567 and 201001234567 are all accepted (spaces and dashes are ignored). National formats with a leading 0 are rejected because the country cannot be inferred. Numbers are returned as digits only, without +.
How sending works
Messages are queued per number and sent one at a time, with a random pause between messages and a short "typing…" indicator before text, to behave like a person and protect your number. New numbers (paired less than 7 days ago) have a reduced daily limit that grows each day (50, 100, 200, …). When the daily limit is reached, messages stay queued and go out the next day. If several sends fail in a row, the number is paused (instance.paused webhook) until support resumes it.
Rate limits
| What | Limit |
|---|---|
| Calls with an instance token | 60 per minute per number |
POST /otp and POST /otp/reverse |
30 per minute per number |
POST /contacts/check |
20 per minute per number |
| Calls with an account token | 30 per minute |
Over a limit you get 429 rate_limited with a Retry-After header.
Authenticating requests
To authenticate requests, include an Authorization header with the value "Bearer {INSTANCE_TOKEN}".
All authenticated endpoints are marked with a requires authentication badge in the documentation below.
Send Authorization: Bearer <token>. There are two kinds of token: the instance token (wai_…, one per WhatsApp number, used by every endpoint except one; get it in the dashboard under Numbers) and the account token (wat_…, only for creating instances by API; ask us for one). Tokens are shown once when created; we store only a hash, so a lost token must be regenerated (dashboard → Numbers → edit the number → Regenerate API token).
Instances
An instance is one WhatsApp number connected to your account. Create it, pair it by scanning the QR code, then use its token for everything else.
Create an instance
requires authentication
Creates a new WhatsApp number slot and starts pairing. Authenticate with your account
token (wat_…), not an instance token. The response contains the instance token
(wai_…) once: store it, it cannot be shown again. Next, poll the QR endpoint.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/instances" \
--header "Authorization: Bearer {ACCOUNT_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"name\": \"Sales line\"
}"
const url = new URL(
"https://wagateway.io/api/v1/instances"
);
const headers = {
"Authorization": "Bearer {ACCOUNT_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"name": "Sales line"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/instances';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {ACCOUNT_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'name' => 'Sales line',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/instances'
payload = {
"name": "Sales line"
}
headers = {
'Authorization': 'Bearer {ACCOUNT_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (201, Created):
{
"success": true,
"data": {
"instance": {
"id": "01j9z8k2m3n4p5q6r7s8t9v0wx",
"name": "Sales line",
"status": "pending",
"phone": null,
"webhook_url": null,
"webhook_events": [
"message.received",
"message.status"
],
"connected_at": null,
"last_seen_at": null,
"created_at": "2026-10-12T10:00:00Z"
},
"token": "wai_3f9c1e2b7a6d4c8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c",
"token_notice": "Store this token now; it cannot be shown again."
},
"error": null
}
Example response (401, Missing or wrong account token):
{
"success": false,
"data": null,
"error": {
"code": "unauthorized",
"message": "Missing or invalid account token."
}
}
Example response (403, Plan limit reached):
{
"success": false,
"data": null,
"error": {
"code": "plan_limit_reached",
"message": "Your plan allows 3 numbers. Delete one or upgrade your plan."
}
}
Example response (403, Account suspended or expired):
{
"success": false,
"data": null,
"error": {
"code": "account_inactive",
"message": "Account is suspended or the subscription has expired."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get the pairing QR code
requires authentication
Returns the current QR code as a PNG data URL, ready for an <img src>. Poll every
2–3 seconds: the QR rotates about every 20 seconds and qr is null while a new one
is being generated. Scan it with WhatsApp on the phone (Settings → Linked devices →
Link a device). When status becomes connected, pairing is done and qr stays null.
Example request:
curl --request GET \
--get "https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/qr" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/qr"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/qr';
$response = $client->get(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/qr'
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()Example response (200, Waiting for scan):
{
"success": true,
"data": {
"qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAAB...",
"status": "qr"
},
"error": null
}
Example response (200, Paired):
{
"success": true,
"data": {
"qr": null,
"status": "connected"
},
"error": null
}
Example response (404, Not your instance):
{
"success": false,
"data": null,
"error": {
"code": "not_found",
"message": "Resource not found."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get instance status
requires authentication
status is one of: pending (created, not paired), qr (waiting for scan),
connected, disconnected (temporarily offline, reconnecting automatically),
logged_out (unlinked from the phone; pair again), banned (blocked by WhatsApp),
paused (sending stopped after repeated failures; contact support).
quota is today's sending allowance for this number (UTC day): daily_limit is the
plan limit, lowered during the first 7 days after pairing (warmup); remaining counts
down as messages are sent and resets at resets_at. Messages over the limit stay
queued until then. quota is null if it cannot be read right now.
restrictions shows WhatsApp's own limits on starting new chats: timelock (active,
until, type) and new_chat_cap (status: NONE, FIRST_WARNING, SECOND_WARNING
or CAPPED; used, total, resets_at), checked at checked_at. While one applies,
messages to new contacts are refused with 423 (see Messages); existing chats work.
Example request:
curl --request GET \
--get "https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/status" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/status"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/status';
$response = $client->get(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/status'
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()Example response (200):
{
"success": true,
"data": {
"id": "01j9z8k2m3n4p5q6r7s8t9v0wx",
"name": "Sales line",
"status": "connected",
"phone": "201001234567",
"webhook_url": "https://example.com/wa-webhook",
"webhook_events": [
"message.received",
"message.status"
],
"auto_read": false,
"connected_at": "2026-10-12T10:02:11Z",
"last_seen_at": "2026-10-12T14:30:00Z",
"restrictions": {
"timelock": {
"active": false,
"until": null,
"type": null
},
"new_chat_cap": null,
"checked_at": "2026-10-12T14:00:00Z"
},
"created_at": "2026-10-12T10:00:00Z",
"quota": {
"daily_limit": 200,
"plan_limit": 1000,
"warmup": true,
"sent_today": 37,
"remaining": 163,
"resets_at": "2026-10-13T00:00:00.000Z"
}
},
"error": null
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Log out (unlink the number)
requires authentication
Unlinks this instance from the WhatsApp account, like removing it under Linked devices on the phone. Queued messages are not sent. To use the number again, pair it with a new QR.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/logout" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/logout"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "POST",
headers,
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/logout';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/logout'
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers)
response.json()Example response (200):
{
"success": true,
"data": {
"id": "01j9z8k2m3n4p5q6r7s8t9v0wx",
"name": "Sales line",
"status": "logged_out",
"phone": "201001234567",
"webhook_url": null,
"webhook_events": [
"message.received",
"message.status"
],
"connected_at": null,
"last_seen_at": "2026-10-12T14:31:00Z",
"created_at": "2026-10-12T10:00:00Z"
},
"error": null
}
Example response (503, Service temporarily unavailable):
{
"success": false,
"data": null,
"error": {
"code": "engine_unavailable",
"message": "The WhatsApp service is temporarily unavailable. Please retry."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Update instance settings
requires authentication
auto_read: mark every new incoming message as read (blue ticks for the sender) a few
seconds after it arrives, like a person opening the chat. Off by default; you can also
mark single messages with "Mark a message as read".
Example request:
curl --request POST \
"https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/settings" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"auto_read\": true
}"
const url = new URL(
"https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/settings"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"auto_read": true
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/settings';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'auto_read' => true,
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/settings'
payload = {
"auto_read": true
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (200):
{
"success": true,
"data": {
"id": "01j9z8k2m3n4p5q6r7s8t9v0wx",
"name": "Sales line",
"status": "connected",
"auto_read": true
},
"error": null
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Messages
Safe retries: send an Idempotency-Key header (any unique string up to 255 printable
characters, e.g. order-1042-shipped). If you retry with the same key, you get the original
message back (202, header Idempotent-Replayed: true) and nothing is sent twice. The same
key with a different request returns 422 idempotency_key_reused; while the first request
with that key is still being processed, a repeat gets 409 idempotency_conflict (retry
shortly). Keys are per number.
Sending is asynchronous: a send endpoint validates and queues the message, then answers
202 Accepted with its message_id. The message then moves queued → sent →
delivered → read (or failed), reported on your webhook as message.status and
visible with "Get a message". Media is downloaded by us from the url you give (public
http/https only, max 16 MB).
WhatsApp restrictions: WhatsApp may temporarily stop a number from starting NEW chats
(a "timelock"), or cap how many new chats it can start per period. While that applies, a
message to someone the number has no chat with yet is refused with 423
(account_restricted or new_chat_limit_reached, with data.until); trying anyway would
make the restriction worse. Existing chats keep working, and so do messages scheduled
(send_at) after until. See restrictions in "Get instance status" and the
instance.restriction webhook.
Replies: add reply_to with the message_id of a message in the same chat (one you
received, or sent) and WhatsApp shows it quoted above yours, like swiping to reply.
Send a text message
requires authentication
Plain text, up to 65,536 characters. Whitespace and line breaks are kept as sent.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/messages/text" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Idempotency-Key: order-1042-shipped" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to\": \"+201001234567\",
\"text\": \"Hi Ahmed, your order #1042 has shipped.\\nTrack it: https:\\/\\/example.com\\/t\\/1042\"
}"
const url = new URL(
"https://wagateway.io/api/v1/messages/text"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Idempotency-Key": "order-1042-shipped",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to": "+201001234567",
"text": "Hi Ahmed, your order #1042 has shipped.\nTrack it: https:\/\/example.com\/t\/1042"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/text';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key' => 'order-1042-shipped',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'to' => '+201001234567',
'text' => 'Hi Ahmed, your order #1042 has shipped.'."\n"
.'Track it: https://example.com/t/1042',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/text'
payload = {
"to": "+201001234567",
"text": "Hi Ahmed, your order #1042 has shipped.\nTrack it: https:\/\/example.com\/t\/1042"
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key': 'order-1042-shipped',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (202, Queued):
{
"success": true,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"status": "queued"
},
"error": null
}
Example response (409, Number not paired):
{
"success": false,
"data": null,
"error": {
"code": "instance_not_connected",
"message": "Instance is qr; connect it by scanning the QR code first."
}
}
Example response (422, Invalid input):
{
"success": false,
"data": null,
"error": {
"code": "validation_failed",
"message": "The recipient phone (to) must be an international phone number, e.g. +201001234567.",
"fields": {
"to": [
"The recipient phone (to) must be an international phone number, e.g. +201001234567."
]
}
}
}
Example response (503, Could not queue (retry)):
{
"success": false,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9"
},
"error": {
"code": "engine_unavailable",
"message": "The message could not be queued right now. Please retry."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Send an image
requires authentication
JPEG, PNG or WebP from a public URL, with an optional caption (max 1,024 characters).
Example request:
curl --request POST \
"https://wagateway.io/api/v1/messages/image" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Idempotency-Key: order-1042-shipped" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to\": \"+201001234567\",
\"url\": \"https:\\/\\/cdn.example.com\\/products\\/1042.jpg\",
\"caption\": \"Your order is on its way\"
}"
const url = new URL(
"https://wagateway.io/api/v1/messages/image"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Idempotency-Key": "order-1042-shipped",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to": "+201001234567",
"url": "https:\/\/cdn.example.com\/products\/1042.jpg",
"caption": "Your order is on its way"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/image';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key' => 'order-1042-shipped',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'to' => '+201001234567',
'url' => 'https://cdn.example.com/products/1042.jpg',
'caption' => 'Your order is on its way',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/image'
payload = {
"to": "+201001234567",
"url": "https:\/\/cdn.example.com\/products\/1042.jpg",
"caption": "Your order is on its way"
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key': 'order-1042-shipped',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (202, Queued):
{
"success": true,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"status": "queued"
},
"error": null
}
Example response (409, Number not paired):
{
"success": false,
"data": null,
"error": {
"code": "instance_not_connected",
"message": "Instance is qr; connect it by scanning the QR code first."
}
}
Example response (422, Invalid input):
{
"success": false,
"data": null,
"error": {
"code": "validation_failed",
"message": "The recipient phone (to) must be an international phone number, e.g. +201001234567.",
"fields": {
"to": [
"The recipient phone (to) must be an international phone number, e.g. +201001234567."
]
}
}
}
Example response (503, Could not queue (retry)):
{
"success": false,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9"
},
"error": {
"code": "engine_unavailable",
"message": "The message could not be queued right now. Please retry."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Send a video
requires authentication
MP4 (H.264/AAC) from a public URL, with an optional caption. Max 16 MB.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/messages/video" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Idempotency-Key: order-1042-shipped" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to\": \"+201001234567\",
\"url\": \"https:\\/\\/cdn.example.com\\/videos\\/unboxing.mp4\",
\"caption\": \"How to set it up\"
}"
const url = new URL(
"https://wagateway.io/api/v1/messages/video"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Idempotency-Key": "order-1042-shipped",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to": "+201001234567",
"url": "https:\/\/cdn.example.com\/videos\/unboxing.mp4",
"caption": "How to set it up"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/video';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key' => 'order-1042-shipped',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'to' => '+201001234567',
'url' => 'https://cdn.example.com/videos/unboxing.mp4',
'caption' => 'How to set it up',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/video'
payload = {
"to": "+201001234567",
"url": "https:\/\/cdn.example.com\/videos\/unboxing.mp4",
"caption": "How to set it up"
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key': 'order-1042-shipped',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (202, Queued):
{
"success": true,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"status": "queued"
},
"error": null
}
Example response (409, Number not paired):
{
"success": false,
"data": null,
"error": {
"code": "instance_not_connected",
"message": "Instance is qr; connect it by scanning the QR code first."
}
}
Example response (422, Invalid input):
{
"success": false,
"data": null,
"error": {
"code": "validation_failed",
"message": "The recipient phone (to) must be an international phone number, e.g. +201001234567.",
"fields": {
"to": [
"The recipient phone (to) must be an international phone number, e.g. +201001234567."
]
}
}
}
Example response (503, Could not queue (retry)):
{
"success": false,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9"
},
"error": {
"code": "engine_unavailable",
"message": "The message could not be queued right now. Please retry."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Send audio or a voice note
requires authentication
As an audio file (default), or as a voice note with voice_note: true. Voice notes
must be OGG/Opus to play inline in WhatsApp; MP3 works for audio files.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/messages/audio" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Idempotency-Key: order-1042-shipped" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to\": \"+201001234567\",
\"url\": \"https:\\/\\/cdn.example.com\\/audio\\/welcome.ogg\",
\"voice_note\": true
}"
const url = new URL(
"https://wagateway.io/api/v1/messages/audio"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Idempotency-Key": "order-1042-shipped",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to": "+201001234567",
"url": "https:\/\/cdn.example.com\/audio\/welcome.ogg",
"voice_note": true
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/audio';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key' => 'order-1042-shipped',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'to' => '+201001234567',
'url' => 'https://cdn.example.com/audio/welcome.ogg',
'voice_note' => true,
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/audio'
payload = {
"to": "+201001234567",
"url": "https:\/\/cdn.example.com\/audio\/welcome.ogg",
"voice_note": true
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key': 'order-1042-shipped',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (202, Queued):
{
"success": true,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"status": "queued"
},
"error": null
}
Example response (409, Number not paired):
{
"success": false,
"data": null,
"error": {
"code": "instance_not_connected",
"message": "Instance is qr; connect it by scanning the QR code first."
}
}
Example response (422, Invalid input):
{
"success": false,
"data": null,
"error": {
"code": "validation_failed",
"message": "The recipient phone (to) must be an international phone number, e.g. +201001234567.",
"fields": {
"to": [
"The recipient phone (to) must be an international phone number, e.g. +201001234567."
]
}
}
}
Example response (503, Could not queue (retry)):
{
"success": false,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9"
},
"error": {
"code": "engine_unavailable",
"message": "The message could not be queued right now. Please retry."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Send a document
requires authentication
Any file (PDF, DOCX, XLSX, ZIP, …) from a public URL. filename is what the recipient
sees; mimetype must match the file.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/messages/document" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Idempotency-Key: order-1042-shipped" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to\": \"+201001234567\",
\"url\": \"https:\\/\\/cdn.example.com\\/invoices\\/1042.pdf\",
\"filename\": \"Invoice-1042.pdf\",
\"mimetype\": \"application\\/pdf\",
\"caption\": \"Your invoice for October\"
}"
const url = new URL(
"https://wagateway.io/api/v1/messages/document"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Idempotency-Key": "order-1042-shipped",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to": "+201001234567",
"url": "https:\/\/cdn.example.com\/invoices\/1042.pdf",
"filename": "Invoice-1042.pdf",
"mimetype": "application\/pdf",
"caption": "Your invoice for October"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/document';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key' => 'order-1042-shipped',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'to' => '+201001234567',
'url' => 'https://cdn.example.com/invoices/1042.pdf',
'filename' => 'Invoice-1042.pdf',
'mimetype' => 'application/pdf',
'caption' => 'Your invoice for October',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/document'
payload = {
"to": "+201001234567",
"url": "https:\/\/cdn.example.com\/invoices\/1042.pdf",
"filename": "Invoice-1042.pdf",
"mimetype": "application\/pdf",
"caption": "Your invoice for October"
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key': 'order-1042-shipped',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (202, Queued):
{
"success": true,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"status": "queued"
},
"error": null
}
Example response (409, Number not paired):
{
"success": false,
"data": null,
"error": {
"code": "instance_not_connected",
"message": "Instance is qr; connect it by scanning the QR code first."
}
}
Example response (422, Invalid input):
{
"success": false,
"data": null,
"error": {
"code": "validation_failed",
"message": "The recipient phone (to) must be an international phone number, e.g. +201001234567.",
"fields": {
"to": [
"The recipient phone (to) must be an international phone number, e.g. +201001234567."
]
}
}
}
Example response (503, Could not queue (retry)):
{
"success": false,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9"
},
"error": {
"code": "engine_unavailable",
"message": "The message could not be queued right now. Please retry."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Send a location
requires authentication
A map pin with optional name and address.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/messages/location" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Idempotency-Key: order-1042-shipped" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to\": \"+201001234567\",
\"lat\": 30.0444,
\"lng\": 31.2357,
\"name\": \"Cairo Store\",
\"address\": \"12 Tahrir Square, Cairo\"
}"
const url = new URL(
"https://wagateway.io/api/v1/messages/location"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Idempotency-Key": "order-1042-shipped",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to": "+201001234567",
"lat": 30.0444,
"lng": 31.2357,
"name": "Cairo Store",
"address": "12 Tahrir Square, Cairo"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/location';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key' => 'order-1042-shipped',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'to' => '+201001234567',
'lat' => 30.0444,
'lng' => 31.2357,
'name' => 'Cairo Store',
'address' => '12 Tahrir Square, Cairo',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/location'
payload = {
"to": "+201001234567",
"lat": 30.0444,
"lng": 31.2357,
"name": "Cairo Store",
"address": "12 Tahrir Square, Cairo"
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key': 'order-1042-shipped',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (202, Queued):
{
"success": true,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"status": "queued"
},
"error": null
}
Example response (409, Number not paired):
{
"success": false,
"data": null,
"error": {
"code": "instance_not_connected",
"message": "Instance is qr; connect it by scanning the QR code first."
}
}
Example response (422, Invalid input):
{
"success": false,
"data": null,
"error": {
"code": "validation_failed",
"message": "The recipient phone (to) must be an international phone number, e.g. +201001234567.",
"fields": {
"to": [
"The recipient phone (to) must be an international phone number, e.g. +201001234567."
]
}
}
}
Example response (503, Could not queue (retry)):
{
"success": false,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9"
},
"error": {
"code": "engine_unavailable",
"message": "The message could not be queued right now. Please retry."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Send a poll
requires authentication
A question with 2–12 answers, one choice or several (multiple). Votes come back on
your webhook as message.poll_vote (the voter's current choice; an empty selected
means they removed their vote), and the totals are in "Get a message"
(content.votes: one {from, selected, at} per voter).
Example request:
curl --request POST \
"https://wagateway.io/api/v1/messages/poll" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Idempotency-Key: restock-poll-2026-11" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to\": \"+201001234567\",
\"question\": \"Which scent should we restock first?\",
\"options\": [
\"b\"
],
\"multiple\": false
}"
const url = new URL(
"https://wagateway.io/api/v1/messages/poll"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Idempotency-Key": "restock-poll-2026-11",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to": "+201001234567",
"question": "Which scent should we restock first?",
"options": [
"b"
],
"multiple": false
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/poll';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key' => 'restock-poll-2026-11',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'to' => '+201001234567',
'question' => 'Which scent should we restock first?',
'options' => ['b'],
'multiple' => false,
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/poll'
payload = {
"to": "+201001234567",
"question": "Which scent should we restock first?",
"options": [
"b"
],
"multiple": false
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Idempotency-Key': 'restock-poll-2026-11',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (202, Queued):
{
"success": true,
"data": {
"message_id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"status": "queued"
},
"error": null
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
List messages
requires authentication
Sent and received messages of this instance, newest first, paginated.
Example request:
curl --request GET \
--get "https://wagateway.io/api/v1/messages?status=failed&direction=out&from=2026-10-01&to=2026-10-12T23%3A59%3A59Z&per_page=20&page=1" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://wagateway.io/api/v1/messages"
);
const params = {
"status": "failed",
"direction": "out",
"from": "2026-10-01",
"to": "2026-10-12T23:59:59Z",
"per_page": "20",
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages';
$response = $client->get(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'status' => 'failed',
'direction' => 'out',
'from' => '2026-10-01',
'to' => '2026-10-12T23:59:59Z',
'per_page' => '20',
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages'
params = {
'status': 'failed',
'direction': 'out',
'from': '2026-10-01',
'to': '2026-10-12T23:59:59Z',
'per_page': '20',
'page': '1',
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()Example response (200):
{
"success": true,
"data": {
"items": [
{
"id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"instance_id": "01j9z8k2m3n4p5q6r7s8t9v0wx",
"direction": "out",
"phone": "201001234567",
"type": "text",
"content": {
"text": "Your order #1042 has shipped."
},
"status": "read",
"error": null,
"wa_message_id": "3EB0C1D2E3F4A5B6C7D8",
"sent_at": "2026-10-12T10:05:03Z",
"delivered_at": "2026-10-12T10:05:04Z",
"read_at": "2026-10-12T10:07:40Z",
"created_at": "2026-10-12T10:05:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 1,
"last_page": 1
}
},
"error": null
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get a message
requires authentication
direction is out (sent by you) or in (received). Incoming media messages include
content.media with id, mime, size and file_name; content.media.error is set
if the file could not be stored (too_large, download_failed). Failed outgoing
messages have an error code, e.g. not_on_whatsapp, invalid_payload,
media_url_blocked, media_too_large, media_http_error, send_failed.
Example request:
curl --request GET \
--get "https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9';
$response = $client->get(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9'
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()Example response (200, Outgoing, read):
{
"success": true,
"data": {
"id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"instance_id": "01j9z8k2m3n4p5q6r7s8t9v0wx",
"direction": "out",
"phone": "201001234567",
"type": "text",
"content": {
"text": "Your order #1042 has shipped."
},
"status": "read",
"error": null,
"wa_message_id": "3EB0C1D2E3F4A5B6C7D8",
"sent_at": "2026-10-12T10:05:03Z",
"delivered_at": "2026-10-12T10:05:04Z",
"read_at": "2026-10-12T10:07:40Z",
"created_at": "2026-10-12T10:05:00Z"
},
"error": null
}
Example response (404, Unknown or other instance's message):
{
"success": false,
"data": null,
"error": {
"code": "not_found",
"message": "Resource not found."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Download received media
requires authentication
The file of an incoming image, video, audio or document message (the mediaId in the
message.received webhook is the message id). Returns the raw file with its
Content-Type, not JSON. Files are kept for 30 days, then this returns
410 media_expired: download what you need to keep.
Example request:
curl --request GET \
--get "https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/media" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/media"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/media';
$response = $client->get(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/media'
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()Example response (200, The file (binary)):
<binary file, e.g. Content-Type: image/jpeg>
Example response (404, No media / not your message):
{
"success": false,
"data": null,
"error": {
"code": "media_not_found",
"message": "This message has no stored media."
}
}
Example response (410, Deleted by retention):
{
"success": false,
"data": null,
"error": {
"code": "media_expired",
"message": "The file was deleted under the retention policy."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Cancel a message
requires authentication
Cancels an outgoing message that has not been sent yet: a scheduled one (send_at) or
one still waiting in the queue. Its status becomes cancelled. Messages already sent
cannot be recalled.
Example request:
curl --request DELETE \
"https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "DELETE",
headers,
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9';
$response = $client->delete(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9'
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('DELETE', url, headers=headers)
response.json()Example response (200):
{
"success": true,
"data": {
"id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"status": "cancelled",
"scheduled_at": "2026-10-20T09:00:00Z"
},
"error": null
}
Example response (409, Already sent):
{
"success": false,
"data": null,
"error": {
"code": "message_not_cancellable",
"message": "Only queued outgoing messages can be cancelled; this one is delivered."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Mark a message as read
requires authentication
Sends a read receipt for a message you received: the sender sees blue ticks, as if you
opened the chat. read_at is set. To do this for every new message automatically,
turn on auto_read (see "Update instance settings"). Read receipts are only shown if
your number has them enabled in WhatsApp's privacy settings.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/read" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/read"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "POST",
headers,
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/read';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/read'
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers)
response.json()Example response (200):
{
"success": true,
"data": {
"id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"direction": "in",
"status": "received",
"read_at": "2026-10-27T10:00:05Z"
},
"error": null
}
Example response (409, Number not connected):
{
"success": false,
"data": null,
"error": {
"code": "instance_not_connected",
"message": "The number is not connected."
}
}
Example response (422, Not a received message):
{
"success": false,
"data": null,
"error": {
"code": "message_not_incoming",
"message": "Only received messages can be marked as read."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
React to a message
requires authentication
Adds an emoji reaction to a message of this chat (one you received or sent), like
long-pressing it in WhatsApp; null removes your reaction. Reactions from the other
person arrive on your webhook as message.reaction; both are in "Get a message"
(content.reactions: customer, us).
Example request:
curl --request POST \
"https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/react" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"emoji\": \"👍\"
}"
const url = new URL(
"https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/react"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"emoji": "👍"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/react';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'emoji' => '👍',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/messages/01j9z8q0a1b2c3d4e5f6g7h8j9/react'
payload = {
"emoji": "👍"
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (200):
{
"success": true,
"data": {
"id": "01j9z8q0a1b2c3d4e5f6g7h8j9",
"content": {
"text": "Thanks!",
"reactions": {
"us": "👍"
}
}
},
"error": null
}
Example response (409, Number not connected):
{
"success": false,
"data": null,
"error": {
"code": "instance_not_connected",
"message": "The number is not connected right now."
}
}
Example response (422, Not on WhatsApp yet):
{
"success": false,
"data": null,
"error": {
"code": "message_not_sent",
"message": "This message has not reached WhatsApp yet."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
OTP
Verify a user's phone number with a one-time code sent over WhatsApp: send a code, then check what the user typed. We generate and keep the code (only a hash of it), so you do not have to.
- A code works once, until it expires, for at most 5 tries.
- Per number: at most 3 codes in 10 minutes, and 30 seconds between two (
429 otp_rate_limitedwithdata.retry_afterseconds). - It is sent like any message (pacing, daily limit), so it usually arrives within seconds;
its delivery is reported as usual (
message.statuswebhook,message_id). - Add
linkfor a "magic link": the message then has a link with the code in it, for one-tap login on your site (your page sends the code to "Verify a code").
Reverse OTP ("Create a reverse code"): instead of us messaging the user, the user
messages your number. Show them the returned link (a wa.me link with the code already
typed) or a QR of it; when their message arrives the code is verified, you get an
otp.verified webhook (sent to your webhook URL whatever events you picked), and
"Get a code's status" says verified with the user's phone. No chat is started by your
number, so it is safer for it, and it counts as half a code. These messages are not filed
in the team inbox.
Codes count against your plan's OTP allowance (Billing): above it they are billed per code
with your next payment, up to a monthly limit (402 otp_limit_reached after that).
Send a code
requires authentication
Example request:
curl --request POST \
"https://wagateway.io/api/v1/otp" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to\": \"+201001234567\",
\"length\": 6,
\"expires_in\": 300,
\"language\": \"ar\",
\"brand\": \"ZONE\",
\"link\": \"https:\\/\\/example.com\\/login?code={code}\"
}"
const url = new URL(
"https://wagateway.io/api/v1/otp"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to": "+201001234567",
"length": 6,
"expires_in": 300,
"language": "ar",
"brand": "ZONE",
"link": "https:\/\/example.com\/login?code={code}"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/otp';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'to' => '+201001234567',
'length' => 6,
'expires_in' => 300,
'language' => 'ar',
'brand' => 'ZONE',
'link' => 'https://example.com/login?code={code}',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/otp'
payload = {
"to": "+201001234567",
"length": 6,
"expires_in": 300,
"language": "ar",
"brand": "ZONE",
"link": "https:\/\/example.com\/login?code={code}"
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (201, Sent):
{
"success": true,
"data": {
"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n",
"to": "201001234567",
"expires_at": "2026-11-01T10:05:00Z",
"message_id": "01jb2x4m1a2b3c4d5e6f7g8h9j"
},
"error": null
}
Example response (429, Too many codes):
{
"success": false,
"data": {
"retry_after": 22
},
"error": {
"code": "otp_rate_limited",
"message": "Too many codes for this number. Try again later."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Verify a code
requires authentication
Always 200: check data.valid. When it is false, data.reason is wrong_code
(with attempts_left), expired, too_many_attempts, already_used or not_found.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/otp/verify" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"otp_id\": \"01jb2x4m0f8a9c3d7e6g5h4k2n\",
\"code\": \"482913\"
}"
const url = new URL(
"https://wagateway.io/api/v1/otp/verify"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n",
"code": "482913"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/otp/verify';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'otp_id' => '01jb2x4m0f8a9c3d7e6g5h4k2n',
'code' => '482913',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/otp/verify'
payload = {
"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n",
"code": "482913"
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (200, Valid):
{
"success": true,
"data": {
"valid": true,
"reason": null,
"attempts_left": null,
"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n"
},
"error": null
}
Example response (200, Wrong code):
{
"success": true,
"data": {
"valid": false,
"reason": "wrong_code",
"attempts_left": 4,
"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n"
},
"error": null
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Create a reverse code
requires authentication
Example request:
curl --request POST \
"https://wagateway.io/api/v1/otp/reverse" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"phone\": \"+201001234567\",
\"length\": 6,
\"expires_in\": 300,
\"language\": \"ar\",
\"brand\": \"ZONE\",
\"reply\": \"تم التحقق من رقمك ✅\"
}"
const url = new URL(
"https://wagateway.io/api/v1/otp/reverse"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"phone": "+201001234567",
"length": 6,
"expires_in": 300,
"language": "ar",
"brand": "ZONE",
"reply": "تم التحقق من رقمك ✅"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/otp/reverse';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'phone' => '+201001234567',
'length' => 6,
'expires_in' => 300,
'language' => 'ar',
'brand' => 'ZONE',
'reply' => 'تم التحقق من رقمك ✅',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/otp/reverse'
payload = {
"phone": "+201001234567",
"length": 6,
"expires_in": 300,
"language": "ar",
"brand": "ZONE",
"reply": "تم التحقق من رقمك ✅"
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (201, Created):
{
"success": true,
"data": {
"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n",
"code": "482913",
"text": "كود التحقق: 482913",
"link": "https://wa.me/201001234567?text=%D9%83%D9%88%D8%AF%20%D8%A7%D9%84%D8%AA%D8%AD%D9%82%D9%82%3A%20482913",
"expires_at": "2026-11-01T10:05:00Z"
},
"error": null
}
Example response (409, Number not connected):
{
"success": false,
"data": null,
"error": {
"code": "instance_not_connected",
"message": "The number is not connected."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get a code's status
requires authentication
status is pending, verified or expired. For a reverse code, phone is the
number that sent it once verified.
Example request:
curl --request GET \
--get "https://wagateway.io/api/v1/otp/01jb2x4m0f8a9c3d7e6g5h4k2n" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://wagateway.io/api/v1/otp/01jb2x4m0f8a9c3d7e6g5h4k2n"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/otp/01jb2x4m0f8a9c3d7e6g5h4k2n';
$response = $client->get(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/otp/01jb2x4m0f8a9c3d7e6g5h4k2n'
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()Example response (200, Verified):
{
"success": true,
"data": {
"otp_id": "01jb2x4m0f8a9c3d7e6g5h4k2n",
"mode": "reverse",
"status": "verified",
"phone": "201001234567",
"expires_at": "2026-11-01T10:05:00Z",
"verified_at": "2026-11-01T10:01:12Z"
},
"error": null
}
Example response (404, Unknown id):
{
"success": false,
"data": null,
"error": {
"code": "otp_not_found",
"message": "OTP not found."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Contacts
Check a number
requires authentication
Is this phone number on WhatsApp? Results are cached for 24 hours. You do not need to call this before sending: every send already checks the recipient. Limited to 20 requests per minute, because many lookups in a row can get a number flagged.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/contacts/check" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"phone\": \"+201001234567\"
}"
const url = new URL(
"https://wagateway.io/api/v1/contacts/check"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"phone": "+201001234567"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/contacts/check';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'phone' => '+201001234567',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/contacts/check'
payload = {
"phone": "+201001234567"
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (200, On WhatsApp):
{
"success": true,
"data": {
"phone": "201001234567",
"exists": true
},
"error": null
}
Example response (200, Not on WhatsApp):
{
"success": true,
"data": {
"phone": "201009999999",
"exists": false
},
"error": null
}
Example response (409, Instance not connected):
{
"success": false,
"data": null,
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected to WhatsApp."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Webhooks
We POST events to your webhook_url as JSON. Respond with any 2xx within 10 seconds;
anything else (or a timeout) is retried after 10 s, 1 min, 5 min, 30 min and 2 h. Respond
410 Gone to stop retries for an event. The same event can arrive more than once, so
de-duplicate on id. Your URL must be public http/https (internal addresses are refused)
and redirects are not followed.
Deliveries can arrive out of order (a retried sent after a read, for example). For
message.status, keep the most advanced status: sent < delivered < read; failed is final.
Events
| event | when | data |
|---|---|---|
message.received |
someone sent your number a message | messageId, from, senderName, type, text, caption, mediaId, mediaMime, location, timestamp |
message.sent_from_phone |
you sent a message yourself from the phone or WhatsApp Web (not through the API), so your copy of the chat stays complete | messageId, to, type, text, caption, mediaMime, fileName, location, timestamp |
message.reaction |
someone reacted to a message (or you did, from the phone) | messageId, emoji (null = reaction removed), by (customer or us), from |
message.poll_vote |
someone voted on your poll (or changed / removed their vote) | messageId (the poll), from, selected (their current answers; empty = vote removed), votedAt |
message.status |
a message you sent changed status | messageId, status (sent, delivered, read, failed), timestamp, and error when failed (e.g. not_on_whatsapp) |
instance.connected / instance.disconnected / instance.logged_out / instance.banned |
the number's connection changed | phone, reason |
instance.paused |
sending was paused after repeated failures | reason, failures |
instance.restriction |
WhatsApp's limit on new chats changed (timelock started or ended, or the new-chat cap moved to FIRST_WARNING, SECOND_WARNING, CAPPED or back to NONE) |
timelock (active, until, type), newChatCap (status, used, total, resetsAt) |
otp.verified |
a user sent your number a reverse OTP code (see OTP). Sent to every webhook URL, whatever events you picked | otp_id, mode (reverse), status, phone, expires_at, verified_at |
Example body:
{
"id": "01J9Z9C4H7K2M5P8R1T4W7Y0B3",
"event": "message.received",
"instance_id": "01j9z8k2m3n4p5q6r7s8t9v0wx",
"data": { "messageId": "01j9z9c4...", "from": "201001234567", "senderName": "Ahmed", "type": "text", "text": "Hi, is my order ready?", "timestamp": "2026-10-12T10:20:00.000Z" },
"occurred_at": "2026-10-12T10:20:00.412Z",
"sent_at": "2026-10-12T10:20:00.530Z"
}
Verifying the signature
Every request carries two headers:
X-Timestamp: Unix time in seconds when we signed the requestX-Signature: hexHMAC-SHA256(X-Timestamp + "." + raw request body, your webhook secret)
Always verify before trusting a webhook. Compute the HMAC over the raw body bytes (before any JSON parsing), compare in constant time, and reject timestamps older than 5 minutes to stop replays. Your secret is returned by "Set the webhook".
PHP (Laravel)
Route::post('/wa-webhook', function (Illuminate\Http\Request $request) {
$secret = env('WA_WEBHOOK_SECRET');
$timestamp = $request->header('X-Timestamp');
$signature = $request->header('X-Signature');
$raw = $request->getContent();
$expected = hash_hmac('sha256', $timestamp.'.'.$raw, $secret);
if (! $signature || ! hash_equals($expected, $signature) || abs(time() - (int) $timestamp) > 300) {
abort(401);
}
$event = json_decode($raw, true);
// de-duplicate on $event['id'], then handle $event['event'] / $event['data']
return response()->noContent();
});
Plain PHP
$raw = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $timestamp.'.'.$raw, getenv('WA_WEBHOOK_SECRET'));
if (!hash_equals($expected, $signature) || abs(time() - (int) $timestamp) > 300) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true);
http_response_code(200);
Node.js (Express)
const crypto = require('crypto');
const express = require('express');
const app = express();
// Keep the raw body: the signature is over the exact bytes we sent.
app.post('/wa-webhook', express.raw({ type: 'application/json' }), (req, res) => {
const timestamp = req.get('X-Timestamp') || '';
const signature = req.get('X-Signature') || '';
const expected = crypto
.createHmac('sha256', process.env.WA_WEBHOOK_SECRET)
.update(`${timestamp}.${req.body}`)
.digest('hex');
const valid =
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)) &&
Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body);
// de-duplicate on event.id, then handle event.event / event.data
res.sendStatus(200);
});
Set the webhook
requires authentication
Sets where events are sent (url, or null to stop sending) and which events you want
(a new number starts with message.received, message.status, message.sent_from_phone,
message.reaction, message.poll_vote and instance.restriction). The response includes the
signing secret; pass rotate_secret: true to replace it (the old one stops working
immediately).
Example request:
curl --request POST \
"https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/webhook" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"url\": \"https:\\/\\/example.com\\/wa-webhook\",
\"events\": [
\"message.received\"
],
\"rotate_secret\": false
}"
const url = new URL(
"https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/webhook"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"url": "https:\/\/example.com\/wa-webhook",
"events": [
"message.received"
],
"rotate_secret": false
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/webhook';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'url' => 'https://example.com/wa-webhook',
'events' => ['message.received'],
'rotate_secret' => false,
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/webhook'
payload = {
"url": "https:\/\/example.com\/wa-webhook",
"events": [
"message.received"
],
"rotate_secret": false
}
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()Example response (200):
{
"success": true,
"data": {
"url": "https://example.com/wa-webhook",
"events": [
"message.received",
"message.status",
"instance.disconnected"
],
"secret": "Xq3vT9bL2mN7pR4sW8yZ1cF6hJ0kD5gA",
"signature": "X-Signature = hex HMAC-SHA256(X-Timestamp + \".\" + raw body, secret)"
},
"error": null
}
Example response (422, Internal or invalid URL):
{
"success": false,
"data": null,
"error": {
"code": "validation_failed",
"message": "The url must point to a public internet address.",
"fields": {
"url": [
"The url must point to a public internet address."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Send a test event
requires authentication
Sends one signed webhook.test event to your URL right away and tells you what your
server answered. Use it to check your signature verification.
Example request:
curl --request POST \
"https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/webhook/test" \
--header "Authorization: Bearer {INSTANCE_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/webhook/test"
);
const headers = {
"Authorization": "Bearer {INSTANCE_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "POST",
headers,
}).then(response => response.json());$client = new \GuzzleHttp\Client();
$url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/webhook/test';
$response = $client->post(
$url,
[
'headers' => [
'Authorization' => 'Bearer {INSTANCE_TOKEN}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));import requests
import json
url = 'https://wagateway.io/api/v1/instances/01j9z8k2m3n4p5q6r7s8t9v0wx/webhook/test'
headers = {
'Authorization': 'Bearer {INSTANCE_TOKEN}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers)
response.json()Example response (200, Delivered):
{
"success": true,
"data": {
"delivery_id": "01J9Z9D2F5H8K1M4P7R0T3W6Y9",
"delivered": true,
"response_code": 200,
"error": null
},
"error": null
}
Example response (200, Your server failed):
{
"success": true,
"data": {
"delivery_id": "01J9Z9D2F5H8K1M4P7R0T3W6Y9",
"delivered": false,
"response_code": 500,
"error": "HTTP 500: Internal Server Error"
},
"error": null
}
Example response (409, No URL set):
{
"success": false,
"data": null,
"error": {
"code": "webhook_not_configured",
"message": "Set a webhook URL first."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.