1. Audits Over Polling: Run a full directory fetch periodically (e.g., once a day) to catch any manual changes made by agents in the WhatsApp mobile app. 2. Case-Insensitive Searching: When looking for a label by name in this list, always use case-insensitive matching to prevent duplicate creation errors. 3. Fallbac

Get All Labels

Retrieve all WhatsApp labels available in your WhatsApp Business account.

GET

https://api.wawp.net/v2/labels?access_token=123456789&instance_id=123456789

Authentication Required

Test /v2/labels endpoint

Supports

GET

No query parameters required

This endpoint doesn't expect data in the URL.

Catalog

Returns a list of all defined labels on the account.

Sync

Use this on startup to build your local label map.

Best practices

Poll this endpoint occasionally to detect labels created on the phone.
Display available labels in a dropdown for your agents.

The Label Directory: Master Inventory Management

The Get All Labels endpoint acts as the central directory for your WhatsApp Business account's organizational metadata. It is the primary tool for auditing your existing taxonomy and synchronizing your external systems with the reality of your WhatsApp environment.

🏗️ Core Concept: The Source of Truth

This endpoint provides a snapshot of every label currently configured on your account. Because labels are global resources, this list is common across all agents and automated systems connected to your instance.

Key Data Architecture

Each entry in the returned array represents a unique organizational category, defined by a persistent ID and a visual signature (Color Index). While name changes are frequent, the ID remains the immutable reference point for your database.

🚀 Strategic Operational Use Cases

1. Global State Synchronization

The most common use for this endpoint is "Directory Hydration." On system startup or agent login, your application should fetch the full directory to build a local map of names to IDs. This prevents your system from having to "guess" which ID corresponds to "VIP" or "New Lead" during high-volume operations.

2. CRM Taxonomy Mapping

If you are integrating WhatsApp with an external CRM (like Salesforce, HubSpot, or a custom ERP), this endpoint allows you to run a "Taxonomy Audit." By comparing your WhatsApp labels with your CRM tags, you can identify naming discrepancies or missing categories and programmatically reconcile them.

3. Analytics & Resource Distribution

By combining this endpoint with Get Chats with Label, you can generate a "Volume Heatmap." This allows management to see exactly how many conversations are sitting in "Pending" versus "In Progress," enabling better resource allocation across your agent pool.

⚡ Performance Engineering: Advanced Caching Strategies

Since labels are established during account setup and rarely change in real-time, fetching the entire list for every message would be inefficient.

The "Pulse & Probe" Caching Pattern

Instead of high-frequency polling, we recommend a "Warm Cache" approach:

Initial Fetch: Pull all labels during the "Warm-up" phase of your worker or server.
In-Memory Store: Keep these labels in a global object or a Redis store.
Invalidation Hooks: Instead of a time-based TTL (Time to Live), use Webhooks. Your system should only invalidate the cache when it receives a label.upsert or label.deleted event. This ensures your data is always 100% current without redundant API overhead.

🛠️ Integration Patterns: UI & UX Excellence

Responsive Label Rendering

When building a custom dashboard, use the data from this endpoint to pre-calculate your CSS variables. By mapping the Color Index (0-19) to your design system's theme, you ensure that the "VIP" badge in your CRM looks identical to the "VIP" badge in the official WhatsApp app, providing a seamless multi-channel experience for your agents.

The "Smart Dropdown" Experience

Don't just show a list of names; use the color metadata to group labels logically in your UI. For example, placing all "Red" urgency labels at the top of a selection menu can significantly reduce agent response times during critical escalations.

⚠️ State Consistency & Error Resilience

Handling "The Empty State"

If this endpoint returns an empty array, it indicates a "Clean Slate" account. This is a critical trigger for your system to run its "Bootstrapping" logic—programmatically creating the default taxonomy (e.g., Marketing, Sales, Support) required for your business logic to function.

Handling "The Deleted ID"

If your local database still references a Label ID that no longer appears in this list, your system should proactively "prune" those references. Continuing to attempt tagging with a deleted ID will result in API errors and broken workflow automations.

🎯 Best Practices

Audits Over Polling: Run a full directory fetch periodically (e.g., once a day) to catch any manual changes made by agents in the WhatsApp mobile app.
Case-Insensitive Searching: When looking for a label by name in this list, always use case-insensitive matching to prevent duplicate creation errors.
Fallback Logic: If the API is temporarily unreachable, your system should fall back to its last known cached state rather than failing the entire request.
Security Scoping: Limit who can view this full directory in your own application, as label names can sometimes reveal sensitive internal project names or campaign strategies.

Request Parameters

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

URL Parameters

Passed in the URL query string

	`string`		Your unique WhatsApp Instance ID Example:
	`string`		Your API Access Token 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();
7
8
9fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
10  method: "GET",
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 === 401) {
23      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
24    }
25    if (response.status === 500) {
26      console.error("Error 500: Internal Server Error - Unexpected Failure");
27    }
28
29    const errorText = await response.text();
30    console.error(`Error ${response.status}: ${errorText}`);
31  })
32  .catch((error) => console.error("Network Error:", error));

Interactive SamplesUTF-8

Ln 32, 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.

List of labels retrieved successfully

application/json

object *

Example

{
"0": {
  "id": "1",
  "name": "New Customer",
  "color": 0,
  "colorHex": "#ff9485"
  },
"1": {
  "id": "2",
  "name": "Favorites",
  "color": 1,
  "colorHex": "#64c4ff"
  }
}

Unauthorized - Invalid or Missing Access Token

Internal Server Error - Unexpected Failure