Toda conversa na Kontato passa por 3 estados ao longo do tempo. Saber em qual estado está ajuda a entender por que o bot às vezes responde, às vezes não — e onde encontrar conversas antigas.
Os 3 estados
1. Ativa
Conversa em andamento. É o estado padrão de toda conversa.
- Bot responde normalmente (se não estiver pausado)
- Aparece na tab Ativas
- Realtime atualiza mensagens novas
- No topo da conversa aberta: nome do contato + telefone com máscara (com
~no nome quando ainda é provisório). O estado fica indicado pela tab Ativas, não mais no header.
2. Encerrada
Conversa finalizada. Pode acontecer de 4 formas:
- Manualmente pelo dono — botão X no canto superior direito do card da conversa (no computador aparece quando você passa o mouse; no celular fica sempre visível). Abre uma confirmação e encerra na hora.
- Recomeço diário — todo dia às 00:05 (horário de Brasília) o sistema encerra todas as conversas ativas do dia (inclusive as pausadas) pra começar limpo no dia seguinte
- Automaticamente por inatividade — cron
cleanup(a cada 6h) marca como encerrada toda conversa ativa há mais de 24h sem nova mensagem - Bot encerra via tool — quando detecta fim natural (despedida do cliente, agendamento confirmado, dúvida resolvida), o bot chama internamente a tool
encerrar_conversa
Encerrar manual pelo card
Cada conversa ativa tem um X no canto do card. Ao clicar, você confirma num modal que explica o efeito: o histórico fica salvo na aba Encerradas, o bot para de responder, e a próxima mensagem do cliente abre uma conversa nova.
Quando encerra, a Kontato:
- Atualiza
status = "encerrada"no banco - Dispara análise de IA pra sugerir tags pro cliente (background)
- Conversa muda da tab Ativas pra tab Encerradas
- Próxima mensagem do cliente abre nova conversa ativa (não reabre a encerrada)
Encerrar não é deletar
Conversa encerrada continua acessível na tab Encerradas com todo o histórico legível. Mensagens só são deletadas muito depois (ver abaixo).
3. Arquivada
Conversa antiga, fora do dia-a-dia. Cron cleanup marca como arquivada toda conversa encerrada há mais de 30 dias.
- Não aparece na UI (nem na tab Ativas, nem na tab Encerradas)
- Status fica
arquivadano banco comarquivada_emregistrado - Cliente continua existindo em
/clientes - Próxima vez que cliente mandar mensagem, abre nova conversa ativa
Arquivadas não têm UI
É proteção de dados — depois de 30 dias encerrada, a conversa é considerada fechada definitivamente. Se precisar consultar algo dessa idade, abra um chamado no suporte.
Retenção de mensagens
A v0.30.0 corrigiu uma regra antiga que apagava mensagens com mais de 30 dias indistintamente (atingindo conversas ativas com histórico longo). A regra atual é mais conservadora:
- Mensagens são deletadas apenas quando a conversa está arquivada há mais de 1 ano
- Conversa em si permanece (só perde o conteúdo das mensagens)
- Conversas ativas e encerradas mantêm o histórico completo o tempo todo
1 ano = retenção real
Mensagens de conversas arquivadas há mais de 1 ano são apagadas pelo cron cleanup. Se precisa de algo importante (combinado, comprovante via texto), copie pra fora ou puxe via suporte antes desse prazo.
Transições
| De | Para | Trigger |
|---|---|---|
| (nova mensagem) | Ativa | Cliente manda primeira mensagem |
| Ativa | Encerrada | Você clica no X do card · meia-noite (recomeço diário) · 24h sem mensagem (cron) · bot detecta fim natural (tool) |
| Encerrada | Arquivada | 30 dias após encerrar (cron) |
| Arquivada | (mensagens apagadas) | 1 ano arquivada (cron) |
| Encerrada | Ativa | Cliente manda mensagem nova → abre nova conversa, não reativa a antiga |
Ciclo completo (exemplo)
- Dia 1, 14:00 — Maria manda "Bom dia" → conversa criada como Ativa
- Dia 1, 14:30 — Bot agendou pra ela. Cliente se despede ("ok obrigada!"). Bot encerra via tool.
- Dia 5 — Maria manda "Cheguei!" → nova conversa Ativa criada (a do dia 1 continua Encerrada)
- Dia 32 — conversa do dia 1 já está Encerrada há mais de 30 dias → cron move pra Arquivada (some da UI)
- Dia 397 — conversa arquivada há 1 ano → cron deleta as mensagens dela (a row da conversa permanece no banco vazia, pra histórico interno)
Cron cleanup — quando roda
- Frequência: a cada 6 horas
- Endpoint:
/api/cron/cleanup - 3 etapas em sequência:
- Encerra ativas sem mensagem há 24h+
- Arquiva encerradas há 30d+ (preenche
arquivada_em) - Deleta mensagens de arquivadas há mais de 1 ano
Sem ação manual sua. Só rola.
Cron de recomeço diário (00:05 BRT)
Separado do cleanup, um cron próprio (encerrar-conversas-dia) roda todo dia às 00:05 (horário de Brasília) e encerra todas as conversas ativas do dia — inclusive as que estão pausadas (automática ou manualmente). É o "recomeço diário": no dia seguinte, a próxima mensagem de cada cliente abre uma conversa nova, do zero, com o bot ativo. O histórico do dia anterior fica salvo na aba Encerradas.
Próximo passo
Você terminou a categoria Conversas! Conhece o cockpit, sabe assumir, busca, filtra, atribui tags, controla bot, lida com áudio/mídia, configura respostas fixas e entende ciclo de vida.
Próxima categoria — onde a mágica do bot vira receita: