> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Documentación de Estructura de Datos
> Documentación oficial para extraer datos en bruto de la base de datos
# Documentación oficial para extraer datos en bruto de la base de datos
Este documento tiene como objetivo proporcionar acceso y una descripción de las principales estructuras de datos disponibles para la empresa, con el fin de facilitar la correcta integración, gestión y análisis de la información relacionada con las interacciones y los agentes participantes.
Además de describir cada estructura de tabla, incluye recomendaciones y advertencias sobre el manejo responsable de los datos personales que pueden encontrarse en los registros, destacando la importancia de cumplir con las normativas vigentes de privacidad y seguridad de la información.
Sugerimos revisar cuidadosamente cada definición de campo y las notas sobre el manejo de datos personales antes de iniciar cualquier proceso de integración o análisis, para garantizar el uso seguro y adecuado de la base de datos proporcionada.
Los datos presentados son en bruto y sin procesar.
## Acceso a los Datos en ClickHouse mediante HTTP y Herramientas de BI
Esta sección explica cómo conectarse a la base de datos ClickHouse de Botslovers, ya sea mediante acceso HTTP directo (por ejemplo usando `curl`) o a través de herramientas gráficas y de Business Intelligence como DBeaver, Power BI o Tableau.
### Acceso mediante HTTP (ejemplo con curl)
Puedes acceder a los datos ejecutando consultas SQL directamente contra la base de datos ClickHouse a través de su interfaz HTTP.
**Ejemplo Básico:**
Para recuperar los primeros 10 registros de la tabla `messages_`:
```bash theme={null}
curl -u usuario:'contraseña' 'https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010'
```
Reemplaza `usuario` y `contraseña` con tus credenciales personales.
El parámetro `query` debe estar codificado como URL.
**Formatos de Respuesta:**
Por defecto, la respuesta está en formato TabSeparated. Puedes solicitar otros formatos añadiendo `FORMAT` al final de la consulta:
**Ejemplo JSON:**
```bash theme={null}
curl -u usuario:'contraseña' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20JSON"
```
**Ejemplo CSV:**
```bash theme={null}
curl -u usuario:'contraseña' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20CSV"
```
### Acceso desde Herramientas de BI o Clientes de Base de Datos (DBeaver, Power BI, Tableau, etc.)
ClickHouse admite conectores JDBC y ODBC, lo que te permite usar herramientas gráficas para explorar y analizar los datos.
#### Acceso mediante DBeaver
* Abre DBeaver y crea una nueva conexión.
* Selecciona ClickHouse como tipo de base de datos.
* Elige HTTP como tipo de conexión.
* Rellena los siguientes campos:
* Host: `public-clickhouse.botslovers.com`
* Puerto: `443`
* Usuario: tu nombre de usuario
* Contraseña: tu contraseña
* SSL: habilitado (asegúrate de que la casilla esté marcada)
* Prueba la conexión y guarda.
#### Acceso desde Herramientas de BI (Power BI, Tableau, etc.)
**Power BI**
* Descarga e instala el driver ODBC oficial de ClickHouse.
* Configura un DSN ODBC apuntando a:
* Host: `public-clickhouse.botslovers.com`
* Puerto: `443` (o `8443` según la configuración, consulta con tu administrador)
* Modo SSL: habilitado
* Usuario/Contraseña: tus credenciales
* En Power BI, crea una nueva fuente de datos ODBC y selecciona el DSN configurado.
**Tableau**
* Puedes usar el driver ODBC de ClickHouse como en Power BI.
* Alternativamente, usa el conector nativo de ClickHouse.
## Seguridad y Mejores Prácticas
* Tus credenciales son personales y no deben compartirse.
* Consulta con tu administrador si tienes preguntas sobre los límites de uso o la estructura de datos.
* Recomendamos evitar consultas que extraigan grandes volúmenes de datos para prevenir posibles problemas de rendimiento del servicio.
## Tablas
### `messages`
Actúa como el repositorio central donde se almacena cada mensaje individual generado en una conversación. Este documento detalla sus campos, propósito y recomendaciones específicas para gestionar los datos sensibles de forma segura.
### `agent_activity`
Tablas que concentran información relevante sobre los agentes — humanos o automatizados — que participan en las conversaciones. Facilitan la asociación de eventos y métricas a cada agente para el análisis de actividad individual, el cálculo de indicadores clave (ej. tiempos de respuesta, cierres de sesión, disponibilidad del agente) y la trazabilidad de acciones en las conversaciones, incluso cuando se producen transferencias.
## Descripción de Tablas
### `messages` (Tabla: `messages_`)
Almacena cada mensaje intercambiado durante las conversaciones.
| Campo | Tipo | Descripción |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sender_id` | String | Identificador único del remitente que vincula cada mensaje a una entidad específica. |
| `sender_type` | String | Origen del mensaje: `"user"`, `"bot"`, `"system"` o `"human"`. |
| `id` | String | Clave única de cada mensaje, garantizando la detección de duplicados. |
| `created_at` | DateTime | Marca de tiempo en UTC de cuándo se generó el mensaje. |
| `channel` | String | Canal a través del cual se envió el mensaje: `"whatsapp"` o `"web"` (widget). |
| `session` | String | Identificador de conversación que agrupa múltiples mensajes. |
| `direction` | String | Dirección del mensaje: `"inbound"` o `"outbound"`. |
| `type` | String | Tipo comunicativo: `"inbound"` (recibido) o `"outbound"` (enviado). |
| `text` | String | Contenido completo de texto libre del mensaje. Puede incluir texto, emojis, emails, IDs, etc.
**Nota:** Puede ser `null` para imágenes o documentos. |
| `language` | String | Código de idioma (ej. `"es"`, `"en"`).
**Nota:** Puede ser `null` si no se detectó. |
### `agent_activity` (Tabla: `chat_agent_log_`)
Registra los eventos que ocurren durante la interacción de los agentes con los chats.
| Campo | Tipo | Descripción |
| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | String | Identificador único del evento. |
| `chat_id` | String | Identificador del chat asociado. |
| `agent_id` | String | Identificador único del agente involucrado en el evento. |
| `joined_at` | DateTime | Marca de tiempo UTC de cuándo el agente se unió al chat. |
| `left_at` | Nullable(DateTime) | Marca de tiempo UTC de cuándo el agente abandonó el chat, o `null` si aún está activo. |
| `event` | String | Tipo de evento. Valores posibles: `bot_assigned`, `agent_timeout`, `user_timeout`, `agent_joined`, `chat_escalated`, `manual_close`, `resolved`, `assigned_to_human`, `transferred`. |
| `response_rating` | Nullable(Int16) | Calificación dada a la interacción, si la hay. |
| `created_at` | DateTime | Marca de tiempo de creación del registro. |
| `updated_at` | DateTime | Marca de tiempo de la última actualización del registro. |
| `deleted_at` | Nullable(DateTime) | Marca de tiempo de eliminación lógica, si aplica. |
### `agent_status_logs` (Tabla: `agent_status_logs_`)
Rastrea el historial de cambios de estado del agente a lo largo del tiempo, como la transición de "en línea" a "pausa".
| Campo | Tipo | Descripción |
| ------------------- | --------------- | ------------------------------------------------------------------------------------------------- |
| `id` | String | Identificador único del cambio de estado. |
| `agent_id` | String | Identificador único del agente. |
| `old_status` | String | Estado anterior del agente: `training`, `offline`, `break`, `ending_shift`, `inactive`, `online`. |
| `new_status` | String | Nuevo estado del agente: `training`, `offline`, `break`, `ending_shift`, `inactive`, `online`. |
| `status_changed_at` | DateTime | Marca de tiempo UTC de cuándo cambió el estado. |
| `duration_seconds` | Nullable(Int64) | Duración en segundos del estado anterior, o `null` si no aplica. |
| `created_at` | DateTime | Marca de tiempo de creación del registro. |
## Manejo de Datos Personales
La tabla `messages_`, especialmente la columna `text`, retiene el contenido completo de las interacciones con los clientes, pudiendo contener datos personales como nombres, direcciones de email, números de identificación u otros detalles sobre los productos o servicios que ofrece tu empresa.
Estos registros no han sido anonimizados ni pseudonimizados para preservar el contexto completo de cada conversación y garantizar la precisión del análisis.
Es **esencial** procesar estos datos de acuerdo con las regulaciones aplicables, manteniendo siempre la confidencialidad, la seguridad y los derechos de los titulares de los datos.