> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/EvolutionAPI/evolution-api/llms.txt
> Use this file to discover all available pages before exploring further.

# Assign Label to Chat

> Add or remove labels from WhatsApp chats and contacts.

## Overview

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

<Note>
  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.
</Note>

## Authentication

This endpoint requires authentication via the `apikey` header.

<ParamField path="header.apikey" type="string" required>
  Your Evolution API key for authentication.
</ParamField>

## Path Parameters

<ParamField path="path.instanceName" type="string" required>
  The name of your WhatsApp Business instance.
</ParamField>

## Request Body

<ParamField body="number" type="string" required>
  The phone number or chat JID to label. Can be in format "5511999999999" or "[5511999999999@s.whatsapp.net](mailto:5511999999999@s.whatsapp.net)".
</ParamField>

<ParamField body="labelId" type="string" required>
  The ID of the label to add or remove. You can get label IDs from the `/label/findLabels` endpoint.
</ParamField>

<ParamField body="action" type="string" required>
  The action to perform. Must be one of:

  * `add`: Add the label to the chat
  * `remove`: Remove the label from the chat
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the operation completed successfully.
</ResponseField>

<ResponseField name="number" type="string">
  The chat/contact that was labeled.
</ResponseField>

<ResponseField name="labelId" type="string">
  The label ID that was added or removed.
</ResponseField>

<ResponseField name="action" type="string">
  The action that was performed ("add" or "remove").
</ResponseField>

<RequestExample>
  ```bash cURL (Add Label) theme={null}
  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"
    }'
  ```

  ```bash cURL (Remove Label) theme={null}
  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@s.whatsapp.net",
      "labelId": "1",
      "action": "remove"
    }'
  ```

  ```javascript JavaScript theme={null}
  // 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();
  ```

  ```python Python theme={null}
  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()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success (Add) theme={null}
  {
    "success": true,
    "number": "5511999999999@s.whatsapp.net",
    "labelId": "1",
    "action": "add"
  }
  ```

  ```json 200 Success (Remove) theme={null}
  {
    "success": true,
    "number": "5511999999999@s.whatsapp.net",
    "labelId": "1",
    "action": "remove"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Invalid action",
    "message": "Action must be 'add' or 'remove'"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid API key"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "error": "Feature not available",
    "message": "Labels are only available for WhatsApp Business accounts"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Label not found",
    "message": "The specified label ID does not exist"
  }
  ```
</ResponseExample>

## Usage Notes

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

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

<Warning>
  Attempting to add a label that's already assigned to a chat will not cause an error, but it won't create a duplicate.
</Warning>

## Common Use Cases

### Customer Status Tracking

```javascript theme={null}
// 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

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