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

# Gestión de etiquetas

> Consulta el catálogo de etiquetas de tu compañía y asígnalas a una conversación

Las etiquetas (*tags*) clasifican tus conversaciones para segmentarlas, reportarlas y enrutarlas. Esta página describe el flujo recomendado para gestionarlas por API: primero obtienes el catálogo de etiquetas de la compañía, luego consultas las etiquetas asociadas a una conversación y por último las asignas o actualizas.

<Steps>
  <Step title="Obtén las etiquetas disponibles de la compañía">
    Recupera el catálogo con los `id` de cada etiqueta.
  </Step>

  <Step title="Consulta las etiquetas actuales de la conversación">
    Revisa qué etiquetas tiene asignadas la conversación antes de modificarlas.
  </Step>

  <Step title="Asigna o actualiza las etiquetas">
    Envía la lista completa de `id` que debe quedar en la conversación.
  </Step>
</Steps>

***

## Autenticación

Todos los endpoints de esta página pertenecen al dominio `https://api.jelou.ai` y usan autenticación básica.

| Campo             | Ubicación | Tipo   | Requerido | Descripción                                                 |
| ----------------- | --------- | ------ | --------- | ----------------------------------------------------------- |
| **Authorization** | Header    | string | Sí        | Credenciales `clientId:clientSecret` codificadas en Base64. |
| **Content-Type**  | Header    | string | Sí        | `application/json` en las solicitudes con cuerpo.           |

<Info>
  Consulta [Introducción](/api/introduction) para conocer cómo construir el encabezado `Authorization: Basic`.
</Info>

***

## 1. Obtener etiquetas disponibles de la compañía

Obtiene el catálogo de etiquetas disponibles para una compañía. Usa este endpoint para conocer los `id` que necesitas al asignar etiquetas.

### Endpoint

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

### Parámetros de ruta

| Campo         | Ubicación | Tipo   | Requerido | Descripción                         |
| ------------- | --------- | ------ | --------- | ----------------------------------- |
| **companyId** | Path      | string | Sí        | Identificador único de la compañía. |

### Parámetros de consulta

| Campo              | Ubicación | Tipo      | Requerido | Descripción                              |
| ------------------ | --------- | --------- | --------- | ---------------------------------------- |
| **name**           | Query     | string    | No        | Filtra etiquetas por nombre.             |
| **language**       | Query     | string    | No        | Idioma del nombre de la etiqueta.        |
| **teams**          | Query     | string\[] | No        | Filtra por equipos.                      |
| **bots**           | Query     | string\[] | No        | Filtra por canales.                      |
| **isGlobal**       | Query     | boolean   | No        | Incluye etiquetas globales.              |
| **isVisible**      | Query     | boolean   | No        | Incluye únicamente etiquetas visibles.   |
| **shouldPaginate** | Query     | boolean   | No        | Retorna resultados paginados.            |
| **limit**          | Query     | number    | No        | Cantidad máxima de registros por página. |

### Ejemplo de solicitud

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

### Ejemplo de respuesta

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

### Detalle de la respuesta

| Campo         | Tipo    | Descripción                                                                |
| ------------- | ------- | -------------------------------------------------------------------------- |
| **id**        | integer | Identificador de la etiqueta. Es el valor que envías al asignar etiquetas. |
| **name**      | object  | Nombre de la etiqueta por idioma (`es`, `en`, etc.).                       |
| **color**     | string  | Color de la etiqueta en formato hexadecimal.                               |
| **isVisible** | boolean | Indica si la etiqueta se muestra en la plataforma.                         |
| **isGlobal**  | boolean | Indica si la etiqueta está disponible para toda la compañía.               |

***

## 2. Obtener información de una conversación

Obtiene la información completa de una conversación, incluyendo las etiquetas actualmente asociadas.

### Endpoint

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

### Parámetros de ruta

| Campo      | Ubicación | Tipo   | Requerido | Descripción                             |
| ---------- | --------- | ------ | --------- | --------------------------------------- |
| **roomId** | Path      | string | Sí        | Identificador único de la conversación. |

### Parámetros de consulta

| Campo               | Ubicación | Tipo    | Requerido | Descripción                                       |
| ------------------- | --------- | ------- | --------- | ------------------------------------------------- |
| **addConversation** | Query     | boolean | No        | Incluye información adicional de la conversación. |

### Ejemplo de solicitud

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

### Ejemplo de respuesta

```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>
  Las etiquetas asignadas a una conversación se recuperan del atributo `data.tags`.
</Tip>

***

## 3. Asignar o actualizar etiquetas de una conversación

Asigna o actualiza las etiquetas de una conversación.

### Endpoint

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

### Parámetros de ruta

| Campo     | Ubicación | Tipo   | Requerido | Descripción                                                     |
| --------- | --------- | ------ | --------- | --------------------------------------------------------------- |
| **botId** | Path      | string | Sí        | Identificador único del canal al que pertenece la conversación. |

### Parámetros del cuerpo

| Campo      | Ubicación | Tipo       | Requerido | Descripción                           |
| ---------- | --------- | ---------- | --------- | ------------------------------------- |
| **roomId** | Body      | string     | Sí        | Identificador de la conversación.     |
| **tags**   | Body      | integer\[] | Sí        | Lista de `id` de etiquetas a asociar. |

### Ejemplo de solicitud

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

### Ejemplo de respuesta

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

***

## Consideraciones

<Warning>
  El arreglo enviado en `tags` **reemplaza por completo** las etiquetas actuales de la conversación. No agrega etiquetas a las existentes.
</Warning>

* Todas las etiquetas enviadas deben existir y estar disponibles para el canal especificado.
* Si quieres conservar las etiquetas ya asignadas y agregar nuevas, envía en el arreglo tanto las existentes como las nuevas.
* Si envías un arreglo vacío (`[]`), se eliminarán todas las etiquetas asociadas a la conversación.

### Ejemplo

Supón que la conversación tiene actualmente las etiquetas `[14, 15]`.

Para agregar la etiqueta `20` y conservar las existentes, envía las tres:

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

Si envías únicamente la etiqueta nueva, las etiquetas `14` y `15` se reemplazan y la conversación queda solo con la etiqueta `20`:

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

***

## Códigos de respuesta

| Código | Estado                | Descripción                 |
| ------ | --------------------- | --------------------------- |
| 200    | OK                    | Operación exitosa.          |
| 400    | Bad Request           | Solicitud inválida.         |
| 401    | Unauthorized          | No autorizado.              |
| 404    | Not Found             | Recurso no encontrado.      |
| 500    | Internal Server Error | Error interno del servidor. |