> ## 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. # Documentazione Struttura Dati > Documentazione ufficiale per l'estrazione di dati grezzi dal database # Documentazione ufficiale per l'estrazione di dati grezzi dal database Questo documento ha lo scopo di fornire accesso e descrizione delle principali strutture dati disponibili per l'azienda, facilitando l'integrazione adeguata, la gestione e l'analisi delle informazioni relative alle interazioni e agenti partecipanti. Oltre a descrivere la struttura di ciascuna tabella, include raccomandazioni e avvisi riguardo al trattamento responsabile dei dati personali che possono essere trovati nei registri, evidenziando l'importanza del rispetto delle attuali normative sulla privacy e sicurezza delle informazioni. Suggeriamo di rivedere attentamente ciascuna definizione di campo e le note sul trattamento dei dati personali prima di iniziare qualsiasi processo di integrazione o analisi, per garantire l'uso sicuro e appropriato del database fornito. I dati presentati sono grezzi e non elaborati. ## Accesso ai Dati in ClickHouse via HTTP e Strumenti BI Questa sezione spiega come connettersi al database ClickHouse di Botslovers, sia tramite accesso HTTP diretto (ad esempio usando `curl`) che tramite strumenti grafici e Business Intelligence come DBeaver, Power BI o Tableau. ### Accesso via HTTP (esempio usando curl) È possibile accedere ai dati eseguendo query SQL direttamente sul database ClickHouse tramite la sua interfaccia HTTP. **Esempio Base:** Per recuperare i primi 10 record dalla tabella `messages_`: ```bash theme={null} curl -u user:'password' 'https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010' ``` Sostituisci `user` e `password` con le tue credenziali personali. Il parametro `query` deve essere codificato in URL. **Formati di Risposta:** Per impostazione predefinita, la risposta è in formato TabSeparated. È possibile richiedere altri formati aggiungendo `FORMAT` alla fine della query: **Esempio JSON:** ```bash theme={null} curl -u user:'password' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20JSON" ``` **Esempio CSV:** ```bash theme={null} curl -u user:'password' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20CSV" ``` ### Accesso da Strumenti BI o Client Database (DBeaver, Power BI, Tableau, ecc.) ClickHouse supporta connettori JDBC e ODBC, permettendo di utilizzare strumenti grafici per esplorare e analizzare i dati. #### Accesso via DBeaver * Apri DBeaver e crea una nuova connessione. * Seleziona ClickHouse come tipo di database. * Scegli HTTP come tipo di connessione. * Compila i seguenti campi: * Host: `public-clickhouse.botslovers.com` * Porta: `443` * Utente: il tuo nome utente * Password: la tua password * SSL: abilitato (assicurati che la casella sia selezionata) * Testa la connessione e salva. #### Accesso da Strumenti BI (Power BI, Tableau, ecc.) **Power BI** * Scarica e installa il driver ODBC ufficiale di ClickHouse. * Configura un DSN ODBC che punti a: * Host: `public-clickhouse.botslovers.com` * Porta: `443` (o `8443` a seconda della configurazione, verifica con il tuo amministratore) * Modalità SSL: abilitata * Nome utente/Password: le tue credenziali * In Power BI, crea una nuova origine dati ODBC e seleziona il DSN configurato. **Tableau** * Puoi utilizzare il driver ODBC di ClickHouse come in Power BI. * In alternativa, utilizza il connettore nativo ClickHouse. ## Sicurezza e Migliori Pratiche * Le tue credenziali sono personali e non devono essere condivise. * Consulta il tuo amministratore se hai domande sui limiti di utilizzo o sulla struttura dei dati. * Raccomandiamo di evitare query che estraggono grandi volumi di dati per prevenire potenziali problemi di performance del servizio. ## Tabelle ### `messages` Funziona come repository centrale dove ogni singolo messaggio generato in una conversazione è archiviato. Questo documento dettaglia i suoi campi, scopo e raccomandazioni specifiche per gestire i dati sensibili in modo sicuro. ### `agent_activity` Tabelle che concentrano informazioni rilevanti sugli agenti — umani o automatizzati — che partecipano alle conversazioni. Facilitano l'associazione di eventi e metriche a ciascun agente per analisi di attività individuali, calcoli di indicatori chiave (ad es. tempi di risposta, chiusure di sessione, disponibilità agenti) e tracciabilità delle azioni attraverso le conversazioni, anche quando si verificano trasferimenti. ## Descrizioni delle Tabelle ### `messages` (Tabella: `messages_`) Archivia ogni messaggio scambiato durante le conversazioni. | Campo | Tipo | Descrizione | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sender_id` | Stringa | Identificatore univoco del mittente che collega ciascun messaggio a una specifica entità. | | `sender_type` | Stringa | Origine del messaggio: `"user"`, `"bot"`, `"system"`, o `"human"`. | | `id` | Stringa | Chiave univoca di ciascun messaggio, garantendo il rilevamento di duplicati. | | `created_at` | DateTime | Timestamp in UTC per quando il messaggio è stato generato. | | `channel` | Stringa | Canale attraverso cui il messaggio è stato inviato: `"whatsapp"` o `"web"` (widget). | | `session` | Stringa | Identificatore di conversazione che raggruppa più messaggi. | | `direction` | Stringa | Direzione del messaggio: `"inbound"` o `"outbound"`. | | `type` | Stringa | Tipo comunicativo: `"inbound"` (ricevuto) o `"outbound"` (inviato). | | `text` | Stringa | Contenuto completo di testo libero del messaggio. Può includere testo, emoji, email, ID, ecc.
**Nota:** Può essere `null` per immagini o documenti. | | `language` | Stringa | Codice lingua (ad es. `"it"`, `"en"`).
**Nota:** Può essere `null` se non rilevato. | ### `agent_activity` (Tabella: `chat_agent_log_`) Registra eventi che si verificano durante l'interazione degli agenti con le chat. | Campo | Tipo | Descrizione | | ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Stringa | Identificatore univoco dell'evento. | | `chat_id` | Stringa | Identificatore della chat associata. | | `agent_id` | Stringa | Identificatore univoco dell'agente coinvolto nell'evento. | | `joined_at` | DateTime | Timestamp UTC quando l'agente si è unito alla chat. | | `left_at` | Nullable(DateTime) | Timestamp UTC quando l'agente ha lasciato la chat, o `null` se ancora attivo. | | `event` | Stringa | Tipo di evento. Valori possibili: `bot_assigned`, `agent_timeout`, `user_timeout`, `agent_joined`, `chat_escalated`, `manual_close`, `resolved`, `assigned_to_human`, `transferred`. | | `response_rating` | Nullable(Int16) | Valutazione data per l'interazione, se presente. | | `created_at` | DateTime | Timestamp di creazione del record. | | `updated_at` | DateTime | Timestamp dell'ultimo aggiornamento del record. | | `deleted_at` | Nullable(DateTime) | Timestamp di eliminazione logica, se applicabile. | ### `agent_status_logs` (Tabella: `agent_status_logs_`) Traccia la storia dei cambiamenti di stato degli agenti nel tempo, come il passaggio da "online" a "break". | Campo | Tipo | Descrizione | | ------------------- | --------------- | --------------------------------------------------------------------------------------------------- | | `id` | Stringa | Identificatore univoco del cambiamento di stato. | | `agent_id` | Stringa | Identificatore univoco dell'agente. | | `old_status` | Stringa | Stato precedente dell'agente: `training`, `offline`, `break`, `ending_shift`, `inactive`, `online`. | | `new_status` | Stringa | Nuovo stato dell'agente: `training`, `offline`, `break`, `ending_shift`, `inactive`, `online`. | | `status_changed_at` | DateTime | Timestamp UTC quando lo stato è cambiato. | | `duration_seconds` | Nullable(Int64) | Durata in secondi dello stato precedente, o `null` se non applicabile. | | `created_at` | DateTime | Timestamp di creazione del record. | ## Trattamento dei Dati Personali La tabella `messages_`, specialmente la colonna `text`, mantiene il contenuto completo delle interazioni dei clienti, potenzialmente contenente dati personali come nomi, indirizzi email, numeri ID o altri dettagli sui prodotti o servizi offerti dalla vostra azienda. Questi record non sono stati anonimizzati o pseudonimizzati per preservare il contesto completo di ciascuna conversazione e garantire l'accuratezza dell'analisi. È **essenziale** elaborare questi dati secondo le normative applicabili, mantenendo sempre la riservatezza, la sicurezza e i diritti dei soggetti interessati.