> ## 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.
# Gestão de etiquetas
> Consulte o catálogo de etiquetas da sua empresa e atribua-as a uma conversa
As etiquetas (*tags*) classificam suas conversas para segmentá-las, gerar relatórios e roteá-las. Esta página descreve o fluxo recomendado para gerenciá-las por API: primeiro você obtém o catálogo de etiquetas da empresa, depois consulta as etiquetas associadas a uma conversa e, por último, atribui ou atualiza essas etiquetas.
Recupere o catálogo com o `id` de cada etiqueta.
Veja quais etiquetas a conversa já possui antes de modificá-las.
Envie a lista completa de `id` que deve permanecer na conversa.
***
## Autenticação
Todos os endpoints desta página pertencem ao domínio `https://api.jelou.ai` e usam autenticação básica.
| Campo | Local | Tipo | Obrigatório | Descrição |
| ----------------- | ------ | ------ | ----------- | ---------------------------------------------------------- |
| **Authorization** | Header | string | Sim | Credenciais `clientId:clientSecret` codificadas em Base64. |
| **Content-Type** | Header | string | Sim | `application/json` nas solicitações com corpo. |
Consulte [Introdução](/pt/api/introducao) para saber como montar o cabeçalho `Authorization: Basic`.
***
## 1. Obter as etiquetas disponíveis da empresa
Retorna o catálogo de etiquetas disponíveis para uma empresa. Use este endpoint para descobrir os `id` necessários ao atribuir etiquetas.
### Endpoint
```
GET https://api.jelou.ai/v1/company/{companyId}/tags
```
### Parâmetros de rota
| Campo | Local | Tipo | Obrigatório | Descrição |
| ------------- | ----- | ------ | ----------- | ------------------------------- |
| **companyId** | Path | string | Sim | Identificador único da empresa. |
### Parâmetros de consulta
| Campo | Local | Tipo | Obrigatório | Descrição |
| ------------------ | ----- | --------- | ----------- | ------------------------------------------ |
| **name** | Query | string | Não | Filtra etiquetas por nome. |
| **language** | Query | string | Não | Idioma do nome da etiqueta. |
| **teams** | Query | string\[] | Não | Filtra por equipes. |
| **bots** | Query | string\[] | Não | Filtra por canais. |
| **isGlobal** | Query | boolean | Não | Inclui etiquetas globais. |
| **isVisible** | Query | boolean | Não | Inclui apenas etiquetas visíveis. |
| **shouldPaginate** | Query | boolean | Não | Retorna resultados paginados. |
| **limit** | Query | number | Não | Quantidade máxima de registros por página. |
### Exemplo de solicitação
```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}}'
```
### Exemplo de resposta
```json theme={null}
{
"data": [
{
"id": 11,
"name": {
"es": "VIP",
"en": "VIP"
},
"color": "#aabbcc",
"isVisible": true,
"isGlobal": false
}
]
}
```
### Detalhe da resposta
| Campo | Tipo | Descrição |
| ------------- | ------- | ------------------------------------------------------------------- |
| **id** | integer | Identificador da etiqueta. É o valor enviado ao atribuir etiquetas. |
| **name** | object | Nome da etiqueta por idioma (`es`, `en`, entre outros). |
| **color** | string | Cor da etiqueta em formato hexadecimal. |
| **isVisible** | boolean | Indica se a etiqueta é exibida na plataforma. |
| **isGlobal** | boolean | Indica se a etiqueta está disponível para toda a empresa. |
***
## 2. Obter as informações de uma conversa
Retorna as informações completas de uma conversa, incluindo as etiquetas atualmente associadas.
### Endpoint
```
GET https://api.jelou.ai/v1/rooms/{roomId}
```
### Parâmetros de rota
| Campo | Local | Tipo | Obrigatório | Descrição |
| ---------- | ----- | ------ | ----------- | -------------------------------- |
| **roomId** | Path | string | Sim | Identificador único da conversa. |
### Parâmetros de consulta
| Campo | Local | Tipo | Obrigatório | Descrição |
| ------------------- | ----- | ------- | ----------- | ------------------------------------------ |
| **addConversation** | Query | boolean | Não | Inclui informações adicionais da conversa. |
### Exemplo de solicitação
```bash theme={null}
curl --request GET \
--url 'https://api.jelou.ai/v1/rooms/ROOM_ID' \
--header 'Authorization: Basic {{Base64EncodedClientId:ClientSecret}}'
```
### Exemplo de resposta
```json theme={null}
{
"data": {
"id": "abc123",
"name": "John Doe",
"channel": "whatsapp",
"tags": [
{
"id": 14,
"name": {
"es": "Cliente VIP"
}
},
{
"id": 15,
"name": {
"es": "Cliente Frecuente"
}
}
]
}
}
```
As etiquetas atribuídas a uma conversa são obtidas no atributo `data.tags`.
***
## 3. Atribuir ou atualizar as etiquetas de uma conversa
Atribui ou atualiza as etiquetas de uma conversa.
### Endpoint
```
POST https://api.jelou.ai/v1/bots/{botId}/rooms/tags
```
### Parâmetros de rota
| Campo | Local | Tipo | Obrigatório | Descrição |
| --------- | ----- | ------ | ----------- | --------------------------------------------------------- |
| **botId** | Path | string | Sim | Identificador único do canal ao qual a conversa pertence. |
### Parâmetros do corpo
| Campo | Local | Tipo | Obrigatório | Descrição |
| ---------- | ----- | ---------- | ----------- | -------------------------------------- |
| **roomId** | Body | string | Sim | Identificador da conversa. |
| **tags** | Body | integer\[] | Sim | Lista de `id` de etiquetas a associar. |
### Exemplo de solicitação
```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]
}'
```
### Exemplo de resposta
```json theme={null}
{
"data": {
"id": "abc123",
"tags": [1, 2]
},
"message": "Tags assigned successfully."
}
```
***
## Considerações
O arranjo enviado em `tags` **substitui completamente** as etiquetas atuais da conversa. Ele não adiciona etiquetas às já existentes.
* Todas as etiquetas enviadas devem existir e estar disponíveis para o canal especificado.
* Para manter as etiquetas já atribuídas e adicionar novas, envie no arranjo tanto as existentes quanto as novas.
* Se você enviar um arranjo vazio (`[]`), todas as etiquetas associadas à conversa serão removidas.
### Exemplo
Suponha que a conversa tenha atualmente as etiquetas `[14, 15]`.
Para adicionar a etiqueta `20` e manter as existentes, envie as três:
```json theme={null}
{
"roomId": "abc123",
"tags": [14, 15, 20]
}
```
Se você enviar apenas a etiqueta nova, as etiquetas `14` e `15` são substituídas e a conversa fica somente com a etiqueta `20`:
```json theme={null}
{
"roomId": "abc123",
"tags": [20]
}
```
***
## Códigos de resposta
| Código | Estado | Descrição |
| ------ | --------------------- | ------------------------- |
| 200 | OK | Operação bem-sucedida. |
| 400 | Bad Request | Solicitação inválida. |
| 401 | Unauthorized | Não autorizado. |
| 404 | Not Found | Recurso não encontrado. |
| 500 | Internal Server Error | Erro interno do servidor. |