Whatsapp API

Changing session name - [Response object]

denis716@undisclosed.example.com (denis716) — Fri, 16 Oct 2026 20:18:10 +0000

Changing session name

Changes the name of a WhatsApp session.

Request command

To change a session name, send a POST request to:

https://app.whatsgate.org/api/v1/set-name

Request body object

The request body must contain:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "name": "new name"
}

WhatsappID - WhatsApp identifier in the system
name - new session name

Response object

Successful response object

{
  "result": "OK",
  "data":  {
     "id": 151,
     "name": "new name",
     "unique_id": "6345454545454",
     "status": "READY",
     "callback": "https://callback.my/script.handler",
     "date_add": "2022-10-11 19:30:14",
     "status_name": "Working",
     "pushname": "John",
     "wid": "19991234567@c.us",
  }
}

data - session object

Getting the session list - [Response object]

denis716@undisclosed.example.com (denis716) — Fri, 16 Oct 2026 20:17:45 +0000

Getting the session list

Returns the sessions on your account.

Request command

To retrieve the session list, send a POST request to:

https://app.whatsgate.org/api/v1/sessions-get

Request body object

The request body accepts:

{
  "WhatsappID" : "",
  "name" : "",
  "status" : "",
  "page_cnt" : "",
  "page" : ""
}

All fields in this object are optional, so an empty object is enough to get the full list of active sessions. Fields WhatsappID, name, and status are filters.

WhatsappID - filter by WhatsApp identifier, exact match; returns one session with the specified identifier.
name - filter by name, partial match.
status - session status filter. Can be one of:
- AUTH - sessions in authorization status.
- READY - sessions in working state.
- ERROR - sessions in error state.
- CLOSED - closed sessions (due to error or end of paid period)
page_cnt - maximum sessions returned per page. Default is 50, maximum is 100.
page - page number. Default is 1

Response object

Successful response object

{
  "result": "OK",
  "pages" : 1,
  "elements" : 2,
  "page" : 1,
  "data" : [
     {
        "id": 151,
        "name": "My WhatsApp 1",
        "unique_id": "6345454545454",
        "status": "AUTH",
        "callback": "",
        "date_add": "2022-10-11 19:30:14",
        "status_name": "Authorization",
        "pushname": null,
        "wid": null,
        "qr_link": "https://whatsgate.org/qr/6345454545454"
     },
     {
        "id": 152,
        "name": "My WhatsApp 2",
        "unique_id": "6345454545455",
        "status": "READY",
        "callback": "",
        "date_add": "2022-10-12 10:35:01",
        "status_name": "Working",
        "pushname": "John",
        "wid": "19991234567@c.us",
        "qr_link": ""
     },
  ]
}

result - contains “OK” when the request succeeds
pages - number of pages for the selected filters
elements - number of elements in the filtered result (number of WhatsApp sessions returned)
page - current page number
data - contains an array of WhatsApp session objects

Deleting a session via API - [Response object]

denis716@undisclosed.example.com (denis716) — Fri, 16 Oct 2026 20:17:12 +0000

Deleting a session via API

Deleting a session logs that WhatsApp account out of Whatsgate, removes the session data from Whatsgate servers, and frees the connection. If your plan has no free connection left, delete a session before you create another one.

Request command

Send a POST request to:

https://app.whatsgate.org/api/v1/session-delete

Request body object

The request body must contain:

{
  "WhatsappID": "YOUR_WHATSAPP_ID"
}

WhatsappID - WhatsApp identifier in the system

Response object

Successful response object

{
  "result": "OK",
  "data": {
        "id": 456,
        "name": "My Whatsapp",
        "unique_id": "YOUR_WHATSAPP_ID",
        "status": "DESTROYING",
        "callback": null,
        "date_add": "2022-10-12 07:10:49",
        "status_name": "Deleting",
        "pushname": "John",
        "wid": "19991234567@c.us",
    }
}

Creating a session via API - [Embedding the QR page]

denis716@undisclosed.example.com (denis716) — Fri, 16 Oct 2026 20:16:35 +0000

Creating a session via API

This request opens a WhatsApp session so you can link an account. After it opens, authorize the session in the WhatsApp mobile app with a QR code. When you no longer need the session, close it with session-delete.

Request command

To create a session, send a POST request to:

https://app.whatsgate.org/api/v1/session-create

Request body object for QR authorization

The request body must contain:

{
  "name" : "My WhatsApp",
  "callback" : "https://callback.my/script.handler"
}

name - WhatsApp name in the system (for easier identification)
callback - URL of the incoming events handler (optional, can be set later via set-hook)

Request body object for CODE authorization

The request body must contain:

{
  "name" : "My WhatsApp",
  "callback" : "https://callback.my/script.handler",
  "auth_type" : "CODE",
  "number" : "19999999999"
}

name - WhatsApp name in the system (for easier identification)
callback - URL of the incoming events handler (optional, can be set later via set-hook)
auth_type - authorization type set to code. In this mode, phone number becomes required.
number - phone number to connect in 7XXXXXXXXXX format

Response object

Successful response object

