1. Webhook-Triggered Audits: Avoid high-frequency polling. Instead of checking this endpoint every 5 minutes, use the label.chat.added webhook to keep a local, incremental list of chat associations. 2. Verify Label Vitality: Before querying for chats, ensure the Label ID is still active. Querying a deleted ID will re

Get Chats with Label

Get a list of chats associated with a specific label.

GET

https://api.wawp.net/v2/labels/{labelId}/chats?access_token=123456789&instance_id=123456789&labelId=1

Authentication Required

Test /v2/labels/{labelId}/chats endpoint

Supports

GET

No query parameters required

This endpoint doesn't expect data in the URL.

Aggregation

Often used to get a count of chats per label.

Dashboard

Great for visualizing workload (e.g., 'Pending Support Tickets').

Best practices

Cache the counts and update only when webhook events occur.
Use charts to display label distribution for supervisors.

Targeted Retrieval: Mastering Category-Based Filtering

The Get Chats with Label endpoint is the primary bridge between your organizational taxonomy and your communication workflow. It allows you to filter your entire conversation history by a specific Label ID, returning a lean list of chat identifiers and names that belong to that category.

🏗️ Core Concept: Category-Based Batch Processing

This endpoint enables high-efficiency retrieval by offloading the filtering logic to Wawp's core servers. Instead of your system iterating through thousands of individual chat logs to identify "Stale Leads" or "VIPs," you can retrieve a pre-filtered list in a single, optimized API request.

Key Strategic Capabilities:

Mass Outreach Orchestration: Instantly identify all participants in a specific marketing campaign or product launch for targeted broadcasts.
Workflow Throughput Auditing: Measure the "State Density" of your funnel—such as how many chats are currently bottlenecked in the "Payment Failure" or "Escalated" states.
CRM State Synchronization: Pull segmented lists of contacts to ensure your external CRM dashboards reflect the real-time visual categorization seen by your WhatsApp agents.

🚀 Priority Operational Use Cases

1. The Proactive Retention Cycle

By regularly querying labels like "Pending Follow-up" or "Day 3 Trial," your system can identify users who have entered a period of inactivity. This allows you to trigger automated re-engagement messages or move them to a different "Nurture" category to prevent lead decay.

2. Segmented Sentiment Analysis

In high-volume accounts, auditing every message is impossible. This endpoint allows you to focus your analytical resources on the most critical segments. By fetching only the chats tagged "Dissatisfied" or "Urgent," you can run targeted sentiment analysis to identify systemic issues before they escalate.

3. Queue Management & Load Balancing

If you use labels to assign chats to specific departments (e.g., "Sales Queue," "Support Tier 2"), this endpoint provides the headcount per queue. This data is essential for dynamic resource allocation, allowing you to move agents between departments based on real-time conversation volume.

⚖️ Scalability & Big Data Architecture

For enterprise accounts with tens of thousands of conversations, the management of label lists requires an optimized approach to prevent memory exhaustion and timeout errors.

Managing High-Volume Lists

While this endpoint is designed for speed, retrieving a list of 5,000+ chats can be tax the CPU of smaller server instances.

The Cursor-Free Pattern: This endpoint returns the full current list for a label. To maintain performance, we recommend immediately streaming this data into a background processing queue (such as Redis or RabbitMQ) rather than attempting to process it inside the main HTTP request loop.
Memory Hygiene: If you are operating in a resource-constrained environment (like a Lambda function or an Edge Worker), avoid storing the entire array in memory; process the results as a stream of IDs to minimize your memory footprint.

🛡️ Data Integrity & Compliance

PII Sensitivity & GDPR

The names returned by this endpoint are the contact names as they appear in the WhatsApp account's address book.

Data Minimization: Never fetch full chat lists and store them indefinitely. Retrieve the list only when you have an immediate action to perform, and dispose of the identifiers once the operation is complete.
Real-Time Reflection: The list is a snapshot of the current state. Because agents can add/remove labels in the WhatsApp mobile app at any time, treat the data as highly transient.

🎯 Best Practices

Webhook-Triggered Audits: Avoid high-frequency polling. Instead of checking this endpoint every 5 minutes, use the label.chat.added webhook to keep a local, incremental list of chat associations.
Verify Label Vitality: Before querying for chats, ensure the Label ID is still active. Querying a deleted ID will result in an empty list, which your system might incorrectly interpret as "Zero active leads."
Hybrid Enrichment: Use the lean IDs returned here as a "Filter Key." If you need more data (like profile pictures or BIOs), pass these IDs to the Get Contact Info endpoint in small batches to build a rich, visual dashboard.

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`		The unique ID of the label 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/labels/1/chats";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "123456789"
6}).toString();
7
8
9fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
10  method: "GET",
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 === 401) {
23      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
24    }
25    if (response.status === 500) {
26      console.error("Error 500: Internal Server Error - Unexpected Failure");
27    }
28
29    const errorText = await response.text();
30    console.error(`Error ${response.status}: ${errorText}`);
31  })
32  .catch((error) => console.error("Network Error:", error));

Interactive SamplesUTF-8

Ln 32, 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.

List of chats retrieved successfully

application/json

object *

Example

{
"0": {
  "id": "123456789@c.us",
  "name": "John Doe"
  }
}

Unauthorized - Invalid or Missing Access Token

Internal Server Error - Unexpected Failure