Set Chat Labels

Overwrite all labels for a specific chat.

PUT
https://api.wawp.net/v2/labels/chats/{chatId}?access_token=123456789&chatId=123456789%40c.us&instance_id=123456789&labels=%5B%221%22%2C+%222%22%5D

Authentication Required

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

Log In
Test /v2/labels/chats/{chatId}/set endpoint
PUTPOST

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Use 'add' endpoints instead if you want to preserve existing labels.

  • Validate all label IDs before sending the request.

Decisive State Management: Overwriting All Chat Labels

While adding and removing labels individually is useful for incremental updates, the Set Chat Labels endpoint is designed for Atomic State Transitions. It allows you to define the exact set of labels a chat should have, effectively overwriting any existing tags in a single operation.


🏗️ Core Concept

This endpoint is the primary tool for Full State Sync. Instead of calling "Add" three times and "Remove" twice to update a chat's context, you provide an array of all intended Label IDs (e.g., ["1", "2"]). WhatsApp will ensure those specific labels are applied and all others are removed.

Key Capabilities:

  1. Mass Migration: Instantly move a chat from "Outdated Campaign" tags to a new set of "Retention" tags.
  2. State Synchronization: Force the WhatsApp thread to match the exact state of your external CRM record.
  3. Atomic Updates: Ensure that a chat is never in an inconsistent state (e.g., having both "Active" and "Closed" labels at the same time).

🚀 Priority Use Cases

1. The CRM "Master Sync"

Every time a contact's status changes in your CRM, push the new reality to WhatsApp.

async function syncLabelsFromCRM(chatId, crmTags) {
  // Map CRM tags to WhatsApp Label IDs
  const labelIds = crmTags.map(tag => tagMap[tag]).filter(Boolean);
  
  // Force WhatsApp to match CRM exactly
  await api.setChatLabels(chatId, labelIds);
  console.log(`Synchronized labels for ${chatId}: ${labelIds.join(', ')}`);
}

2. Funnel Stage Transitions

When a user graduates from "Trial" to "Paid subscriber," you want to clear all "Trial-related" metadata and apply "Subscriber" metadata.

// Moving from Trial to Active
await api.setChatLabels(chatId, [subscriberLabelId, highValueLabelId]);
// All previous tags like "Trial Day 3", "Demo Scheduled" are wiped.

⚡ Technical Depth: Transactional Safety

Because this endpoint is destructive (it removes anything not mentioned), it should be treated with the same caution as a database UPDATE command.

The "Get-Modify-Set" Pattern

If you want to add a label while ensuring you strictly control the other labels, use this pattern:

  1. Get Current: Call GET /v2/labels/chats/{chatId}.
  2. Filter: Locally add/remove the IDs you want.
  3. Set: Call this endpoint with the final array.

This is safer than incremental calls in high-latency environments where multiple systems might be trying to tag the same chat.


�️ Reliability & Webhook Orchestration

Every Label ID added or removed during this operation will trigger a corresponding webhook event.

Webhook Noise Management

If your system listens to label.chat.added, setting 5 labels at once will fire 5 webhooks.

  • Recommendation: Disable automated logic for a specific chat ID for 5-10 seconds after calling this endpoint to allow the "dust to settle" on the remote WhatsApp account.
  • Idempotency: If you set the same labels the chat already has, no webhooks will fire, making this a safe operation to run on a daily sync cron job.

🛠️ Integration Patterns: Advanced State Sync

Multi-Agent "Locking" System

Use a specific "Locked by [Agent Name]" label. When an agent grabs a chat, use this endpoint to remove "Unassigned" and add "Locked by Agent X" in one atomic jump.

The "Clean Slate" Pattern

To remove all labels from a chat without deleting the labels themselves, simply send an empty array:

await api.setChatLabels(chatId, []);

⚠️ Important Behaviors & Edge Cases

  • Destructive Overwrite: Any Label ID not included in your request will be removed from the chat. Use with caution.
  • Array Limit: While you can theoretically send many IDs, keep the array to a reasonable size (<20) as WhatsApp only supports a limited number of labels per account.
  • Validation: If you provide a non-existent Label ID in the array, the entire request may fail with a 400 Bad Request. Always verify your Label IDs before setting.

� Disaster Recovery & Rollback Strategies

Because this endpoint is destructive, having a "safety net" is a recommended architectural pattern.

Implementing a "Soft Delete" Buffer

Before calling this endpoint to clear labels:

  1. Snapshot: Store the current label IDs in a previousLabels field in your own database.
  2. Delay: Wait 30 seconds.
  3. Rollback Option: If an agent realized they made a mistake, they can click "Undo," which calls this endpoint again with the previousLabels array.

Visual State Verification

After every set operation, we recommend calling GET /v2/labels/chats/{chatId} one last time to verify the WhatsApp server has correctly applied the changes. This ensures your frontend is never out of sync with Meta's actual state.


�🎯 Best Practices

  1. Read Before Write (If Unsure): If you only want to add a label without losing existing ones, use the Link Label to Chat endpoint instead.
  2. Webhook Awareness: This operation will trigger both add and remove events for every change made. Ensure your webhook handlers can handle bursts of events.
  3. Use for "Single View" Dashboards: This is the best endpoint for UIs that allow agents to select multiple tags from a list and click "Save Changes."

Request Parameters

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

Query Parameters & Request Body

Supported in URL Query String or JSON Body
string

Your unique WhatsApp Instance ID

Example:
string

Your API Access Token

Example:
string

The unique ID of the chat (e.g., 123456789@c.us)

Example:
string[]

Array of label IDs to assign (overwrites existing ones)

Example:

Build with AI using Wawp MCP

MCP READY

Connect Wawp API directly to Cursor, Windsurf, or Claude Desktop. Let AI write, test, and execute your WhatsApp integration code automatically!

How to Connect

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/chats/123456789@c.us";
3const params = new URLSearchParams({
4 "instance_id": "123456789",
5 "access_token": "123456789"
6}).toString();
7const body = {
8 "labels": [
9 "1",
10 "2"
11 ]
12};
13
14fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
15 method: "PUT",
16 headers: { "Content-Type": "application/json" },
17 body: JSON.stringify(body)
18})
19 .then(async (response) => {
20 if (response.ok) {
21 const data = await response.json();
22 console.log("Success:", data);
23 return data;
24 }
25
26 // Error Handling
27 if (response.status === 401) {
28 console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
29 }
30 if (response.status === 400) {
31 console.error("Error 400: Bad Request - Invalid Parameter Format");
32 }
33 if (response.status === 500) {
34 console.error("Error 500: Internal Server Error - Unexpected Failure");
35 }
36
37 const errorText = await response.text();
38 console.error(`Error ${response.status}: ${errorText}`);
39 })
40 .catch((error) => console.error("Network Error:", error));
Interactive Samples
Ln 40, 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.

Labels updated successfully
application/json
boolean *

Example

{
"ok": true
}
Bad Request - Invalid Parameter Format
Unauthorized - Invalid or Missing Access Token
Internal Server Error - Unexpected Failure
Previous TopicGet Chat Labels
Next TopicGroups Overview

Command Palette

Search for a command to run...