{
  "result": "OK",
  "data" : {
     "id": 151,
     "name": "My WhatsApp",
     "unique_id": "6345454545454",
     "status": "PENDING",
     "callback": "https://callback.my/script.handler",
     "date_add": "2022-10-11 19:30:14",
     "qr": null,
     "status_name": "Initialization",
     "pushname": null,
     "wid": null,
     "qr_link": "https://whatsgate.org/qr/6345454545454"
  }
}

result - contains “OK” when the request succeeds.
data - contains created session object including its unique identifier unique_id and QR authorization link qr_link.
qr or code depends on selected authorization type. If code authorization is selected, the code is returned in code. Field qr_link points to the authorization code page.

QR authorization window

The QR authorization window is available at:

https://app.whatsgate.org/qr/<unique_id>

For convenience, this link is returned in qr_link when creating a session. The QR code in this window is updated periodically and changes to a success or error image after authorization.

Embedding the QR page

This page can be embedded into your app via iframe, and parent page can receive messages from it. Embedding example:

<h1>QR test code</h1>

<iframe src="https://app.whatsgate.org/qr/6345454545454" width="310" height="310" style="border: none;">

</iframe>

<div class="log" id="log">

</div>

<script>
    window.addEventListener("message", function(event) {

        console.log(event);

        if (event.origin !== 'https://app.whatsgate.org') {
            // something came from an unknown domain; ignore it
            return;
        }

        if(typeof event.data !== 'object') {
            // message must be an object
            return;
        }

        if(!('module' in event.data) && event.data.module !== 'qr'){
            // object must contain module field with value qr
            return;
        }

        //if we're here, the message is valid; output it
        console.log( "received: " + event.data.message);
        //append message to parent-page log
        document.getElementById('log').append("received: " + event.data.message, document.createElement("br"));
    });
</script>

The message object is in event.data and has this format:

{
  "module" : "qr",
  "message" : "<message>"
}

module - always has value qr, to identify relevant messages
message - can have the following values:
- loading - session initialization and QR code loading; sent at page load start
- qr - QR code has been generated and displayed; sent each time code refreshes
- success - device authorized successfully; QR code is hidden
- error - authorization error occurred; try again
- broken - attempt to open a window with non-existing or closed session identifier

Incoming events processing (events-get) - [Request command]

denis716@undisclosed.example.com (denis716) — Fri, 16 Oct 2026 20:15:25 +0000

Incoming events processing (events-get)

Returns incoming events, including:

incoming messages (action = message)
message read/update (action = ack)
incoming media file (action = media)
message sent (action = sent) - this event appears only for asynchronous sending
error (action = error)
WhatsApp disconnect and session removal (action = disconnect)

Request command

To retrieve the event list, send a POST request to:

https://app.whatsgate.org/api/v1/events-get

Request body object

The request body accepts the following object:

{
  "WhatsappID" : "XXXXXXXXXXXXX",
  "date" : "YYYY-MM-DD HH:MM:SS",
  "action" : "message",
  "page_cnt" : "10",
  "page" : "1"
}

All fields in this object are optional, meaning an empty object is enough to get the full list of events. Fields WhatsappID and action are filters, and date limits events by date. The date is typically used like this: after reading events, take the date of the last event and pass it in the next request as date to fetch only newer events.

WhatsappID - filter by WhatsApp identifier; uses exact match and returns events for the specified session. If omitted, the system returns events for all sessions, including deleted ones.
date - limits events by the specified date. A common pattern is to reuse the latest received event date in the next request to get fresh events only.
action - event type filter. Can be one of:
- message - incoming message.
- ack - message status update.
- media - incoming media file.
- sent - message sent (only when sending asynchronously)
- error - error
- disconnect - WhatsApp disconnect and session deletion
- create - outgoing message
page_cnt - maximum number of events per response page. Default is 10, maximum is 100.
page - response page number. Default is 1

Response object

Successful response object

{
  "result": "OK",
  "pages" : 1,
  "elements" : 2,
  "page" : 1,
  "data" : [
     // 
  ]
}

result - contains “OK” when the request succeeds
pages - number of pages for the given filters
elements - number of matching elements (event count)
page - current page number
data - contains an array of objects representing events.

Incoming processing (Webhook) - [Message object]

denis716@undisclosed.example.com (denis716) — Fri, 16 Oct 2026 20:14:47 +0000

Incoming processing (Webhook)

Webhooks deliver incoming events, asynchronous send results, and errors. When a message arrives in WhatsApp, Whatsgate sends a POST request to your webhook URL:

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"message",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id" : "3EB0436AE1E682FF3A37",
       "id":"false_19999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"19991112233@c.us",
       "to":"19999999999@c.us",
       "isForwarded":false
    }
  }
}

To confirm successful event receipt, your webhook must return a JSON object containing the incoming event identifier and status OK.

{
  "result" : "OK",
  "id" : 18
}

If the system does not receive a valid response, it retries the request 3 times every 20 seconds.

Webhook setup

Webhook setup in account dashboard

