Skip to main content
POST
/
label
/
handleLabel
/
:instanceName
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"
  }'

{
  "success": true,
  "number": "[email protected]",
  "labelId": "1",
  "action": "add"
}

​
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 “[email protected]”.
​
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 --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"
  }'

{
  "success": true,
  "number": "[email protected]",
  "labelId": "1",
  "action": "add"
}

​
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'
});

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us