Unlink Label from Chat

Remove a specific label from a chat or contact.

DELETE
https://api.wawp.net/v2/labels/{id}/chats/{chatId}?access_token=123456789&chatId=201234567890%40c.us&id=1&instance_id=123456789

Authentication Required

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

Log In
Test /v2/labels/{id}/chats/{chatId}/delete endpoint
DELETEPOST

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Remove 'New' labels as soon as an agent replies.

  • Periodically audit old chats to remove stale labels.

Untagging Conversations: Mastering Taxonomy Pruning

The Unlink Label from Chat endpoint is the critical counterpart to the tagging process. It allows you to prune obsolete or resolved metadata from a conversation, ensuring that your agents' inbox remains clutter-free and that your automation engines are operating on the most current state of the relationship.


🏗️ Core Concept: State De - escalation

Removing a label is the programmatic equivalent of ** resolving a state ** or ** transitioning a stage **.

Key Operational Characteristics:

  • ** Non - Destructive Association **: Unlinking a label from a chat only removes the relationship.The label itself remains untouched in your global account directory, ready to be applied to other conversations.
  • ** Targeted State Removal **: Unlike a broad "Clear All," this endpoint allows for surgical removal of a specific attribute(e.g., removing "Urgent" while keeping "Assigned to Bob").
  • ** Idempotency & Silent Execution **: Attempting to remove a label that isn't currently linked to the chat will result in a success response with no side effects. No notification is ever sent to the customer, maintaining the privacy of your internal organizational logic.

🚀 Strategic Operational Use Cases

1. Funnel Progression Hygiene

As a customer moves deeper into your sales or support funnel, their previous stages often become irrelevant.For example, once a "New Lead" becomes a "Qualified Prospect," the "New Lead" label should be unlinked.This keeps the visual interface focused on the * next required action * rather than the conversation's history.

2. Auto - Cleanup of "Stale" Metadata

In high - volume accounts, labels can accumulate over time, leading to "Metadata Bloat." Use this endpoint in conjunction with a background cron job to automatically unlink "Temporary" or "Inquiry" labels after a set period of inactivity(e.g., 7 days).This ensures that only active, high - priority conversations carry visual markers.

3. User - Triggered Opt - Outs

If you use labels to manage internal broadcast segments(e.g., "Marketing Opt-In"), use this endpoint to honor customer requests to stop communications.When a user sends a "Stop" message, your bot can instantly unlink the marketing label, immediately removing them from any future automated outreach lists.


🛠️ Integration Patterns: Orchestrating Move Sequences

The "Link-then-Prune" Strategy

When a conversation state changes(e.g., from "Billing Inquiry" to "Resolved"), we recommend a two - step orchestration:

  1. ** Add the Destination State **: Link the "Resolved" label.
  2. ** Remove the Origin State **: Unlink the "Billing Inquiry" label. This ensures that the chat always carries at least one visual marker during the transition period, preventing the conversation from "disappearing" from filtered views in the agent dashboard.

Mass Decategorization

After a specific campaign or event(e.g., "Webinar Q3") is concluded, you can use this endpoint to clear the campaign markers from thousands of chats.By unlinking the campaign label, you effectively reset those conversations for the next cycle without deleting the record of the interaction itself.


🛡️ Data Integrity & Reliability

Handling ID Sensitivity

Always ensure that the Label ID you are unlinking is a valid string from your current account directory.If you attempt to unlink an ID that has been globally deleted, the API will return a 404 error.We recommend listening for label.deleted webhooks to keep your internal ID mappings clean.


🎯 Best Practices

  1. Avoid Label Overload: Maintain a "Strict Limit" policy for your chats. If a chat has more than 3 labels, it usually indicates that the previous stage markers haven't been properly unlinked.
  2. State-Driven Transitions: Make unlinking a core part of your bot's logic. If a bot finishes a collection flow, it should unlink the "Collecting Info" label as its final act.
  3. Real-Time Synchronization: Ensure your CRM's "Delete Tag" event or "Status Change" trigger is mapped to this endpoint. This keeps the agent's view in WhatsApp perfectly synchronized with the source of truth in your business database.
  4. Audit the Removal: Log every unlinking operation in your internal audit trails to track how long conversations typically spend in a specific "Labeled State."

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

Target phone number or group ID (@c.us, @g.us)

Example:
string

The unique ID of the label

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/1/chats/201234567890@c.us";
3const params = new URLSearchParams({
4 "instance_id": "123456789",
5 "access_token": "123456789"
6}).toString();
7
8
9fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
10 method: "DELETE",
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 - 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 TopicLink Label to Chat
Next TopicGet Chat Labels

Command Palette

Search for a command to run...