To set a Webhook handler URL, open your account dashboard, choose the linked WhatsApp block, click the 3 dots, then click edit.

In the opened window, specify the URL to your Webhook handler script.

Click “Save”.

Webhook setup via API

To enable or disable WebHook via API, use the set-hook method. Send a POST request to:

https://app.whatsgate.org/api/v1/set-hook

Request body:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "callback": "https://callback.my/script.handler"
}

WhatsappID - WhatsApp identifier in the system
callback - URL of incoming events handler

Successful response object

{
  "result": "OK"
}

Event types

Ready

This event is sent after authorization, when the client is fully ready to send and receive messages. Session status changes from AUTH to READY. Field event_action contains “ready”. Field event_data contains authorized account data: number and name.

pushname - display name in WhatsApp
number - authorized phone number
id - WhatsApp identifier in @c.us format

{
  "id":19,
  "whatsapp_id" : "191b80a9238",
  "event_action" : "ready",
  "event_date" : "2023-01-24 18:29:37",
  "status_code" : null,
  "event_data" :
  {
    "pushname": "John",
    "number" : "19991234567",
    "id" : "19991234567@c.us"
  }
}

Message

This event is sent for any incoming message in a chat or group. Field event_action contains “message”. Field event_data contains a message object.

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"message",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_19999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"19991112233@c.us",
       "to":"19999999999@c.us",
       "isForwarded":false
    }
  }
}

Sent

This event is sent after successful message delivery when an asynchronous send command was used.

Field event_action contains “sent”. Field event_data contains the delivered message object.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"sent",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_19999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"19999999999@c.us",
       "to":"19991112233@c.us",
       "isForwarded":false
    }
  }
}

Ack

This event is sent when a message status changes in a chat or group. Field event_action contains “ack”. Field event_data contains the message object whose status changed. Message status is in message field ack and can be: 1 - sent, 2 - delivered, 3 - read.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"ack",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_19999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"19999999999@c.us",
       "to":"19991112233@c.us",
       "isForwarded":false
    }
  }
}

Disconnect

This event is sent when the client disconnects and closes. This happens when you remove the client from your account dashboard or revoke the link in the WhatsApp mobile app. Field event_action contains “disconnect”. Field event_data contains an object with field reason describing the disconnect cause.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"disconnect",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "reason": "Client disconnected"
  }
}

Error

This event is sent when any error occurs. For example, when you try to send asynchronously to a number outside your contact list on the Light plan. Field event_action contains “error”. Field event_data contains an object describing the error.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"error",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "error":"Specified number not in your contact list"
  }
}

Create

This event is sent for any outgoing message in a chat or group. It lets you track sent messages via webhook, including messages sent from the mobile client or other linked applications.

Field event_action contains “create”.

Field event_data contains a message object.

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"create",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"true_19999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"19991112233@c.us",
       "to":"19999999999@c.us",
       "isForwarded":false
    }
  }
}

Message object

{
   "_id":"3EB0436AE1E682FF3A37",
   "id":"false_19999999999@c.us_3EB0436AE1E682FF3A37",
   "ack":1,
   "hasMedia":false,
   "mediaKey":"",
   "body":"212",
   "type":"chat",
   "timestamp":1662575377,
   "from":"19999999999@c.us",
   "to":"19991112233@c.us",
   "isForwarded":false,
   "quoted": {
       "_id": "3EB07621A4D08F9F59E0",
       "from": "19537226631@c.us",
       "type": "chat",
       "body": "Hello!"
   }
}

Message object fields:

_id - message identifier in WhatsApp.
id - WhatsApp message identifier that can be passed in the “quote” field to mark a message as a reply.
ack - (int) status flag showing message state: 1 - sent, 2 - delivered, 3 - read
hasMedia - flag indicating whether message contains a media file
mediaKey - media file key used in get-media to fetch media.
body - message text
type - message type
timestamp - message date in Unix timestamp format
from - sender identifier
to - recipient identifier
isForwarded - indicates whether the message was forwarded from another chat
quoted - if this message quotes (replies to) another message, quoted contains the quoted message object.
- _id - quoted message identifier
- from - quoted message author identifier
- type - quoted message type
- body - quoted message text

PHP code for webhook request handling

<?php
 
//buffer output
ob_start();
 
var_dump('----------------------' . date('d.m.Y H:i:s') . '----------------');
 
//extract request data
$input = file_get_contents('php://input');
$input_data = json_decode($input, true);
 
var_dump($input_data);
 
if($input_data['event_action'] == 'message') {
    //@TODO process incoming message
 
}
 
if($input_data['event_action'] == 'ack') {
 
    //@TODO process delivery or read status
 
    if($input_data['event_data']['message']['ack'] == 2) {
        //@TODO delivered
    }
    if($input_data['event_data']['message']['ack'] == 3) {
        //@TODO read
    }
}
 
//save log
$fo = fopen('webhook.log', 'a');
fwrite($fo, ob_get_clean());
fclose($fo);
 
//build and output response
$answer_data = [
    'id' => $input_data['id'],
    'result' => 'OK'
];
 
echo json_encode($answer_data);
?>