Create Label

Create a new WhatsApp label with a name and optional color.

POST

https://api.wawp.net/v2/labels?access_token=123456789&color=0&instance_id=123456789&name=Urgent

Authentication Required

Test /v2/labels/create endpoint

Supports

POST

No query parameters required

This endpoint doesn't expect data in the URL.

Building Your Taxonomy: Creating Labels

Establishing a robust labeling system is the first step toward transforming your WhatsApp Business account from a simple messaging tool into a structured, metadata-driven customer service platform. The Create Label endpoint serves as the fundamental architect for this transformation, allowing you to define the semantic categories that will govern your conversational workflows.

🏗️ Architectural Philosophy: Designing a Scalable Taxonomy

When you create a label, you are not just naming a folder; you are defining a State or Attribute that a conversation can possess. Because WhatsApp limits each account to 20 labels, every entry in your taxonomy must be strategic, versatile, and high-impact.

The "Label Blueprint" Strategy

A well-designed label system should focus on three core pillars:

Workflow Stage: Indicating where the customer is in their journey (e.g., "New Lead", "In Negotiation").
Visual Urgency: Using the color system to signal the need for immediate action.
Ownership & Responsibility: Defining who or what (e.g., a specific department or bot) is currently managing the thread.

🎨 The Color System: Visual Intelligence for Agents

The WhatsApp labeling interface is a highly visual environment. The 20-color palette (indexed 0-19) is designed to minimize cognitive load for agents who are managing dozens of simultaneous threads.

The Strategic Color Map

Indices 0 & 13 (High Urgency Reds): Reserved for critical escalations, potential churn risks, or time-sensitive breaches.
Indices 1 & 14 (Operational Blues): Ideal for active workstreams, informational updates, or mid-funnel leads that require consistent but not immediate engagement.
Indices 9 & 15 (Positive Greens): Used for "Closed Won" status, verified payments, or successfully resolved support tickets.
Index 2 (Yellow): Represents a "Pending" or "Waiting" state—usually where the ball is in the customer's or a third-party's court.
Index 4 (Grey): Best for "Cold" leads, "Nurture" campaigns, or archived threads that shouldn't distract the agent's main focus.

[!IMPORTANT] Engineering Tip: While the API returns a colorHex, tips: [ { type: 'info', title: 'Color', content: 'Supports standard WhatsApp color indices (0-19).' }, { type: 'info', title: 'Limits', content: 'You can create up to 20 unique labels per account.' } ], recommendations: [ "Establish a naming convention across your organization.", "Use distinct colors for high-priority vs low-priority items." ]

your system should rely exclusively on the Color Index (0-19) for logic. The hex values may shift slightly across different device versions or WhatsApp themes, but the index mapping is the immutable link to Meta's UI.

📏 Naming Conventions & Standardizations

To ensure your labels are as effective in the mobile app as they are in your custom CRM, follow these naming standards:

Character Economy: WhatsApp enforces a ~25 character limit. Names like "High Priority Support Request Assigned to Alice" will be truncated in the UI, rendering them useless. Use "Urgent: Alice" instead.
Action-Oriented Naming: Use labels that describe a state or a needed action. "Invoice" is a noun; "Invoice Sent" or "Pay Pending" are actionable states.
Semantic Consistency: Avoid using "Label" in the name. "VIP Label" is redundant when the UI already places the name in a colored badge.

🚀 Advanced Operational Use Cases

1. Sales Funnel Orchestration

Instead of manual tracking, use label creation to build a dynamic funnel. You might define stages starting from "Initial Inquiry" through "Discovery Call" and "Proposal" down to "Closed." By programmatically maintaining these labels, your reporting systems can calculate conversion rates simply by counting chat distribution across these IDs.

2. Team & Department Routing

In large organizations, labels act as the "Routing Meta" for incoming threads. You can create specialized labels for "Technical Support," "Billing," and "Sales." When a customer hits a specific branch in your IVR/Bot, your system ensures the correct label exists and applies it, instantly notifying the correct department's monitoring team.

3. Campaign & Event Tracking

For seasonal events (e.g., "Black Friday Sale" or "Product Launch X"), temporary labels allow you to isolate performance data. Once the campaign is over, these labels can be archived or deleted to free up space for the next cycle.

⚠️ Scaling Beyond the 20-Label Limit

The 20-label limit is a frequent challenge for high-growth businesses. If your system requires more than 20 categories, we recommend the following "Expansion Patterns":

The "Tag Prefix" Pattern: Use a single label called "Campaign" and store the specific campaign ID in your internal database, linked to the chat ID.
The "Rolling Archive" Pattern: Implement a cleanup script that deletes labels for campaigns or events that have been inactive for more than 90 days.
Dynamic Lifecycle: Only create labels when they are actively needed for the current month's goals, and rotate them as business priorities shift.

🔄 Idempotency & Conflict Resolution

WhatsApp allows for Duplicate Label Names. This can lead to significant confusion if your system creates a new "New Lead" label every time a lead arrives.

The "Verify-Before-Create" Pattern

Your integration should always implement a "Check and Bridge" logic. Before attempting to create a label, fetch the current global list. If a label with the target name (case-insensitive) already exists, your system should use that existing ID instead of creating a new one. This preserves the 20-label quota and maintains a single source of truth for each category.

🛠️ Performance & Integration Principles

Bootstrapping Your Primary Taxonomy

We recommend creating your core "Mission Critical" labels during your application's initial setup or "Warm-up" phase. Creating labels "on-the-fly" during high-traffic message bursts can introduce unnecessary latency and risk hitting Meta's undocumented rate limits for metadata changes.

Webhook Synergy

The creation of a label triggers the label.upsert webhook. Your backend should listen for this event to keep your local database synchronized with the WhatsApp account, especially if users are also creating labels manually via the mobile app.

🎯 Best Practices Summary

Think Statefully: Labels should represent the current state of a conversation, not just the customer's identity.
Optimize Visuals: Group similar departments into color clusters (e.g., all Sales-related labels use shades of Blue).
Store Mapping Locally: Always save the returned id alongside the name in your system for high-speed cross-referencing.
Audit the Sidebar: Periodically review your labels in the native WhatsApp app to ensure they remain legible and meaningful for your frontline agents.

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 name of the new label Example:
`number`	—	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";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "123456789"
6}).toString();
7const body = {
8  "name": "Urgent",
9  "color": "0"
10};
11
12fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
13  method: "POST",
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 SamplesUTF-8

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 created successfully

Bad Request - Invalid Parameter Format

Unauthorized - Invalid or Missing Access Token