Gestión de etiquetas

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.

Obtén las etiquetas disponibles de la compañía

Recupera el catálogo con los id de cada etiqueta.

Consulta las etiquetas actuales de la conversación

Revisa qué etiquetas tiene asignadas la conversación antes de modificarlas.

Asigna o actualiza las etiquetas

Envía la lista completa de id que debe quedar en la conversación.

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.

Consulta Introducción para conocer cómo construir el encabezado Authorization: Basic.

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

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

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

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

Ejemplo de respuesta

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

Las etiquetas asignadas a una conversación se recuperan del atributo data.tags.

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

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

{
  "data": {
    "id": "abc123",
    "tags": [1, 2]
  },
  "message": "Tags assigned successfully."
}

Consideraciones

El arreglo enviado en tags reemplaza por completo las etiquetas actuales de la conversación. No agrega etiquetas a las existentes.

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:

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

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

API reference

Envío de mensajes

Campañas

Conversaciones

Etiquetas

Métricas

Usuarios

Recursos

Widget

Datum

Panel de Atención Externo

Canal Personalizado

Gestión de Memoria

Autenticación

1. Obtener etiquetas disponibles de la compañía

Endpoint

Parámetros de ruta

Parámetros de consulta

Ejemplo de solicitud

Ejemplo de respuesta

Detalle de la respuesta

2. Obtener información de una conversación

Endpoint

Parámetros de ruta

Parámetros de consulta

Ejemplo de solicitud

Ejemplo de respuesta

3. Asignar o actualizar etiquetas de una conversación

Endpoint

Parámetros de ruta

Parámetros del cuerpo

Ejemplo de solicitud

Ejemplo de respuesta

Consideraciones

Ejemplo

Códigos de respuesta

​Autenticación

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

​Endpoint

​Parámetros de ruta

​Parámetros de consulta

​Ejemplo de solicitud

​Ejemplo de respuesta

​Detalle de la respuesta

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

​Endpoint

​Parámetros de ruta

​Parámetros de consulta

​Ejemplo de solicitud

​Ejemplo de respuesta

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

​Endpoint

​Parámetros de ruta

​Parámetros del cuerpo

​Ejemplo de solicitud

​Ejemplo de respuesta

​Consideraciones

​Ejemplo

​Códigos de respuesta

Autenticación

1. Obtener etiquetas disponibles de la compañía

Endpoint

Parámetros de ruta

Parámetros de consulta

Ejemplo de solicitud

Ejemplo de respuesta

Detalle de la respuesta

2. Obtener información de una conversación

Endpoint

Parámetros de ruta

Parámetros de consulta

Ejemplo de solicitud

Ejemplo de respuesta

3. Asignar o actualizar etiquetas de una conversación

Endpoint

Parámetros de ruta

Parámetros del cuerpo

Ejemplo de solicitud

Ejemplo de respuesta

Consideraciones

Ejemplo

Códigos de respuesta