> ## 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ó d'Estructura de Dades
> Documentació oficial per extreure dades en brut de la base de dades
# Documentació oficial per extreure dades en brut de la base de dades
Aquest document té com a objectiu proporcionar accés i descripció de les principals estructures de dades disponibles per a l'empresa, facilitant la integració adequada, gestió i anàlisi d'informació relacionada amb les interaccions i agents participants.
A més de descriure l'estructura de cada taula, inclou recomanacions i advertències sobre el tractament responsable de dades personals que poden trobar-se als registres, destacant la importància de complir amb les normatives actuals de privadesa i seguretat de la informació.
Us suggerim revisar atentament cada definició de camp i les notes sobre el tractament de dades personals abans d'iniciar qualsevol procés d'integració o anàlisi, per garantir l'ús segur i adequat de la base de dades proporcionada.
Les dades presentades són en brut i no processades.
## Accedir a les Dades a ClickHouse mitjançant HTTP i Eines BI
Aquesta secció explica com connectar-se a la base de dades ClickHouse de Botslovers, ja sigui mitjançant accés HTTP directe (per exemple, utilitzant `curl`) o mitjançant eines gràfiques i d'Intel·ligència Empresarial com DBeaver, Power BI o Tableau.
### Accés mitjançant HTTP (exemple amb curl)
Podeu accedir a les dades executant consultes SQL directament contra la base de dades ClickHouse mitjançant la seva interfície HTTP.
**Exemple bàsic:**
Per recuperar els primers 10 registres de la taula `messages_`:
```bash theme={null}
curl -u user:'password' 'https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010'
```
Substituïu `user` i `password` per les vostres credencials personals.
El paràmetre `query` ha d'estar codificat en URL.
**Formats de resposta:**
Per defecte, la resposta està en format TabSeparated. Podeu sol·licitar altres formats afegint `FORMAT` al final de la consulta:
**Exemple JSON:**
```bash theme={null}
curl -u user:'password' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20JSON"
```
**Exemple CSV:**
```bash theme={null}
curl -u user:'password' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20CSV"
```
### Accés des d'Eines BI o Clients de Base de Dades (DBeaver, Power BI, Tableau, etc.)
ClickHouse admet connectors JDBC i ODBC, permetent utilitzar eines gràfiques per explorar i analitzar les dades.
#### Accés mitjançant DBeaver
* Obriu DBeaver i creeu una connexió nova.
* Seleccioneu ClickHouse com a tipus de base de dades.
* Trieu HTTP com a tipus de connexió.
* Ompliu els camps següents:
* Host: `public-clickhouse.botslovers.com`
* Port: `443`
* Usuari: el vostre nom d'usuari
* Contrasenya: la vostra contrasenya
* SSL: activat (assegureu-vos que la casella estigui marcada)
* Proveu la connexió i deseu.
#### Accés des d'Eines BI (Power BI, Tableau, etc.)
**Power BI**
* Baixeu i instal·leu el controlador ODBC oficial de ClickHouse.
* Configureu un DSN ODBC que apunti a:
* Host: `public-clickhouse.botslovers.com`
* Port: `443` (o `8443` segons la configuració, consulteu el vostre administrador)
* Mode SSL: activat
* Nom d'usuari/Contrasenya: les vostres credencials
* A Power BI, creeu una font de dades ODBC nova i seleccioneu el DSN configurat.
**Tableau**
* Podeu utilitzar el controlador ODBC de ClickHouse com a Power BI.
* Alternativament, utilitzeu el connector natiu ClickHouse.
## Seguretat i Millors Pràctiques
* Les vostres credencials són personals i no s'han de compartir.
* Consulteu el vostre administrador si teniu preguntes sobre límits d'ús o estructura de dades.
* Us recomanem evitar consultes que extreguin grans volums de dades per prevenir possibles problemes de rendiment del servei.
## Taules
### `messages`
Funciona com a repositori central on cada missatge individual generat en una conversa s'emmagatzema. Aquest document detalla els seus camps, propòsit i recomanacions específiques per gestionar dades sensibles de manera segura.
### `agent_activity`
Taules que concentren informació rellevant sobre agents — humans o automatitzats — que participen en converses. Faciliten l'associació d'esdeveniments i mètriques a cada agent per anàlisis d'activitat individuals, càlculs d'indicadors clau (com temps de resposta, tancaments de sessió, disponibilitat d'agents) i traçabilitat d'accions a través de converses, fins i tot quan es produeixen transferències.
## Descripcions de Taules
### `messages` (Taula: `messages_`)
Emmagatzema cada missatge intercanviat durant les converses.
| Camp | Tipus | Descripció |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sender_id` | String | Identificador únic del remitent que enllaça cada missatge a una entitat específica. |
| `sender_type` | String | Origen del missatge: `"user"`, `"bot"`, `"system"`, o `"human"`. |
| `id` | String | Clau única de cada missatge, assegurant la detecció de duplicats. |
| `created_at` | DateTime | Marca de temps en UTC per quan es va generar el missatge. |
| `channel` | String | Canal a través del qual es va enviar el missatge: `"whatsapp"` o `"web"` (widget). |
| `session` | String | Identificador de conversa que agrupa diversos missatges. |
| `direction` | String | Direcció del missatge: `"inbound"` o `"outbound"`. |
| `type` | String | Tipus comunicatiu: `"inbound"` (rebuda) o `"outbound"` (enviada). |
| `text` | String | Contingut complet de text lliure del missatge. Pot incloure text, emojis, emails, IDs, etc.
**Nota:** Pot ser `null` per imatges o documents. |
| `language` | String | Codi d'idioma (per exemple, `"ca"`, `"en"`).
**Nota:** Pot ser `null` si no es detecta. |
### `agent_activity` (Taula: `chat_agent_log_`)
Registra esdeveniments que es produeixen durant la interacció dels agents amb els xats.
| Camp | Tipus | Descripció |
| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | String | Identificador únic de l'esdeveniment. |
| `chat_id` | String | Identificador del xat associat. |
| `agent_id` | String | Identificador únic de l'agent implicat en l'esdeveniment. |
| `joined_at` | DateTime | Marca de temps UTC quan l'agent es va unir al xat. |
| `left_at` | Nullable(DateTime) | Marca de temps UTC quan l'agent va deixar el xat, o `null` si encara està actiu. |
| `event` | String | Tipus d'esdeveniment. Valors possibles: `bot_assigned`, `agent_timeout`, `user_timeout`, `agent_joined`, `chat_escalated`, `manual_close`, `resolved`, `assigned_to_human`, `transferred`. |
| `response_rating` | Nullable(Int16) | Valoració donada per la interacció, si n'hi ha. |
| `created_at` | DateTime | Marca de temps de creació del registre. |
| `updated_at` | DateTime | Marca de temps de l'última actualització del registre. |
| `deleted_at` | Nullable(DateTime) | Marca de temps d'eliminació lògica, si s'aplica. |
### `agent_status_logs` (Taula: `agent_status_logs_`)
Fa un seguiment de l'historial de canvis d'estat dels agents al llarg del temps, com el pas de "online" a "break".
| Camp | Tipus | Descripció |
| ------------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| `id` | String | Identificador únic del canvi d'estat. |
| `agent_id` | String | Identificador únic de l'agent. |
| `old_status` | String | Estat anterior de l'agent: `training`, `offline`, `break`, `ending_shift`, `inactive`, `online`. |
| `new_status` | String | Nou estat de l'agent: `training`, `offline`, `break`, `ending_shift`, `inactive`, `online`. |
| `status_changed_at` | DateTime | Marca de temps UTC quan va canviar l'estat. |
| `duration_seconds` | Nullable(Int64) | Durada en segons de l'estat anterior, o `null` si no s'aplica. |
| `created_at` | DateTime | Marca de temps de creació del registre. |
## Tractament de Dades Personals
La taula `messages_` , especialment la columna `text`, manté el contingut complet de les interaccions dels clients, potencialment contenint dades personals com noms, adreces de correu electrònic, números d'ID o altres detalls sobre els productes o serveis que ofereix la vostra empresa.
Aquests registres no s'han anonimitzat ni pseudonimitzat per preservar el context complet de cada conversa i garantir l'exactitud de l'anàlisi.
És **essencial** processar aquestes dades d'acord amb les normatives aplicables, mantenint sempre la confidencialitat, seguretat i els drets dels subjectes de dades.