Chat Actions

Chats list & overview

Get a list of all active chats (individuals and groups) with pagination support.

GET
https://api.wawp.net/v2/chats?access_token=YOUR_ACCESS_TOKEN&instance_id=123456789&limit=20&offset=0&sortBy=id&sortOrder=DESC

Authentication Required

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

Log In
Test /v2/chats endpoint
GETPOST

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Consult the official documentation for detailed parameter descriptions.

  • Test endpoints in a sandbox environment before production.

  • Keep your API client library up to date.

Chat List & Management

Retrieve an overview of all conversations currently available in your WhatsApp instance.

🛡️ Best Practices

Mastering the Inbox: High-Scale Chat Retrieval and Synchronization

The /v2/chats endpoint is the administrative gateway to your WhatsApp instance's history. Unlike the overview endpoint, which provides a snapshot, the Chats List API is designed for exhausive discovery and deep synchronization. Whether you are migrating data to a new CRM or building a searchable archive, mastering the nuances of this endpoint is essential for professional WhatsApp integrations.

🏗️ The Mechanics of Chat Discovery

When you request the chat list, the Wawp engine interfaces with its internal encrypted database to reconstruct the conversation graph. This process involves:

  1. Hydration: Associating the raw JIDs (e.g., 201234567890@c.us) with their display names and latest status.
  2. State Categorization: Identifying which chats are "Pinned," "Archived," or "Muted."
  3. Pagination Processing: Calculating the offset and limit logic to deliver a deterministic subset of results.

🚀 Advanced Pagination and Indexing Strategies

In high-volume accounts (5,000+ chats), requesting the "full list" is an anti-pattern that leads to memory spikes and network latency. Follow these professional guidelines:

1. The "Sliding Window" Sync

If you are synchronizing your local database with Wawp for the first time:

  • Phase 1: Fetch the first 50 results (limit=50, offset=0) to get the most recent activity.
  • Phase 2: Use a recursive loop to fetch subsequent pages (offset=50, 100, ...) until the response array is empty.
  • Interrupt Resilience: Store the last successful offset in your local database so you can resume the sync if the connection drops.

2. Strategic Sorting

  • sortBy=id: Useful for alphabetical indexing or consistency checks.
  • sortOrder=DESC: The default and most recommended setting. It ensures that the newest threads — those most likely to require immediate attention — are returned first.

🛡️ Best Practices for Efficient Polling

While Webhooks are the preferred way to receive new messages, the /v2/chats endpoint remains the source of truth for chat state changes (like a user changing their group name or archiving a thread).

  • The Delta Sync: Instead of polling the whole list, poll only the first page (limit=20) every hour. If you detect a change in a chatId that your system didn't know about, trigger a deep dive for that specific conversation.
  • Archiving Policy: To keep this list manageable, implement an auto-archiving script. Use the chat list to identify "Zombie" chats (no messages for 90 days) and call the archive endpoint to move them out of the "Active" list.

🧩 Advanced Use Cases

Building a "WhatsApp Explorer"

Create a custom search interface for your team.

  • Logic: Fetch the entire chat list (paginated) and index the name and id fields in an ElasticSearch or Meilisearch instance. This allows your support agents to find any customer instantly without waiting for the engine to respond.

Bot "Self-Audit"

In a multi-bot environment, use this endpoint to ensure that your bot hasn't been "orphaned" in groups it shouldn't be in. Regularly scan the list for unknown group IDs (@g.us) and programmatically leave them.

⚠️ Important Considerations

  • Engine Restarts: During an engine "Cold Boot," the chat list may take a few seconds to populate as it re-syncs with the phone's encrypted storage. Handle 202 Accepted or empty responses gracefully during the first 30 seconds of a session.
  • Group Permissions: For groups, this endpoint returns the group metadata available to your instance. If you were removed from a group, it may still appear in the list for a short "grace period" before disappearing.
  • Memory Management: Each chat object in the response occupies a small amount of memory. In very large requests (e.g., limit=500), ensure your application layer (Node.js/Python) has sufficient heap space to parse the JSON payload.

Summary of Capabilities:

  • Exhaustive retrieval of all chat threads (Individuals and Groups).
  • Deterministic pagination for large-scale data migrations.
  • Support for custom sorting to prioritize active conversations.
  • Reliable metadata retrieval for CRM and Database indexing.

Request Parameters

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

URL Parameters

Passed in the URL query string
string

Your unique WhatsApp Instance ID

Example:
string

Your API Access Token

Example:
string—

Field to sort by (e.g., id)

Example:
string—

Sort direction (ASC or DESC)

Example:
number—

Number of chats to return

Example:
number—

Number of chats to skip

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/chats";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "YOUR_ACCESS_TOKEN",
6  "sortBy": "id",
7  "sortOrder": "DESC",
8  "limit": "20",
9  "offset": "0"
10}).toString();
11
12
13fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
14  method: "GET",
15  headers: { "Content-Type": "application/json" },
16  
17})
18  .then(async (response) => {
19    if (response.ok) {
20      const data = await response.json();
21      console.log("Success:", data);
22      return data;
23    }
24    
25    // Error Handling
26    if (response.status === 400) {
27      console.error("Error 400: Bad Request - Missing Required Parameter(s)");
28    }
29    if (response.status === 400) {
30      console.error("Error 400: Bad Request (XML Format)");
31    }
32    if (response.status === 400) {
33      console.error("Error 400: Bad Request (Plain Text)");
34    }
35    if (response.status === 401) {
36      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
37    }
38    if (response.status === 401) {
39      console.error("Error 401: Unauthorized (XML Format)");
40    }
41    if (response.status === 404) {
42      console.error("Error 404: Not Found - Session Does Not Exist");
43    }
44    if (response.status === 404) {
45      console.error("Error 404: Not Found (XML Format)");
46    }
47    if (response.status === 500) {
48      console.error("Error 500: Internal Server Error - Unexpected Failure");
49    }
50    if (response.status === 500) {
51      console.error("Error 500: Internal Server Error (HTML)");
52    }
53    if (response.status === 502) {
54      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
55    }
56    if (response.status === 502) {
57      console.error("Error 502: Bad Gateway (XML Format)");
58    }
59
60    const errorText = await response.text();
61    console.error(`Error ${response.status}: ${errorText}`);
62  })
63  .catch((error) => console.error("Network Error:", error));
Interactive Samples
Ln 63, 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 - Request completed successfully
Type:
application/json
boolean *
string *

Example

{
"success": true,
"message": "Operation completed successfully"
}
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 TopicChat Management
Next TopicGet Chats Overview

Command Palette

Search for a command to run...