Usuários e Históricos

Esta seção detalha a gestão inteligente de perfis, a sincronização de contextos globais e as regras de persistência da memória de chat do Menthor.

Fluxo Getter (Cadastro e Atualização)

O endpoint principal para a gestão de perfis é o /add_user_getter. Ele foi projetado para ser o ponto único de entrada de dados do usuário, garantindo integridade e performance.

  1. Idempotência: O sistema realiza um checksum dos dados enviados. O banco de dados só é atualizado se houver mudança real nos campos name, phone ou no dicionário de payload.

  2. Sincronização de Contextos: Este fluxo atua como sincronizador da Lista Global de Contextos. Sempre que dados de contextos inéditos são enviados no payload do usuário, o sistema atualiza automaticamente as definições globais para que a IA possa alternar entre bases de dados dinamicamente.

Validação de Identidade e Pareamento WhatsApp (OTP via E-mail)

Para assegurar que apenas colaboradores autorizados acessem os dados corporativos através do WhatsApp ou de canais de mensageria, o Menthor implementa um fluxo de verificação de identidade em duas etapas via One-Time Password (OTP).

Ciclo de Vida da Validação

  1. Recepção da Mensagem: A mensagem chega à API (via /sentence_streaming, /token_streaming ou /block_streaming) contendo o identificador do canal no payload (campo wpp_lid).

  2. Checagem de Pareamento Prévia: * Se o wpp_lid já pertencer ao cadastro do usuário no banco local, a requisição é autorizada imediatamente e a IA processa o prompt. * Se o wpp_lid for inédito ou não corresponder ao cadastro, o sistema suspende o atendimento e responde solicitando a identificação:

    «Olá! Não conseguimos identificar sua conta automaticamente. Por favor, digite o seu e-mail cadastrado…»

  3. Disparo do Código OTP: * O usuário digita seu e-mail no chat. * O sistema busca o e-mail no cadastro corporativo. Se encontrado, gera um código numérico de 6 dígitos criptograficamente seguro. * O código é despachado para a caixa de entrada do usuário via SMTP e a IA confirma exibindo o e-mail mascarado para privacidade (ex: j**o@empresa.com).

  4. Persistência de Sessão no Redis: * O desafio é armazenado no Redis com TTL de 300 segundos (5 minutos) sob a chave do canal. * Há um limite de segurança de 3 tentativas incorretas. Caso o limite seja atingido ou o tempo expire, o código é invalidado e um novo e-mail deve ser solicitado.

  5. Confirmação e Autorização: * Quando o usuário envia os 6 dígitos corretos, o sistema valida o código, remove o desafio ativo do Redis, grava o ``wpp_lid`` no cadastro do usuário e responde imediatamente no WhatsApp com a confirmação de autenticação e boas-vindas. * O código numérico de 6 dígitos não é encaminhado à LLM, evitando consumo desnecessário de tokens e garantindo que o número efêmero não polua a memória do chat. * A partir desse instante, o canal está pareado e todas as próximas mensagens são autorizadas e processadas pela IA de forma instantânea.

Dica

Entregabilidade e Filtros Anti-Spam: O bot instrui automaticamente o colaborador a verificar a pasta de Spam / Lixo Eletrônico caso não visualize a mensagem na Caixa de Entrada em instantes. Filtros de segurança de provedores corporativos (como Microsoft 365 ou Google Workspace) podem por vezes classificar mensagens automáticas nessas pastas secundárias.

Casos Especiais: Troca de Aparelho, Identificação e Invalidação de LID

O sistema contempla diferentes dinâmicas operacionais de mensageria:

  • Mensagem apenas com LID (Sem Telefone): Se o identificador de dispositivo (wpp_lid) já estiver gravado no perfil do usuário, o sistema autoriza o acesso instantaneamente, dispensando a presença do número de telefone no payload da mensagem.

  • Troca de Aparelho / Novo Dispositivo (Telefone Reconhecido + Novo LID): Se a mensagem contiver o telefone de um colaborador cadastrado, mas o wpp_lid recebido for diferente do cadastrado no banco (por exemplo, após trocar de smartphone, reinstalar o aplicativo ou em caso de suspeita de clonagem de linha): 1. O sistema reconhece a conta pelo telefone, dispensando a digitação do e-mail. 2. Dispara automaticamente o código OTP para o e-mail cadastrado daquele colaborador. 3. Notifica o WhatsApp com alerta de segurança («Identificamos uma alteração no seu WhatsApp. Por segurança, enviamos um código…»). 4. Ao digitar o código correto, o cadastro é atualizado com o novo LID.

  • Invalidação Automática de LID: Sempre que os dados de um usuário são atualizados com um novo número de telefone via endpoint /add_user_getter, o sistema invalida automaticamente o LID anterior (definindo lid = None), exigindo nova validação por segurança.

Manutenção de Usuários

  • Listagem Geral: Utilize /list_users para recuperar a relação de todos os usuários cadastrados.

  • Remoção Definitiva: Utilize /delete_user/{email}. Esta ação é permanente e remove todos os vínculos do usuário com o sistema.

Gestão de Memória e Histórico

O Menthor armazena as interações em arquivos JSON temporários localizados no diretório datasets/messages. O endpoint /user_history/{id_context} permite recuperar essas conversas de forma segmentada por origem.

O sistema identifica a origem da conversa através do padrão de nomenclatura do arquivo físico, permitindo que a aplicação cliente saiba por onde o usuário interagiu:

  • WhatsApp: Identificado pelo sufixo #wpp-.

  • Web (Email): Identificado pelo padrão #{email}-.

  • Web (Phone): Demais padrões capturados no diretório.

A memória do assistente é otimizada para manter a coerência com a estrutura de dados atual. Por isso, as seguintes regras se aplicam:

Aviso

Arquivos .lock: Arquivos com a extensão .lock são ignorados pelo endpoint de histórico. Eles indicam uma sessão em escrita ativa (conversa em processamento), e os dados só ficam disponíveis após a conclusão da resposta da IA.

Importante

Higiene de Dados (Reset de Memória): Sempre que o metadado de um banco de dados (Menthor DB) é atualizado via /receive_documents_db, os arquivos de histórico do respectivo contexto são automaticamente arquivados. Isso impede que a IA utilize memórias obsoletas de tabelas ou colunas que não existem mais.

Nota

Caso o endpoint de histórico retorne um erro 404, a aplicação cliente deve tratar como «Início de Jornada» (usuário novo) ou «Histórico Expirado» (histórico arquivado).