Assign Label to Chat

Add or remove labels from WhatsApp chats and contacts.

POST /label/handleLabel/:instanceName

cURL (Add Label)

curl --request POST \
  --url https://api.example.com/label/handleLabel/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "5511999999999",
    "labelId": "1",
    "action": "add"
  }'

curl --request POST \
  --url https://api.example.com/label/handleLabel/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "[e-mail]",
    "labelId": "1",
    "action": "remove"
  }'

// Add label to chat
const response = await fetch(
  'https://api.example.com/label/handleLabel/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      number: '5511999999999',
      labelId: '1',
      action: 'add'
    })
  }
);

const data = await response.json();

import requests

# Remove label from chat
response = requests.post(
    'https://api.example.com/label/handleLabel/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'number': '5511999999999',
        'labelId': '2',
        'action': 'remove'
    }
)

data = response.json()

200 Success (Add)

{
  "success": true,
  "number": "[e-mail]",
  "labelId": "1",
  "action": "add"
}

{
  "success": true,
  "number": "[e-mail]",
  "labelId": "1",
  "action": "remove"
}

{
  "error": "Invalid action",
  "message": "Action must be 'add' or 'remove'"
}

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

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

{
  "error": "Label not found",
  "message": "The specified label ID does not exist"
}

Overview

You can assign labels to chats or remove them. This helps you organize and categorize your conversations for better management.

Labels are only available for WhatsApp Business accounts. You must first create labels in your WhatsApp Business app before you can assign them via the API.

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.

Request Body

number · string · required

The phone number or chat JID to label. Can be in format “5511999999999” or “[e-mail]”.

labelId · string · required

The ID of the label to add or remove. You can get label IDs from the /label/findLabels endpoint.

action · string · required

The action to perform. Must be one of:

• add: Add the label to the chat
• remove: Remove the label from the chat

Response

success · boolean

Whether the operation completed successfully.

number · string

The chat/contact that was labeled.

labelId · string

The label ID that was added or removed.

action · string

The action that was performed (“add” or “remove”).

cURL (Add Label)

curl --request POST \
  --url https://api.example.com/label/handleLabel/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "5511999999999",
    "labelId": "1",
    "action": "add"
  }'

curl --request POST \
  --url https://api.example.com/label/handleLabel/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "[e-mail]",
    "labelId": "1",
    "action": "remove"
  }'

// Add label to chat
const response = await fetch(
  'https://api.example.com/label/handleLabel/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      number: '5511999999999',
      labelId: '1',
      action: 'add'
    })
  }
);

const data = await response.json();

import requests

# Remove label from chat
response = requests.post(
    'https://api.example.com/label/handleLabel/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'number': '5511999999999',
        'labelId': '2',
        'action': 'remove'
    }
)

data = response.json()

200 Success (Add)

{
  "success": true,
  "number": "[e-mail]",
  "labelId": "1",
  "action": "add"
}

{
  "success": true,
  "number": "[e-mail]",
  "labelId": "1",
  "action": "remove"
}

{
  "error": "Invalid action",
  "message": "Action must be 'add' or 'remove'"
}

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

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

{
  "error": "Label not found",
  "message": "The specified label ID does not exist"
}

Usage Notes

You can assign multiple labels to the same chat by calling this endpoint multiple times with different label IDs.

Use labels to implement automated chat categorization workflows. For example, automatically label chats based on message content or customer behavior.

Attempting to add a label that’s already assigned to a chat will not cause an error, but it won’t create a duplicate.

Common Use Cases

Customer Status Tracking

// Label new customers
await assignLabel({
  number: '5511999999999',
  labelId: 'new_customer',
  action: 'add'
});

// Later, upgrade to VIP
await assignLabel({
  number: '5511999999999',
  labelId: 'new_customer',
  action: 'remove'
});

await assignLabel({
  number: '5511999999999',
  labelId: 'vip',
  action: 'add'
});

Priority Management

// Mark urgent chats
await assignLabel({
  number: chatId,
  labelId: 'urgent',
  action: 'add'
});

// Remove when resolved
await assignLabel({
  number: chatId,
  labelId: 'urgent',
  action: 'remove'
});

await assignLabel({
  number: chatId,
  labelId: 'resolved',
  action: 'add'
});

Related Endpoints

Get All Labels

First, fetch available labels:

GET /label/findLabels/:instanceName

This returns all labels with their IDs, which you can then use to assign to chats.