MENU navbar-image

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."
    }
}
 

Request      

POST api/v1/instances

Headers

Authorization        

Example: Bearer {ACCOUNT_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

name   string     

A label for this number, for your own reference. Must not be greater than 100 characters. Example: Sales line

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."
    }
}
 

Request      

GET api/v1/instances/{id}/qr

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The instance ID. Example: 01j9z8k2m3n4p5q6r7s8t9v0wx

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
}
 

Request      

GET api/v1/instances/{id}/status

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The instance ID. Example: 01j9z8k2m3n4p5q6r7s8t9v0wx

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."
    }
}
 

Request      

POST api/v1/instances/{id}/logout

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The instance ID. Example: 01j9z8k2m3n4p5q6r7s8t9v0wx

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
}
 

Request      

POST api/v1/instances/{id}/settings

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The instance ID. Example: 01j9z8k2m3n4p5q6r7s8t9v0wx

Body Parameters

auto_read   boolean     

Example: true

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."
    }
}
 

Request      

POST api/v1/messages/text

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Idempotency-Key        

Example: order-1042-shipped

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

to   string     

Recipient phone number in international format. Spaces, dashes and a leading + or 00 are accepted. Must not be greater than 32 characters. Example: +201001234567

text   string     

Message text (max 65,536 characters). Line breaks and spacing are kept. Must match the regex /\S/. Must not be greater than 65536 characters. Example: Hi Ahmed, your order #1042 has shipped. Track it: https://example.com/t/1042

send_at   string  optional    

Optional. Schedule the message (ISO 8601, e.g. 2026-10-20T09:00:00+03:00), up to 30 days ahead. Omit or use a past time to send now. It still goes out with the normal pacing and daily limit. Must be a valid date. Must be a date before +30 days.

reply_to   string  optional    

Optional. The message_id of a message in the same chat (received or sent) to quote above this one, like swiping to reply. Must be 26 characters.

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."
    }
}
 

Request      

POST api/v1/messages/image

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Idempotency-Key        

Example: order-1042-shipped

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

to   string     

Recipient phone number in international format. Spaces, dashes and a leading + or 00 are accepted. Must not be greater than 32 characters. Example: +201001234567

url   string     

Public http(s) URL of the image (JPEG, PNG or WebP, max 16 MB). Must be a valid URL. Must not be greater than 2048 characters. Example: https://cdn.example.com/products/1042.jpg

caption   string  optional    

Optional caption (max 1,024 characters). Must not be greater than 1024 characters. Example: Your order is on its way

send_at   string  optional    

Optional. Schedule the message (ISO 8601, e.g. 2026-10-20T09:00:00+03:00), up to 30 days ahead. Omit or use a past time to send now. It still goes out with the normal pacing and daily limit. Must be a valid date. Must be a date before +30 days.

reply_to   string  optional    

Optional. The message_id of a message in the same chat (received or sent) to quote above this one, like swiping to reply. Must be 26 characters.

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."
    }
}
 

Request      

POST api/v1/messages/video

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Idempotency-Key        

Example: order-1042-shipped

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

to   string     

Recipient phone number in international format. Spaces, dashes and a leading + or 00 are accepted. Must not be greater than 32 characters. Example: +201001234567

url   string     

Public http(s) URL of the video (MP4, max 16 MB). Must be a valid URL. Must not be greater than 2048 characters. Example: https://cdn.example.com/videos/unboxing.mp4

caption   string  optional    

Optional caption (max 1,024 characters). Must not be greater than 1024 characters. Example: How to set it up

send_at   string  optional    

Optional. Schedule the message (ISO 8601, e.g. 2026-10-20T09:00:00+03:00), up to 30 days ahead. Omit or use a past time to send now. It still goes out with the normal pacing and daily limit. Must be a valid date. Must be a date before +30 days.

reply_to   string  optional    

Optional. The message_id of a message in the same chat (received or sent) to quote above this one, like swiping to reply. Must be 26 characters.

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."
    }
}
 

Request      

POST api/v1/messages/audio

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Idempotency-Key        

Example: order-1042-shipped

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

to   string     

Recipient phone number in international format. Spaces, dashes and a leading + or 00 are accepted. Must not be greater than 32 characters. Example: +201001234567

url   string     

Public http(s) URL of the audio file (max 16 MB). Use OGG/Opus for voice notes. Must be a valid URL. Must not be greater than 2048 characters. Example: https://cdn.example.com/audio/welcome.ogg

voice_note   boolean  optional    

Send as a voice note instead of an audio file. Example: true

send_at   string  optional    

