Remember that a STOPPED session is effectively "offline." - The Warning: You will not receive any message or status webhooks while an instance is stopped. WhatsApp's servers will buffer incoming messages for a limited time (usually 24-72 hours), but prolonged hibernation may lead to message loss once their internal TT

Stop Session

Gracefully shuts down the WhatsApp engine for an instance without logging it out. Used to save resources or restart a stuck session.

POST

https://api.wawp.net/v2/session/stop?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/stop endpoint

Supports

POSTGET

No query parameters required

This endpoint doesn't expect data in the URL.

Data Persistence

Stopping a session DOES NOT delete your authentication data. You can restart it anytime without re-scanning the QR code.

Best practices

Use this endpoint to reboot a session if it gets stuck.
Implement an idle-timer in your app to auto-stop sessions that haven't been used for 24+ hours.

Controlled Hibernation: The Power of the /v2/session/stop Endpoint

The /v2/session/stop endpoint is the specialized "Pause" button for your WhatsApp instance. Unlike a deletion, which wipes the slate clean, a "Stop" command puts your engine into a state of Controlled Hibernation. It preserves your authentication data and settings while releasing the underlying compute resources on our high-performance infrastructure.

🏗️ The Technical Lifecycle of a Stopped Session

When you initiate a stop command, Wawp executes a series of clean-up operations:

Queue Flushing: The engine attempts to finalize any outbound transmission tasks currently in the buffer.
Library Shutdown: The WhatsApp-bridge process is signaled to disconnect and save its internal state.
Container Freezing: The isolated environment is paused, meaning it consumes 0% CPU and RAM on our nodes, allowing us to maintain a more efficient and cost-effective ecosystem for you.
Data Persistence: Crucially, your Session Keys and Encryption Secrets are kept in secure persistent storage. This ensures that when you restart, no fresh QR scan is required.

🛡️ Strategic Best Practices

1. Resource Optimization

If you are a SaaS provider with thousands of instances, leaving every session running 24/7 is inefficient.

The Idle-Shutdown Strategy: Monitor your sessions. If a user has been inactive for 72 hours, call /v2/session/stop. This keeps your billing predictable and your dashboard organized.

2. The "Clean Reboot" Sequence

Sometimes, the underlying WhatsApp WebSocket can become "de-synced" from the mobile device.

The Fix: Instead of calling /v2/session/logout, try a sequence of stop followed by start. This forces the engine to reload its libraries and establish a fresh connection to the WhatsApp servers, often resolving transient issues.

3. Webhook Awareness

Remember that a STOPPED session is effectively "offline."

The Warning: You will not receive any message or status webhooks while an instance is stopped. WhatsApp's servers will buffer incoming messages for a limited time (usually 24-72 hours), but prolonged hibernation may lead to message loss once their internal TTL (Time-To-Live) expires.

💡 Industry-Standard Use Cases

A. Nightly Maintenance

For businesses that operate only during local business hours (e.g., a support desk open 9 AM - 5 PM), you can schedule a script to stop all support instances at 6 PM. This provides a clear "Offline" signal to anyone trying to message the business outside of hours.

B. Scalability Management

In a multi-agent environment, where agents log in and out throughout the day, use this endpoint to stop an agent's dedicated instance when they clock out. This ensures that no automated replies or background processes are running while the human agent is away.

⚠️ Common Pitfalls and Troubleshooting

"Instance Not Found" (404)

This error occurs if the session was deleted before the stop command was issued. Ensure your front-end logic respects the sequence of operations.

Delay in Restarting

After calling stop, we recommend waiting at least 3 seconds before calling start again. This gives our cloud orchestrator enough time to fully decommission the previous container before Spinning up a new one.

Summary of Capabilities:

Gracefully disconnect from WhatsApp servers.
Preserve all authentication and QR scan data for future use.
Optimize infrastructure resource consumption.
Provide a "Pause" state for maintenance or off-peak hours.

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/stop";
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 - Session Stopped

3 Variants

Type:

application/json

string *

object *

Example

{
"name": "wawp-84729105",
"status": "STOPPED",
"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...