1. Action-Oriented Taxonomy: Use names like "To Follow Up" or "Needs Manager" instead of passive nouns. Labels should imply an action. 2. Visual Consistency: Leverage the color indices to create an urgency hierarchy. Reserve Reds for high-priority tagging. 3. Batching at Scale: When tagging a large segment of users

Link Label to Chat

Assign a specific label to a chat or contact.

PUT

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} endpoint

Supports

PUT

No query parameters required

This endpoint doesn't expect data in the URL.

Capacity

A chat can have multiple labels (up to 20).

Automation

Labels are excellent triggers for automated workflows.

Best practices

Add a 'Bot Handled' label to chats your bot is managing.
Use labels to track the customer journey (e.g., Lead, Qualified, Closed).

Tagging Conversations: Mastering Semantic Orchestration

The Link Label to Chat endpoint is the primary mechanism for attaching strategic metadata to individual or group conversations. This is not merely a "visual tag"; it is a programmatic state-marker that allows your CRM, bots, and agents to interact with conversations based on their current business value or urgency.

🏗️ Core Concept: Metadata at the Conversation Edge

Think of labels as ** dynamic attributes ** that move a chat through your internal processing pipeline.

Key Architectural Principles:

** Additive Metadata **: A single chat can carry multiple labels simultaneously(e.g., "VIP" + "Pending Payment" + "Assigned to Team A").This allows for multi - dimensional filtering.
** Idempotency by Design **: Linking the same label to the same chat multiple times has zero side effects.This makes it safe to include tagging calls in high - frequency event loops without fear of duplication or errors.
** Silent Context **: Tagging is a purely internal operation.The customer never sees the labels, and no notification is sent to their device.It is a "Private Channel" for your organizational logic.

🚀 Strategic Operational Use Cases

1. Funnel State Management

Use this endpoint to move contacts through your sales funnel.As a user progresses from an "Inbound Lead" to a "Qualified Prospect," your system should link the relevant labels to reflect their increasing value.This allows your sales team to instantly prioritize their inbox based on funnel depth.

2. Auto - Tagging Intelligence

By integrating your messaging history with a sentiment analysis engine or a keyword detector, you can programmatically tag chats.

** Urgency Detection **: Automatically link an "Urgent" label if a user mentions "ASAP" or "Help."
** Intent Categorization **: Tag conversations as "Billing," "Support," or "Sales" based on the initial inbound message, ensuring they are routed to the correct department immediately.

3. CRM & System Synchronization

Mirror the state of your external CRM.If a lead's status is updated in Salesforce or HubSpot, use this endpoint to ensure that the agent looking at the WhatsApp app sees the exact same status in real-time. This "Side-by-Side Synchronization" prevents data silos and agent confusion.

🛠️ Integration Patterns: Orchestrating Clean Transitions

The "Step-Up" Transition

When moving a chat to a new state(e.g., from "Pending" to "Approved"), we recommend a "Link then Prune" pattern.First, link the new "Approved" label, then use the[Unlink endpoint](/v2/labels / { id } / chats / { chatId }) to remove the old "Pending" state.This ensures the chat is never without a category during the transition.

Event - Driven Tagging

Trigger tagging based on external business events.For example, when a payment is processed in your billing system, instantly link the "Paid" label to the customer's WhatsApp chat. This provides immediate visual confirmation to any agent who might be interacting with that customer.

🧪 Advanced Operational Safeguards

Scalability with Groups

This endpoint fully supports WhatsApp Group Chats(@g.us). This is powerful for B2B workflows where you might tag an entire project room as "Active" or "On Hold."

Handling the "ID Drift"

Always verify that the Label ID you are attempting to link is active in your global account directory. If a label has been deleted from the account, attempts to link it will result in a 404 error. Your system should listen for label.deleted events to prevent "Ghost Tagging" attempts.

⚡ Webhook Orchestration

Every successful link operation triggers a label.chat.added event. You can use this to:

Trigger Notifications: Push a high-priority browser notification to an agent's dashboard.
Launch Automations: Start a specific drip campaign or bot sequence when a "Warm Lead" label is applied.

🎯 Best Practices

Action-Oriented Taxonomy: Use names like "To Follow Up" or "Needs Manager" instead of passive nouns. Labels should imply an action.
Visual Consistency: Leverage the color indices to create an urgency hierarchy. Reserve Reds for high-priority tagging.
Batching at Scale: When tagging a large segment of users (e.g., after a mass broadcast), implement a slight delay or use a background queue to ensure smooth propagation across Meta's servers.
Prune Redundancy: Don't let chats accumulate 10+ labels. Maintain "Metadata Hygiene" by removing old stage labels as new ones are added.

Request Parameters

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

Request Body

Sent as a JSON object

	`string`		Your unique WhatsApp Instance ID Example:
	`string`		Your API Access Token Example:
	`string`		The unique ID of the label Example:
	`string`		Target phone number or group ID (@c.us, @g.us) 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/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: "PUT",
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 SamplesUTF-8

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

3 Variants

Type:

application/json

boolean *

string *

Example

{
"success": true,
"message": "Operation completed successfully"
}

Bad Request - Missing Required Parameter(s)

3 Variants

Unauthorized - Invalid or Missing Access Token

2 Variants

Command Palette

Search for a command to run...