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

# Tag management

> Retrieve your company's tag catalog and assign tags to a conversation

Tags classify your conversations so you can segment, report on, and route them. This page describes the recommended flow to manage them through the API: first you retrieve the company's tag catalog, then you check the tags associated with a conversation, and finally you assign or update them.

<Steps>
  <Step title="Retrieve the company's available tags">
    Get the catalog with the `id` of each tag.
  </Step>

  <Step title="Check the conversation's current tags">
    Review which tags the conversation already has before modifying them.
  </Step>

  <Step title="Assign or update the tags">
    Send the complete list of `id` values the conversation should end up with.
  </Step>
</Steps>

***

## Authentication

Every endpoint on this page belongs to the `https://api.jelou.ai` domain and uses basic authentication.

| Field             | Location | Type   | Required | Description                                            |
| ----------------- | -------- | ------ | -------- | ------------------------------------------------------ |
| **Authorization** | Header   | string | Yes      | `clientId:clientSecret` credentials encoded in Base64. |
| **Content-Type**  | Header   | string | Yes      | `application/json` on requests with a body.            |

<Info>
  See [Introduction](/en/api/introduction) to learn how to build the `Authorization: Basic` header.
</Info>

***

## 1. Retrieve the company's available tags

Returns the catalog of tags available to a company. Use this endpoint to find the `id` values you need when assigning tags.

### Endpoint

```
GET https://api.jelou.ai/v1/company/{companyId}/tags
```

### Path parameters

| Field         | Location | Type   | Required | Description                       |
| ------------- | -------- | ------ | -------- | --------------------------------- |
| **companyId** | Path     | string | Yes      | Unique identifier of the company. |

### Query parameters

| Field              | Location | Type      | Required | Description                         |
| ------------------ | -------- | --------- | -------- | ----------------------------------- |
| **name**           | Query    | string    | No       | Filters tags by name.               |
| **language**       | Query    | string    | No       | Language of the tag name.           |
| **teams**          | Query    | string\[] | No       | Filters by teams.                   |
| **bots**           | Query    | string\[] | No       | Filters by channels.                |
| **isGlobal**       | Query    | boolean   | No       | Includes global tags.               |
| **isVisible**      | Query    | boolean   | No       | Includes only visible tags.         |
| **shouldPaginate** | Query    | boolean   | No       | Returns paginated results.          |
| **limit**          | Query    | number    | No       | Maximum number of records per page. |

### Request example

```bash theme={null}
curl --request GET \
  --url 'https://api.jelou.ai/v1/company/COMPANY_ID/tags?isVisible=true&limit=50' \
  --header 'Authorization: Basic {{Base64EncodedClientId:ClientSecret}}'
```

### Response example

```json theme={null}
{
  "data": [
    {
      "id": 11,
      "name": {
        "es": "VIP",
        "en": "VIP"
      },
      "color": "#aabbcc",
      "isVisible": true,
      "isGlobal": false
    }
  ]
}
```

### Response details

| Field         | Type    | Description                                                     |
| ------------- | ------- | --------------------------------------------------------------- |
| **id**        | integer | Tag identifier. This is the value you send when assigning tags. |
| **name**      | object  | Tag name per language (`es`, `en`, and so on).                  |
| **color**     | string  | Tag color in hexadecimal format.                                |
| **isVisible** | boolean | Whether the tag is shown in the platform.                       |
| **isGlobal**  | boolean | Whether the tag is available across the whole company.          |

***

## 2. Get a conversation's information

Returns the full information of a conversation, including the tags currently associated with it.

### Endpoint

```
GET https://api.jelou.ai/v1/rooms/{roomId}
```

### Path parameters

| Field      | Location | Type   | Required | Description                            |
| ---------- | -------- | ------ | -------- | -------------------------------------- |
| **roomId** | Path     | string | Yes      | Unique identifier of the conversation. |

### Query parameters

| Field               | Location | Type    | Required | Description                                   |
| ------------------- | -------- | ------- | -------- | --------------------------------------------- |
| **addConversation** | Query    | boolean | No       | Includes additional conversation information. |

### Request example

```bash theme={null}
curl --request GET \
  --url 'https://api.jelou.ai/v1/rooms/ROOM_ID' \
  --header 'Authorization: Basic {{Base64EncodedClientId:ClientSecret}}'
```

### Response example

```json theme={null}
{
  "data": {
    "id": "abc123",
    "name": "John Doe",
    "channel": "whatsapp",
    "tags": [
      {
        "id": 14,
        "name": {
          "es": "Cliente VIP"
        }
      },
      {
        "id": 15,
        "name": {
          "es": "Cliente Frecuente"
        }
      }
    ]
  }
}
```

<Tip>
  The tags assigned to a conversation are read from the `data.tags` attribute.
</Tip>

***

## 3. Assign or update a conversation's tags

Assigns or updates the tags of a conversation.

### Endpoint

```
POST https://api.jelou.ai/v1/bots/{botId}/rooms/tags
```

### Path parameters

| Field     | Location | Type   | Required | Description                                                   |
| --------- | -------- | ------ | -------- | ------------------------------------------------------------- |
| **botId** | Path     | string | Yes      | Unique identifier of the channel the conversation belongs to. |

### Body parameters

| Field      | Location | Type       | Required | Description                           |
| ---------- | -------- | ---------- | -------- | ------------------------------------- |
| **roomId** | Body     | string     | Yes      | Identifier of the conversation.       |
| **tags**   | Body     | integer\[] | Yes      | List of tag `id` values to associate. |

### Request example

```bash theme={null}
curl --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/rooms/tags' \
  --header 'Authorization: Basic {{Base64EncodedClientId:ClientSecret}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "roomId": "abc123",
    "tags": [1, 2]
  }'
```

### Response example

```json theme={null}
{
  "data": {
    "id": "abc123",
    "tags": [1, 2]
  },
  "message": "Tags assigned successfully."
}
```

***

## Considerations

<Warning>
  The array sent in `tags` **fully replaces** the conversation's current tags. It does not add tags to the existing ones.
</Warning>

* Every tag you send must exist and be available to the specified channel.
* To keep the already assigned tags and add new ones, send both the existing and the new tags in the array.
* If you send an empty array (`[]`), all tags associated with the conversation are removed.

### Example

Say the conversation currently has the tags `[14, 15]`.

To add tag `20` and keep the existing ones, send all three:

```json theme={null}
{
  "roomId": "abc123",
  "tags": [14, 15, 20]
}
```

If you send only the new tag, tags `14` and `15` are replaced and the conversation keeps tag `20` alone:

```json theme={null}
{
  "roomId": "abc123",
  "tags": [20]
}
```

***

## Response codes

| Code | Status                | Description            |
| ---- | --------------------- | ---------------------- |
| 200  | OK                    | Successful operation.  |
| 400  | Bad Request           | Invalid request.       |
| 401  | Unauthorized          | Not authorized.        |
| 404  | Not Found             | Resource not found.    |
| 500  | Internal Server Error | Internal server error. |