> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wappfy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Labels

> Create and manage WhatsApp Business labels to organize your chats and contacts.

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

<Note>
  Labels are only available on WhatsApp Business accounts. Personal WhatsApp accounts do not support labels.
</Note>

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.

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/labels \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  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})`);
  });
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Warning>
  Deleting a label removes it from all associated chats. This action cannot be undone.
</Warning>

***

## Chat Labels

### Get Labels for a Chat

Retrieve all labels assigned to a specific chat.

```bash theme={null}
curl https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```javascript Node.js theme={null}
  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"],
      }),
    }
  );
  ```
</CodeGroup>

<Tip>
  To remove all labels from a chat, pass an empty array: `{"label_ids": []}`.
</Tip>

### Get Chats by Label

Retrieve all chats that have a specific label assigned.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  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`);
  ```
</CodeGroup>

**Response:**

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

***

## Common Use Cases

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

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