Skip to main content

​
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_<empresa>: 
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: 
curl -u usuario:'contraseña' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20JSON"
Ejemplo CSV: 
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_<empresa>)

Almacena cada mensaje intercambiado durante las conversaciones.
CampoTipoDescripción
sender_idStringIdentificador único del remitente que vincula cada mensaje a una entidad específica.
sender_typeStringOrigen del mensaje: "user", "bot", "system" o "human".
idStringClave única de cada mensaje, garantizando la detección de duplicados.
created_atDateTimeMarca de tiempo en UTC de cuándo se generó el mensaje.
channelStringCanal a través del cual se envió el mensaje: "whatsapp" o "web" (widget).
sessionStringIdentificador de conversación que agrupa múltiples mensajes.
directionStringDirección del mensaje: "inbound" o "outbound".
typeStringTipo comunicativo: "inbound" (recibido) o "outbound" (enviado).
textStringContenido completo de texto libre del mensaje. Puede incluir texto, emojis, emails, IDs, etc.
Nota: Puede ser null para imágenes o documentos.
languageStringCódigo de idioma (ej. "es", "en").
Nota: Puede ser null si no se detectó.

​
agent_activity (Tabla: chat_agent_log_<empresa>)

Registra los eventos que ocurren durante la interacción de los agentes con los chats.
CampoTipoDescripción
idStringIdentificador único del evento.
chat_idStringIdentificador del chat asociado.
agent_idStringIdentificador único del agente involucrado en el evento.
joined_atDateTimeMarca de tiempo UTC de cuándo el agente se unió al chat.
left_atNullable(DateTime)Marca de tiempo UTC de cuándo el agente abandonó el chat, o null si aún está activo.
eventStringTipo de evento. Valores posibles: bot_assigned, agent_timeout, user_timeout, agent_joined, chat_escalated, manual_close, resolved, assigned_to_human, transferred.
response_ratingNullable(Int16)Calificación dada a la interacción, si la hay.
created_atDateTimeMarca de tiempo de creación del registro.
updated_atDateTimeMarca de tiempo de la última actualización del registro.
deleted_atNullable(DateTime)Marca de tiempo de eliminación lógica, si aplica.

​
agent_status_logs (Tabla: agent_status_logs_<empresa>)

Rastrea el historial de cambios de estado del agente a lo largo del tiempo, como la transición de “en línea” a “pausa”.
CampoTipoDescripción
idStringIdentificador único del cambio de estado.
agent_idStringIdentificador único del agente.
old_statusStringEstado anterior del agente: training, offline, break, ending_shift, inactive, online.
new_statusStringNuevo estado del agente: training, offline, break, ending_shift, inactive, online.
status_changed_atDateTimeMarca de tiempo UTC de cuándo cambió el estado.
duration_secondsNullable(Int64)Duración en segundos del estado anterior, o null si no aplica.
created_atDateTimeMarca 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.