Creating a session via API

This command opens a WhatsApp session to link it to the service. After opening, you must authorize WhatsApp through the mobile app and QR code. If the session is no longer needed, close it using session-delete.

To create a session, send a POST request to:

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

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)

The request body must contain:

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

• 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

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.

The QR authorization window is available at:

https://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.

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://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://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