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
  }'

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/labels",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "VIP Customer",
      color: 1,
    }),
  }
);

const label = await response.json();
console.log(label.data.id);

Response:

{
  "data": {
    "id": "1",
    "name": "VIP Customer",
    "color": 1
  }
}

Label Colors

WhatsApp Business supports a fixed set of label colors identified by number:

Color ID	Color
`0`	Light gray
`1`	Green
`2`	Blue
`3`	Yellow
`4`	Pink/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"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/labels",
  {
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }
);

const { data } = await response.json();
data.forEach((label) => {
  console.log(`${label.id}: ${label.name} (color: ${label.color})`);
});

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/5511999998888@s.whatsapp.net \
  -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/5511999998888@s.whatsapp.net \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label_ids": ["1", "2"]
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net",
  {
    method: "PUT",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats",
  {
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }
);

const { data } = await response.json();
console.log(`${data.length} chats with the "VIP Customer" label`);

Response:

{
  "data": [
    {
      "chat_id": "5511999998888@s.whatsapp.net",
      "name": "Maria Silva"
    },
    {
      "chat_id": "5511888887777@s.whatsapp.net",
      "name": "Carlos Oliveira"
    }
  ]
}

Common Use Cases

Tagging new leads automatically

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.

Tracking support ticket status

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.

Segmenting customers for broadcasts

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

Method	Endpoint	Description
`POST`	`/api/instances/{id}/labels`	Create a new label
`GET`	`/api/instances/{id}/labels`	List 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}/chats`	Get chats by label

Error Handling

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

Getting Started

Guides

Labels

Labels

Create a Label

Label Colors

List Labels

Update a Label

Delete a Label

Chat Labels

Get Labels for a Chat

Set Labels on a Chat

Get Chats by Label

Common Use Cases

Endpoint Reference

Error Handling

​Labels

​Create a Label

​Label Colors

​List Labels

​Update a Label

​Delete a Label

​Chat Labels

​Get Labels for a Chat

​Set Labels on a Chat

​Get Chats by Label

​Common Use Cases

​Endpoint Reference

​Error Handling

Labels

Create a Label

Label Colors

List Labels

Update a Label

Delete a Label

Chat Labels

Get Labels for a Chat

Set Labels on a Chat

Get Chats by Label

Common Use Cases

Endpoint Reference

Error Handling