Skip to main content

​
Labels

Labels are a WhatsApp Business feature that lets you categorize and organize your chats. Through the Wappfy API, you can create custom labels, assign them to chats, and retrieve chats by label.
Labels are only available on WhatsApp Business accounts. Personal WhatsApp accounts do not support labels.
All label endpoints are scoped to a specific instance: 
/api/instances/{instanceId}/labels/...

​
Create a Label

Create a new label with a name and color. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/labels \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Customer",
    "color": 1
  }'
Response: 
{
  "data": {
    "id": "1",
    "name": "VIP Customer",
    "color": 1
  }
}

​
Label Colors

WhatsApp Business supports a fixed set of label colors identified by number:
Color IDColor
0Light gray
1Green
2Blue
3Yellow
4Pink/Red

​
List Labels

Retrieve all labels for the instance. 
curl https://api.wappfy.io/api/instances/inst_abc123/labels \
  -H "X-Api-Key: YOUR_API_KEY"
Response: 
{
  "data": [
    { "id": "1", "name": "New Customer", "color": 0 },
    { "id": "2", "name": "VIP Customer", "color": 1 },
    { "id": "3", "name": "Pending Payment", "color": 3 },
    { "id": "4", "name": "Resolved", "color": 2 }
  ]
}

​
Update a Label

Update an existing label’s name or color. 
curl -X PUT https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Customer",
    "color": 2
  }'

​
Delete a Label

Permanently delete a label. This removes the label from all chats it was assigned to. 
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY"
Deleting a label removes it from all associated chats. This action cannot be undone.

​
Chat Labels

​
Get Labels for a Chat

Retrieve all labels assigned to a specific chat. 
curl https://api.wappfy.io/api/instances/inst_abc123/labels/chats/[email protected] \
  -H "X-Api-Key: YOUR_API_KEY"
Response: 
{
  "data": [
    { "id": "1", "name": "New Customer", "color": 0 },
    { "id": "3", "name": "Pending Payment", "color": 3 }
  ]
}

​
Set Labels on a Chat

Assign one or more labels to a chat. This replaces any existing labels on the chat. 
curl -X PUT https://api.wappfy.io/api/instances/inst_abc123/labels/chats/[email protected] \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label_ids": ["1", "2"]
  }'
To remove all labels from a chat, pass an empty array: {"label_ids": []}.

​
Get Chats by Label

Retrieve all chats that have a specific label assigned. 
curl https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats \
  -H "X-Api-Key: YOUR_API_KEY"
Response: 
{
  "data": [
    {
      "chat_id": "[email protected]",
      "name": "Maria Silva"
    },
    {
      "chat_id": "[email protected]",
      "name": "Carlos Oliveira"
    }
  ]
}

​
Common Use Cases

Use a webhook to listen for message.received events. When a message comes from an unknown contact, assign the “New Lead” label via the API. This helps your team quickly identify and prioritize new conversations.
Create labels like “Open”, “In Progress”, and “Resolved”. Update the label as your team works through support requests. Use the “Get Chats by Label” endpoint to build a simple support queue.
Label customers by category (e.g., “VIP”, “Wholesale”, “Retail”). When sending broadcast messages, fetch all chats for a label and send messages in a loop.

​
Endpoint Reference

MethodEndpointDescription
POST/api/instances/{id}/labelsCreate a new label
GET/api/instances/{id}/labelsList all labels
PUT/api/instances/{id}/labels/{labelId}Update a label
DELETE/api/instances/{id}/labels/{labelId}Delete a label
GET/api/instances/{id}/labels/chats/{chatId}Get labels for a chat
PUT/api/instances/{id}/labels/chats/{chatId}Set labels on a chat
GET/api/instances/{id}/labels/{labelId}/chatsGet chats by label

​
Error Handling

Status CodeDescription
400Invalid label color or missing required fields.
404Label or chat not found.
409A label with the same name already exists.
422Invalid chat ID format.