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.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, usandocurl) 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 tabelamessages_<empresa>:
user e password pelas suas credenciais pessoais.
O parâmetro
query deve ser codificado em URL.FORMAT ao final da consulta:
Exemplo JSON:
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)
- Host:
- 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(ou8443dependendo da configuração, verifique com o administrador) - Modo SSL: habilitado
- Nome de usuário/Senha: suas credenciais
- Host:
- No Power BI, crie uma nova fonte de dados ODBC e selecione o DSN configurado.
- 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_<empresa>)
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_<empresa>)
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_<empresa>)
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 tabelamessages_, 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.
É 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.