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.

To create a session, send a POST request to:

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

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

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