Session Management

Session Info

Retrieve complete information about a WhatsApp session, including connection status, authenticated user info, and server details.

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

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Poll this endpoint every 3-5 seconds while waiting for the user to scan the QR code.

  • Stop polling once the status becomes 'WORKING'.

  • Use this endpoint to build a 'System Status' page in your application dashboard.

The Pulse of the Engine: Decoding the Session Info Endpoint

The /v2/session/info endpoint is the most critical monitoring tool in your Wawp toolkit. It serves as the "Heartbeat" of your instance, providing real-time data on connection health, authentication state, and identity metadata. Mastering this endpoint is the key to building responsive, self-healing applications.

🔍 The Anatomy of a Status Response

The status field in the response is the primary director for your front-end logic. Understanding each state is essential:

1. WORKING (Active)

✅ The engine is fully connected to WhatsApp's servers and authenticated.

  • Developer Action: You are clear to send messages, fetch contacts, or update profile settings. No restrictions apply.

2. SCAN_QR_CODE (Authentication Pending)

⚠️ The engine is running but lacks valid credentials.

  • Developer Action: This is the only time the qr field in the response will contain a Base64 string. Display this QR code to the user immediately.
  • Pro Tip: QR codes expire rapidly (approx. 20-40 seconds). You must refresh your UI whenever a new QR string is returned by this endpoint.

3. STARTING (Warming Up)

⏳ The dedicated engine is booting and preparing the secure bridge.

  • Developer Action: Show a "Connecting..." spinner. Prevent the user from attempting to send messages until the state transitions.

4. STOPPED (Hibernating)

🛑 The instance is dormant. No system resources are being consumed.

🏗️ Monitoring Architecture: Best Practices

The "Intelligent Polling" Strategy

Polling is efficient if done correctly. We recommend the following orchestration for user-facing dashboards:

  1. Initial Check: When the user opens their dashboard, call /session/info.
  2. The QR Loop: If the status is SCAN_QR_CODE, poll every 3-5 seconds. This ensures the QR code on the screen is always "fresh" and detects the successful scan the moment it happens.
  3. The Stop Condition: Once the status transitions to WORKING, stop polling immediately to save network overhead and battery life on mobile clients.

Leveraging the "Me" Object

When a session is WORKING, the me object provides essential identity metadata:

  • pushName: Use this to welcome the user (e.g., "Welcome back, Sarah!").
  • platform: Understand if the user is connected via a specific OS, which can help in tailoring support if they report sync issues.

🛡️ Reliability and Health Monitoring

Building a "Health Check" Cron

For mission-critical bots, run a background task every 15 minutes that calls /session/info.

  • Auto-Recovery: If a session that should be active returns STOPPED or FAILED, your system should automatically trigger a start or restart call.
  • Alerting: If a session transitions to SCAN_QR_CODE unexpectedly, it means the user has logged out from their phone. Send them a push notification or email to re-link their account.

Troubleshooting Guide

Why is the QR field empty?

The qr field is context-aware. It will only contain data when the status is explicitly SCAN_QR_CODE. In any other state (like STARTING or WORKING), the field will be null or omitted because a handshake is either not ready or no longer needed.

Latency in Status Updates

While our engine is near real-time, there can be a 1-3 second delay as the WhatsApp handshake completes. If a session is stuck in STARTING for more than 60 seconds, it indicates a transient network failure. We recommend calling the /v2/session/restart endpoint to clear the state.

Summary of Capabilities:

  • Verify message-sending readiness.
  • Retrieve the latest QR or Pairing Code.
  • Identify the phone number and name of the connected account.
  • Monitor server-side resource allocation and engine health.

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 to check

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/info";
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 Samples
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 Info
Type:
application/json
string *
string *
object *
object *

Example

{
"name": "wawp-84729105",
"status": "WORKING",
"config": {
  "webhooks": {
    },
  "proxy": null
  },
"me": {
  "id": "201012345678@c.us",
  "pushName": "John Doe"
  }
}
Bad Request - Missing Required Parameter(s)
Unauthorized - Invalid or Missing Access Token
Not Found - Session Does Not Exist
Internal Server Error - Unexpected Failure
Bad Gateway - Connection Failed to Upstream
Previous TopicDelete Session
Next TopicAbout WhatsApp Data

Command Palette

Search for a command to run...