Set Chat Labels
Overwrite all labels for a specific chat.
Authentication Required
Login to swap the placeholders with your real Instance ID and Access Token.
Log InNo 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:
- Mass Migration: Instantly move a chat from "Outdated Campaign" tags to a new set of "Retention" tags.
- State Synchronization: Force the WhatsApp thread to match the exact state of your external CRM record.
- 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:
- Get Current: Call
GET /v2/labels/chats/{chatId}. - Filter: Locally add/remove the IDs you want.
- 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:
- Snapshot: Store the current label IDs in a
previousLabelsfield in your own database. - Delay: Wait 30 seconds.
- Rollback Option: If an agent realized they made a mistake, they can click "Undo," which calls this endpoint again with the
previousLabelsarray.
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
- Read Before Write (If Unsure): If you only want to add a label without losing existing ones, use the
Link Label to Chatendpoint instead. - Webhook Awareness: This operation will trigger both add and remove events for every change made. Ensure your webhook handlers can handle bursts of events.
- 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 Bodystring | 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 READYConnect Wawp API directly to Cursor, Windsurf, or Claude Desktop. Let AI write, test, and execute your WhatsApp integration code automatically!
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.
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.
Example
{
"ok": true
}Command Palette
Search for a command to run...