Manage Labels

Retrieve all labels from your WhatsApp Business account.

GET /label/findLabels/:instanceName

cURL

curl --request GET \
  --url https://api.example.com/label/findLabels/my-instance \
  --header 'apikey: YOUR_API_KEY'

const response = await fetch(
  'https://api.example.com/label/findLabels/my-instance',
  {
    method: 'GET',
    headers: {
      'apikey': 'YOUR_API_KEY'
    }
  }
);

const data = await response.json();

import requests

response = requests.get(
    'https://api.example.com/label/findLabels/my-instance',
    headers={'apikey': 'YOUR_API_KEY'}
)

data = response.json()

200 Success

{
  "labels": [
    {
      "id": "1",
      "name": "New Customer",
      "color": "#00A0DC",
      "predefinedId": "1"
    },
    {
      "id": "2",
      "name": "Pending Payment",
      "color": "#F39C12",
      "predefinedId": "2"
    },
    {
      "id": "custom_123",
      "name": "VIP Client",
      "color": "#9B59B6",
      "predefinedId": null
    }
  ]
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Feature not available",
  "message": "Labels are only available for WhatsApp Business accounts"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

Overview

You can fetch all labels (tags) configured in your WhatsApp Business account. Labels help you organize and categorize chats and contacts.

Labels are only available for WhatsApp Business accounts. Regular WhatsApp accounts do not support labels.

Authentication

This endpoint requires authentication via the apikey header.

header.apikey · string · required

Your Evolution API key for authentication.

Path Parameters

path.instanceName · string · required

The name of your WhatsApp Business instance.

Response

labels · array

Array of label objects.

Show properties

id · string

Unique label identifier.

name · string

Label name/text.

color · string

Label color code (hex format).

predefinedId · string

WhatsApp’s predefined label ID, if applicable.

cURL

curl --request GET \
  --url https://api.example.com/label/findLabels/my-instance \
  --header 'apikey: YOUR_API_KEY'

const response = await fetch(
  'https://api.example.com/label/findLabels/my-instance',
  {
    method: 'GET',
    headers: {
      'apikey': 'YOUR_API_KEY'
    }
  }
);

const data = await response.json();

import requests

response = requests.get(
    'https://api.example.com/label/findLabels/my-instance',
    headers={'apikey': 'YOUR_API_KEY'}
)

data = response.json()

200 Success

{
  "labels": [
    {
      "id": "1",
      "name": "New Customer",
      "color": "#00A0DC",
      "predefinedId": "1"
    },
    {
      "id": "2",
      "name": "Pending Payment",
      "color": "#F39C12",
      "predefinedId": "2"
    },
    {
      "id": "custom_123",
      "name": "VIP Client",
      "color": "#9B59B6",
      "predefinedId": null
    }
  ]
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Feature not available",
  "message": "Labels are only available for WhatsApp Business accounts"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

Label Colors

WhatsApp Business provides predefined label colors:

Available Colors

• Blue: #00A0DC
• Orange: #F39C12
• Purple: #9B59B6
• Green: #16A085
• Red: #E74C3C
• Gray: #95A5A6

Usage Notes

WhatsApp Business allows you to create custom labels in addition to the predefined ones.

Use labels to organize chats by customer status, priority, or any other category relevant to your business.

Label management (creating, editing, deleting) is typically done through the WhatsApp Business app. This API allows you to fetch and assign existing labels.