Optional. Schedule the message (ISO 8601, e.g. 2026-10-20T09:00:00+03:00), up to 30 days ahead. Omit or use a past time to send now. It still goes out with the normal pacing and daily limit. Must be a valid date. Must be a date before +30 days.

reply_to   string  optional    

Optional. The message_id of a message in the same chat (received or sent) to quote above this one, like swiping to reply. Must be 26 characters.

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."
    }
}
 

Request      

POST api/v1/messages/document

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Idempotency-Key        

Example: order-1042-shipped

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

to   string     

Recipient phone number in international format. Spaces, dashes and a leading + or 00 are accepted. Must not be greater than 32 characters. Example: +201001234567

url   string     

Public http(s) URL of the file (max 16 MB). Must be a valid URL. Must not be greater than 2048 characters. Example: https://cdn.example.com/invoices/1042.pdf

filename   string     

File name shown to the recipient. Must not be greater than 255 characters. Example: Invoice-1042.pdf

mimetype   string     

MIME type of the file. Must match the regex /^[\w.+-]+\/[\w.+-]+$/. Must not be greater than 127 characters. Example: application/pdf

caption   string  optional    

Optional caption (max 1,024 characters). Must not be greater than 1024 characters. Example: Your invoice for October

send_at   string  optional    

Optional. Schedule the message (ISO 8601, e.g. 2026-10-20T09:00:00+03:00), up to 30 days ahead. Omit or use a past time to send now. It still goes out with the normal pacing and daily limit. Must be a valid date. Must be a date before +30 days.

reply_to   string  optional    

Optional. The message_id of a message in the same chat (received or sent) to quote above this one, like swiping to reply. Must be 26 characters.

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."
    }
}
 

Request      

POST api/v1/messages/location

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Idempotency-Key        

Example: order-1042-shipped

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

to   string     

Recipient phone number in international format. Spaces, dashes and a leading + or 00 are accepted. Must not be greater than 32 characters. Example: +201001234567

lat   number     

Latitude, -90 to 90. Must be between -90 and 90. Example: 30.0444

lng   number     

Longitude, -180 to 180. Must be between -180 and 180. Example: 31.2357

name   string  optional    

Optional place name. Must not be greater than 255 characters. Example: Cairo Store

address   string  optional    

Optional address. Must not be greater than 512 characters. Example: 12 Tahrir Square, Cairo

send_at   string  optional    

Optional. Schedule the message (ISO 8601, e.g. 2026-10-20T09:00:00+03:00), up to 30 days ahead. Omit or use a past time to send now. It still goes out with the normal pacing and daily limit. Must be a valid date. Must be a date before +30 days.

reply_to   string  optional    

Optional. The message_id of a message in the same chat (received or sent) to quote above this one, like swiping to reply. Must be 26 characters.

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
}
 

Request      

POST api/v1/messages/poll

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Idempotency-Key        

Example: restock-poll-2026-11

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

to   string     

Recipient phone number in international format. Spaces, dashes and a leading + or 00 are accepted. Must not be greater than 32 characters. Example: +201001234567

question   string     

The question (max 255 characters). Must not be greater than 255 characters. Example: Which scent should we restock first?

options   string[]     

Must not be greater than 100 characters.

multiple   boolean  optional    

Allow choosing several answers. Default false (one answer). Example: false

send_at   string  optional    

Optional. Schedule the message (ISO 8601), up to 30 days ahead. Must be a valid date. Must be a date before +30 days.

reply_to   string  optional    

Optional. The message_id of a message in the same chat (received or sent) to quote above this one, like swiping to reply. Must be 26 characters.

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
}
 

Request      

GET api/v1/messages

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

status   string  optional    

Only messages with this status: queued, sent, delivered, read, failed, received. Example: failed

Must be one of:
  • queued
  • sent
  • delivered
  • read
  • failed
  • received
  • cancelled
direction   string  optional    

out for sent, in for received. Example: out

Must be one of:
  • in
  • out
from   string  optional    

Created at or after this date/time (UTC, ISO 8601 or YYYY-MM-DD). Must be a valid date. Example: 2026-10-01

to   string  optional    

Created at or before this date/time (UTC). Must be a valid date. Must be a date after or equal to from. Example: 2026-10-12T23:59:59Z

per_page   integer  optional    

Items per page, 1–100 (default 20). Must be at least 1. Must not be greater than 100. Example: 20

page   integer  optional    

Page number (default 1). Must be at least 1. Example: 1

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."
    }
}
 

Request      

GET api/v1/messages/{id}

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The message ID. Example: 01j9z8q0a1b2c3d4e5f6g7h8j9

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."
    }
}
 

Request      

GET api/v1/messages/{id}/media

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The message ID. Example: 01j9z8q0a1b2c3d4e5f6g7h8j9

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."
    }
}
 

