> ## 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. # Documentação de Estrutura de Dados > Documentação oficial para extração de dados brutos do banco de dados # Documentação oficial para extração de dados brutos do banco de dados Este documento tem como objetivo fornecer acesso e descrição das principais estruturas de dados disponíveis para a empresa, facilitando a integração adequada, o gerenciamento e a análise de informações relacionadas às interações e agentes participantes. Além de descrever a estrutura de cada tabela, inclui recomendações e alertas sobre o manuseio responsável de dados pessoais que podem ser encontrados nos registros, destacando a importância do cumprimento das regulamentações atuais de privacidade e segurança da informação. Recomendamos a revisão cuidadosa de cada definição de campo e das notas sobre o manuseio de dados pessoais antes de iniciar qualquer processo de integração ou análise, para garantir o uso seguro e adequado do banco de dados fornecido. Os dados apresentados são brutos e não processados. ## Acessando os Dados no ClickHouse via HTTP e Ferramentas BI Esta seção explica como se conectar ao banco de dados ClickHouse da Botslovers, seja por meio de acesso HTTP direto (por exemplo, usando `curl`) ou por meio de ferramentas gráficas e de Business Intelligence como DBeaver, Power BI ou Tableau. ### Acesso via HTTP (exemplo usando curl) Você pode acessar os dados executando consultas SQL diretamente no banco de dados ClickHouse por meio de sua interface HTTP. **Exemplo Básico:** Para recuperar os primeiros 10 registros da tabela `messages_`: ```bash theme={null} curl -u user:'password' 'https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010' ``` Substitua `user` e `password` pelas suas credenciais pessoais. O parâmetro `query` deve ser codificado em URL. **Formatos de Resposta:** Por padrão, a resposta está no formato TabSeparated. Você pode solicitar outros formatos adicionando `FORMAT` ao final da consulta: **Exemplo JSON:** ```bash theme={null} curl -u user:'password' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20JSON" ``` **Exemplo CSV:** ```bash theme={null} curl -u user:'password' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20CSV" ``` ### Acesso por Ferramentas BI ou Clientes de Banco de Dados (DBeaver, Power BI, Tableau, etc.) O ClickHouse suporta conectores JDBC e ODBC, permitindo o uso de ferramentas gráficas para explorar e analisar os dados. #### Acesso via DBeaver * Abra o DBeaver e crie uma nova conexão. * Selecione ClickHouse como tipo de banco de dados. * Escolha HTTP como tipo de conexão. * Preencha os seguintes campos: * Host: `public-clickhouse.botslovers.com` * Porta: `443` * Usuário: seu nome de usuário * Senha: sua senha * SSL: habilitado (certifique-se de que a caixa esteja marcada) * Teste a conexão e salve. #### Acesso por Ferramentas BI (Power BI, Tableau, etc.) **Power BI** * Baixe e instale o driver ODBC oficial do ClickHouse. * Configure um DSN ODBC apontando para: * Host: `public-clickhouse.botslovers.com` * Porta: `443` (ou `8443` dependendo da configuração, verifique com o administrador) * Modo SSL: habilitado * Nome de usuário/Senha: suas credenciais * No Power BI, crie uma nova fonte de dados ODBC e selecione o DSN configurado. **Tableau** * Você pode usar o driver ODBC do ClickHouse como no Power BI. * Alternativamente, use o conector nativo do ClickHouse. ## Segurança e Boas Práticas * Suas credenciais são pessoais e não devem ser compartilhadas. * Consulte o administrador se tiver dúvidas sobre limites de uso ou estrutura de dados. * Recomendamos evitar consultas que extraiam grandes volumes de dados para evitar problemas de desempenho no serviço. ## Tabelas ### `messages` Atua como o repositório central onde cada mensagem individual gerada em uma conversa é armazenada. Este documento detalha seus campos, propósito e recomendações específicas para o gerenciamento seguro de dados sensíveis. ### `agent_activity` Tabelas que concentram informações relevantes sobre agentes — humanos ou automatizados — participantes nas conversas. Facilitam a associação de eventos e métricas a cada agente para análise de atividade individual, cálculo de indicadores-chave (por exemplo, tempos de resposta, encerramento de sessões, disponibilidade do agente) e rastreabilidade de ações em conversas, mesmo quando ocorrem transferências. ## Descrições das Tabelas ### `messages` (Tabela: `messages_`) Armazena todas as mensagens trocadas durante as conversas. | Campo | Tipo | Descrição | | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sender_id` | String | Identificador único do remetente vinculando cada mensagem a uma entidade específica. | | `sender_type` | String | Origem da mensagem: `"user"`, `"bot"`, `"system"` ou `"human"`. | | `id` | String | Chave única de cada mensagem, garantindo detecção de duplicatas. | | `created_at` | DateTime | Carimbo de data/hora em UTC para quando a mensagem foi gerada. | | `channel` | String | Canal pelo qual a mensagem foi enviada: `"whatsapp"` ou `"web"` (widget). | | `session` | String | Identificador da conversa agrupando múltiplas mensagens. | | `direction` | String | Direção da mensagem: `"inbound"` ou `"outbound"`. | | `type` | String | Tipo comunicativo: `"inbound"` (recebida) ou `"outbound"` (enviada). | | `text` | String | Conteúdo completo de texto livre da mensagem. Pode incluir texto, emojis, e-mails, IDs, etc.
**Nota:** Pode ser `null` para imagens ou documentos. | | `language` | String | Código do idioma (ex.: `"es"`, `"en"`).
**Nota:** Pode ser `null` se não detectado. | ### `agent_activity` (Tabela: `chat_agent_log_`) Registra eventos que ocorrem durante a interação dos agentes com os chats. | Campo | Tipo | Descrição | | ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | String | Identificador único do evento. | | `chat_id` | String | Identificador do chat associado. | | `agent_id` | String | Identificador único do agente envolvido no evento. | | `joined_at` | DateTime | Carimbo de data/hora UTC quando o agente entrou no chat. | | `left_at` | Nullable(DateTime) | Carimbo de data/hora UTC quando o agente saiu do chat, ou `null` se ainda estiver ativo. | | `event` | String | Tipo de evento. Valores possíveis: `bot_assigned`, `agent_timeout`, `user_timeout`, `agent_joined`, `chat_escalated`, `manual_close`, `resolved`, `assigned_to_human`, `transferred`. | | `response_rating` | Nullable(Int16) | Avaliação dada pela interação, se houver. | | `created_at` | DateTime | Carimbo de data/hora de criação do registro. | | `updated_at` | DateTime | Carimbo de data/hora da última atualização do registro. | | `deleted_at` | Nullable(DateTime) | Carimbo de data/hora de exclusão lógica, se aplicável. | ### `agent_status_logs` (Tabela: `agent_status_logs_`) Rastreia o histórico de alterações de status dos agentes ao longo do tempo, como a transição de "online" para "pausa". | Campo | Tipo | Descrição | | ------------------- | --------------- | ------------------------------------------------------------------------------------------------ | | `id` | String | Identificador único da alteração de status. | | `agent_id` | String | Identificador único do agente. | | `old_status` | String | Status anterior do agente: `training`, `offline`, `break`, `ending_shift`, `inactive`, `online`. | | `new_status` | String | Novo status do agente: `training`, `offline`, `break`, `ending_shift`, `inactive`, `online`. | | `status_changed_at` | DateTime | Carimbo de data/hora UTC quando o status foi alterado. | | `duration_seconds` | Nullable(Int64) | Duração em segundos do status anterior, ou `null` se não aplicável. | | `created_at` | DateTime | Carimbo de data/hora de criação do registro. | ## Tratamento de Dados Pessoais A tabela `messages_`, especialmente a coluna `text`, retém o conteúdo completo das interações dos clientes, podendo conter dados pessoais como nomes, endereços de e-mail, números de documentos ou outros detalhes sobre os produtos ou serviços oferecidos pela sua empresa. Esses registros não foram anonimizados ou pseudonimizados para preservar o contexto completo de cada conversa e garantir a precisão da análise. É **essencial** processar esses dados de acordo com as regulamentações aplicáveis, mantendo sempre a confidencialidade, a segurança e os direitos dos titulares dos dados.