Labels

Update Label

Update an existing WhatsApp label's name or color.

PUT
https://api.wawp.net/v2/labels/{labelId}?access_token=123456789&color=0&instance_id=123456789&labelId=3&name=Very+Urgent

Authentication Required

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

Log In
Test /v2/labels/{labelId}/update endpoint
PUT
PUT

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Notify agents if a common label changes meaning (e.g., 'Red' becomes 'Low Priority').

  • Update the updated timestamp in your local database.

Label Evolution: Navigating Taxonomy Changes

As your business grows and your sales or support funnels mature, your organizational requirements will inevitably shift. The Update Label endpoint is designed to facilitate this evolution, allowing you to refine your terminology and visual hierarchy without severing existing conversation links.

🏗️ Core Concept: Non-Destructive Refinement

Unlike deleting and recreating a category—which would strip all metadata from your active chats—updating a label is a state-preserving operation. When you modify a label's name or color, every chat currently tagged with that record is instantly updated across the entire WhatsApp Business ecosystem.

The Power of Partial Updates

This endpoint follows a "Flexible Schema" approach. You are not required to provide both the name and the color for every request.

  • Terminological Shift: Use this to rename "Lead" to "Prospect" across 500+ chats in a single API call.
  • Priority Escalation: Keep the name "Follow-up" but change its color from Yellow to Red to instantly signal a high-priority state to your manual agent pool.

🚀 Strategic Operational Use Cases

1. Rebranding & Terminology Alignment

Organizations often settle on specific internal buzzwords that eventually change. Whether you are moving from a "Trial" based model to "Freemium" or simply correcting a typo in a high-visibility tag, the Update endpoint ensures your frontline agents always see the most professional and current terminology.

2. Visual Urgency Dynamic

A label's color is a powerful subconscious trigger. During peak periods (like a holiday sale), you might temporarily update the color of your "Shipping" label to a more aggressive index (e.g., Red or Orange) to ensure it stands out in the chat list. Once the peak passes, you can revert it to a more neutral blue or green.

3. Funnel Progression & Consolidation

If you find that two categories (e.g., "Web lead" and "App lead") have become redundant, you can rename one to "Digital Lead" and begin migrating the other's chats. This ensures a clean transition without losing historical context.

⚠️ Critical Behaviors & Atomic Logic

The "Stable ID" Principle

Even when a label's name changes from "Bug A" to "Fixed," its underlying ID never changes. This is critical for your internal reporting systems and databases. Your backend should always link metadata to the Label ID, allowing the name to remain a flexible "Display Attribute."

Duplicate Name Tolerance

WhatsApp allows for multiple labels to share the same name. If you update a label to match the name of an existing one, the system will not prevent the change. While this provides flexibility, it can lead to "UI Confusion."

  • Recommendation: Before executing an update, fetch your global label list and verify that the target name is not already in use by another ID. This maintains a clean and unique sidebar for your agents.

🛡️ Reliability & Webhook Orchestration

Any change to a label's metadata triggers the label.upsert webhook.

Synchronization Strategies

Your integration should use this webhook as a "Sync Trigger." When an agent renames a label manually in the WhatsApp Business app, your local database will receive the update event. This ensures that your CRM's "Tag View" always matches what the agent sees on their mobile device or desktop.

Managing Rate Limits

While metadata updates are lightweight, we recommend avoiding high-frequency "flapping" (e.g., changing a label's color 10 times a minute). Maintain a stable taxonomy to avoid hitting Meta's undocumented rate limits for account-wide metadata modifications.

🛠️ Integration Patterns: Enterprise Compliance

The Audit Blueprint

In regulated industries (like Finance or Healthcare), changing the meaning of a tag can have legal implications. We recommend logging the "Before" and "After" state of any update in your own audit logs, capturing the timestamp and the identity of the agent who initiated the change.

The "Maintenance Window" Rollout

When performing a large-scale re-architecture of your labels, perform the updates during low-traffic periods. This allows the changes to propagate through WhatsApp's global servers and ensures your local caches can be refreshed without impacting active conversation flows.

🎯 Best Practices

  1. Favor Consistency: Avoid frequent renames, as agents build "muscle memory" based on the text and position of labels in their sidebar.
  2. Color Hierarchy: Reserves Red indices for "Negative/Urgent" states and Green for "Success" states. Don't flip these meanings during an update.
  3. Invalidate Caches: After a successful update, instantly clear any local or Redis-based label caches to prevent your UI from showing stale terminology.
  4. Character Awareness: Always verify the new name is under the ~25 character limit to prevent truncation in the official WhatsApp app.

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 to update

Example:
string—

New name for the label

Example:
number—

New internal color number (0-19). E.g., 0=#ff9485, 1=#64c4ff, ... 19=#9368cf

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

Label updated successfully
application/json
string *
string *
number *
string *

Example

{
"id": "3",
"name": "Very Urgent",
"color": 0,
"colorHex": "#ff0000"
}
Bad Request - Invalid Parameter Format
Unauthorized - Invalid or Missing Access Token
Internal Server Error - Unexpected Failure
Previous TopicCreate Label
Next TopicDelete Label

Command Palette

Search for a command to run...