Request      

DELETE api/v1/messages/{id}

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The message ID. Example: 01j9z8q0a1b2c3d4e5f6g7h8j9

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."
    }
}
 

Request      

POST api/v1/messages/{id}/read

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The message ID (a received message). Example: 01j9z8q0a1b2c3d4e5f6g7h8j9

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."
    }
}
 

Request      

POST api/v1/messages/{id}/react

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The message ID. Example: 01j9z8q0a1b2c3d4e5f6g7h8j9

Body Parameters

emoji   string  optional    

An emoji, e.g. 👍 or ❤️. null or "" removes your reaction. Must not be greater than 32 characters. Example: 👍

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.

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."
    }
}
 

Request      

POST api/v1/otp

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

to   string     

Recipient phone number in international format. Must not be greater than 32 characters. Example: +201001234567

length   integer  optional    

Digits in the code, 4–8. Default 6. Must be between 4 and 8. Example: 6

expires_in   integer  optional    

Seconds the code is valid, 60–1800. Default 300. Must be between 60 and 1800. Example: 300

language   string  optional    

Language of the default message: ar (default) or en. Example: ar

Must be one of:
  • ar
  • en
brand   string  optional    

Optional name shown before the default message, e.g. your app name. Must not be greater than 40 characters. Example: ZONE

message   string  optional    

Your own text instead of the default; must contain {code}; may use {minutes} and {link}. Must match the regex /{code}/. Must not be greater than 1000 characters.

link   string  optional    

Optional https link with {code} (a "magic link"): added to the message with the code filled in, for one-tap login on your site. Must match the regex /{code}/. Must not be greater than 500 characters. Example: https://example.com/login?code={code}

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
}
 

Request      

POST api/v1/otp/verify

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

otp_id   string  optional    

The otp_id from "Send a code". Or give to to check the latest code sent to that number. This field is required when to is not present. Must be 26 characters. Example: 01jb2x4m0f8a9c3d7e6g5h4k2n

to   string  optional    

Recipient phone (instead of otp_id). This field is required when otp_id is not present. Must not be greater than 32 characters.

code   string     

The code the user typed. Must not be greater than 16 characters. Example: 482913

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."
    }
}
 

Request      

POST api/v1/otp/reverse

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

phone   string  optional    

Optional: only accept the code from this number (international format). Without it, the code verifies whoever sends it, and phone in the result tells you who. Must not be greater than 32 characters. Example: +201001234567

length   integer  optional    

Digits in the code, 4–8. Default 6. Must be between 4 and 8. Example: 6

expires_in   integer  optional    

Seconds the code is valid, 60–1800. Default 300. Must be between 60 and 1800. Example: 300

language   string  optional    

Language of the prefilled text: ar (default) or en. Example: ar

Must be one of:
  • ar
  • en
brand   string  optional    

Optional name shown before the prefilled text. Must not be greater than 40 characters. Example: ZONE

message   string  optional    

Your own prefilled text instead of the default; must contain {code}. Must match the regex /{code}/. Must not be greater than 300 characters.

reply   string  optional    

Optional text sent back to the user once their code arrives, e.g. "You are logged in ✅". Must not be greater than 1000 characters. Example: تم التحقق من رقمك ✅

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."
    }
}
 

Request      

GET api/v1/otp/{id}

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The otp_id. Example: 01jb2x4m0f8a9c3d7e6g5h4k2n

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."
    }
}
 

Request      

POST api/v1/contacts/check

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

phone   string     

Phone number in international format. Must not be greater than 32 characters. Example: +201001234567

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:

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."
            ]
        }
    }
}
 

Request      

POST api/v1/instances/{id}/webhook

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The instance ID. Example: 01j9z8k2m3n4p5q6r7s8t9v0wx

Body Parameters

url   string  optional    

Public http(s) URL that receives events, or null to stop sending. Must be a valid URL. Must not be greater than 2048 characters. Example: https://example.com/wa-webhook

events   string[]  optional    

An event name.

Must be one of:
  • message.received
  • message.status
  • instance.connected
  • instance.disconnected
  • instance.logged_out
  • instance.banned
  • instance.paused
  • instance.restriction
  • message.sent_from_phone
  • message.reaction
  • message.poll_vote
rotate_secret   boolean  optional    

Generate a new signing secret (the old one stops working immediately). Example: false

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."
    }
}
 

Request      

POST api/v1/instances/{id}/webhook/test

Headers

Authorization        

Example: Bearer {INSTANCE_TOKEN}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The instance ID. Example: 01j9z8k2m3n4p5q6r7s8t9v0wx