On very rare occasions, a session may hang in the "STARTING" state due to a network timeout at the WhatsApp bridge level. - Fix: If the status remains STARTING for more than 45 seconds, we recommend calling the /v2/session/restart endpoint to force a clean environment reset. ---

Start Session

Boots up the WhatsApp engine for a specific instance. This is the trigger that transitions a session from 'STOPPED' to 'STARTING'.

POST

https://api.wawp.net/v2/session/start?access_token=YOUR_ACCESS_TOKEN&instance_id=Your_Instance_ID

Authentication Required

Login to swap the placeholders with your real Instance ID and Access Token.

Log In

Test /v2/session/start endpoint

Supports

POSTGET

No query parameters required

This endpoint doesn't expect data in the URL.

Async Operation

This endpoint returns 'STARTING' immediately. The actual connection happens asynchronously in the background.

Best practices

Use the /v2/status endpoint to fetch the QR code once the state transitions to 'SCAN_QR_CODE'.
If you receive a 404 error, the 'instance_id' is likely incorrect or the instance was deleted.

Starting the Engine: The Deep Dive into /v2/session/start

If creating a session is like "registering a car," then calling /v2/session/start is the act of "turning the ignition." Without this step, your session is merely a passive record in our database, incapable of communicating with the WhatsApp network. This endpoint is the primary catalyst for the entire automation lifecycle.

🏗️ What Happens Technically During "Start"?

When you trigger a start request, Wawp orchestrates several high-concurrency operations:

Container Awakening: The isolated environment dedicated to your instance is powered on.
Library Initialization: The underlying WhatsApp libraries (Baileys/WAWebJS) are loaded into memory and configured with your instance's specific security parameters.
Network Handshake: The engine attempts to establish a secure WebSocket bridge between our high-performance nodes and WhatsApp's official servers.
Credential Fetching: If previous authentication exists, the engine attempts to "resume" the session. If not, it transitions to a state where it can generate a fresh QR code.

🛡️ Strategic Best Practices

1. The "State Check" Prerequisite

Never call start blindly. Always check the current status via /v2/session/info first.

The Ideal Condition: Only call start if the status is STOPPED.
The Risk: Calling start on a session that is already WORKING can cause a protocol conflict, potentially leading to a temporary disconnection or a "Session conflict" notice on the user's mobile device.

2. Handling the "Async" Nature

The start command is non-blocking. It will return a success response (200 OK) almost immediately, but the engine may still be "warming up" for several seconds.

Developer Action: Do not poll for a QR code immediately. Implement a 5-10 second "settle time" before your application starts aggressively checking for status changes.

3. "Warm Booting" for Better UX

In a production dashboard, don't wait for the user to click "Connect."

The Optimization: If you detect a user has logged into your CRM and their WhatsApp status is STOPPED, call start in the background. By the time they click on the WhatsApp integration tab, the engine will be ready to display a QR code, making the experience feel instantaneous.

💡 Industry-Standard Use Cases

A. Automated Re-connection Workers

Build a background "Watcher" service that runs every hour. If it finds a session that should be online (e.g., a "Gold Tier" customer) but has a status of STOPPED, it should trigger a start command automatically.

B. "Morning Boot" Scheduling

If your business only operates during specific hours, you can call /v2/session/stop at night to save system resources and call start 30 minutes before your agents start their shift.

⚠️ Common Errors and Troubleshooting

"Instance Not Found" (404 Not Found)

This occurs if the instance_id provided is incorrect or has been permanently deleted from our servers. Double-check your database persistence layer.

Stuck in "STARTING"

On very rare occasions, a session may hang in the "STARTING" state due to a network timeout at the WhatsApp bridge level.

Fix: If the status remains STARTING for more than 45 seconds, we recommend calling the /v2/session/restart endpoint to force a clean environment reset.

Summary of Responsibilities:

Power on the isolated WhatsApp engine.
Initiate the connection protocol with WhatsApp servers.
Transition the instance state from STOPPED to STARTING or WORKING.
Prepare the environment for QR code or Pairing code generation.

Request Parameters

Configure the parameters required to interact with this endpoint. All query and body arguments are listed below with their details.

Request Body

Sent as a JSON object

	`string`		The 12-character ID of the instance Example:
	`string`		Your API Access Token Example:

Request Samples

Use these ready-to-go code snippets to integrate our API into your project quickly and efficiently. Choose your preferred language and library.

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/session/start";
3const params = new URLSearchParams({
4  "instance_id": "Your_Instance_ID",
5  "access_token": "YOUR_ACCESS_TOKEN"
6}).toString();
7
8
9fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
10  method: "POST",
11  headers: { "Content-Type": "application/json" },
12  
13})
14  .then(async (response) => {
15    if (response.ok) {
16      const data = await response.json();
17      console.log("Success:", data);
18      return data;
19    }
20    
21    // Error Handling
22    if (response.status === 400) {
23      console.error("Error 400: Bad Request - Missing Required Parameter(s)");
24    }
25    if (response.status === 400) {
26      console.error("Error 400: Bad Request (XML Format)");
27    }
28    if (response.status === 400) {
29      console.error("Error 400: Bad Request (Plain Text)");
30    }
31    if (response.status === 401) {
32      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
33    }
34    if (response.status === 401) {
35      console.error("Error 401: Unauthorized (XML Format)");
36    }
37    if (response.status === 404) {
38      console.error("Error 404: Not Found - Session Does Not Exist");
39    }
40    if (response.status === 404) {
41      console.error("Error 404: Not Found (XML Format)");
42    }
43    if (response.status === 500) {
44      console.error("Error 500: Internal Server Error - Unexpected Failure");
45    }
46    if (response.status === 500) {
47      console.error("Error 500: Internal Server Error (HTML)");
48    }
49    if (response.status === 502) {
50      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
51    }
52    if (response.status === 502) {
53      console.error("Error 502: Bad Gateway (XML Format)");
54    }
55
56    const errorText = await response.text();
57    console.error(`Error ${response.status}: ${errorText}`);
58  })
59  .catch((error) => console.error("Network Error:", error));

Interactive SamplesUTF-8

Ln 59, Col 1javascript

Expected Responses

Explore all possible responses and outcomes from the server. We have documented each status code with data examples to make success and error handling easier.

Success - Boot Initiated

3 Variants

Type:

application/json

string *

object *

Example

{
"name": "wawp-84729105",
"status": "STARTING",
"config": {
  "webhooks": {
    },
  "proxy": null
  }
}

Bad Request - Missing Required Parameter(s)

3 Variants

Unauthorized - Invalid or Missing Access Token

2 Variants

Command Palette

Search for a command to run...