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 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.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 usandocurl) 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 tabellamessages_<azienda>:
user e password con le tue credenziali personali.
Il parametro
query deve essere codificato in URL.FORMAT alla fine della query:
Esempio JSON:
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)
- Host:
- 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(o8443a seconda della configurazione, verifica con il tuo amministratore) - Modalità SSL: abilitata
- Nome utente/Password: le tue credenziali
- Host:
- In Power BI, crea una nuova origine dati ODBC e seleziona il DSN configurato.
- 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_<azienda>)
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_<azienda>)
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_<azienda>)
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 tabellamessages_, 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.
È essenziale elaborare questi dati secondo le normative applicabili, mantenendo sempre la riservatezza, la sicurezza e i diritti dei soggetti interessati.