Gestão de etiquetas

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.

Obtenha as etiquetas disponíveis da empresa

Recupere o catálogo com o id de cada etiqueta.

Consulte as etiquetas atuais da conversa

Veja quais etiquetas a conversa já possui antes de modificá-las.

Atribua ou atualize as etiquetas

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

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

{
  "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

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

Exemplo de resposta

{
  "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

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

{
  "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:

{
  "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:

{
  "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.

Referência de API

Enviar Mensagens

Campanhas

Conversações

Etiquetas

Métricas

Usuários

Recursos

Widget

Datum

Painel de Atendimento Externo

Canal Personalizado

Gestão de Memória

Autenticação

1. Obter as etiquetas disponíveis da empresa

Endpoint

Parâmetros de rota

Parâmetros de consulta

Exemplo de solicitação

Exemplo de resposta

Detalhe da resposta

2. Obter as informações de uma conversa

Endpoint

Parâmetros de rota

Parâmetros de consulta

Exemplo de solicitação

Exemplo de resposta

3. Atribuir ou atualizar as etiquetas de uma conversa

Endpoint

Parâmetros de rota

Parâmetros do corpo

Exemplo de solicitação

Exemplo de resposta

Considerações

Exemplo

Códigos de resposta

​Autenticação

​1. Obter as etiquetas disponíveis da empresa

​Endpoint

​Parâmetros de rota

​Parâmetros de consulta

​Exemplo de solicitação

​Exemplo de resposta

​Detalhe da resposta

​2. Obter as informações de uma conversa

​Endpoint

​Parâmetros de rota

​Parâmetros de consulta

​Exemplo de solicitação

​Exemplo de resposta

​3. Atribuir ou atualizar as etiquetas de uma conversa

​Endpoint

​Parâmetros de rota

​Parâmetros do corpo

​Exemplo de solicitação

​Exemplo de resposta

​Considerações

​Exemplo

​Códigos de resposta

Autenticação

1. Obter as etiquetas disponíveis da empresa

Endpoint

Parâmetros de rota

Parâmetros de consulta

Exemplo de solicitação

Exemplo de resposta

Detalhe da resposta

2. Obter as informações de uma conversa

Endpoint

Parâmetros de rota

Parâmetros de consulta

Exemplo de solicitação

Exemplo de resposta

3. Atribuir ou atualizar as etiquetas de uma conversa

Endpoint

Parâmetros de rota

Parâmetros do corpo

Exemplo de solicitação

Exemplo de resposta

Considerações

Exemplo

Códigos de resposta