FormFlow

O FormFlow ajuda times a transformar conversas em dados estruturados prontos para operação, automação e analytics. A documentação abaixo foca em quando usar, como configurar e como operar no dia a dia.

​

Base URL

{{BASE_URL}}/api/externalAPIs/public/formFlow

​

Autenticação

Authorization: Bearer {{TOKEN}}

O hostId pode ser derivado do token ou enviado no body em cenários multi-host.

​

Para que serve

• Capturar dados de leads, conversas e formulários sem digitação manual
• Padronizar campos (email, telefone, empresa, etapa comercial) em toda a operação
• Atualizar valores em tempo real durante o atendimento
• Monitorar completude de formulários para identificar gaps de informação

​

Quando usar

• Atendimento comercial ou suporte que depende de dados estruturados
• Processos de qualificação de leads com campos obrigatórios
• Automação de playbooks que precisam de dados confiáveis por escopo
• Times que querem acompanhar progresso de captura em tempo real

​

Conceitos de uso

• Variável: campo tipado a ser capturado (ex.: email, telefone, nome)
• Formulário: conjunto de variáveis organizado por objetivo (ex.: pré-vendas)
• Valor: dado oficial registrado para um escopo
• Completude: percentual de campos obrigatórios preenchidos no formulário
• Escopo: onde o valor é único (lead, conversation, global, form)

​

Fluxo recomendado de adoção

1. Criar variáveis com keyName, tipo e escopo.
2. Criar catálogo (formulário) e associar as variáveis relevantes.
3. Executar captura por conversa com IA.
4. Consultar valores e completude para validar qualidade da coleta.
5. Opcional: automatizar ajustes com CRUD conversacional e monitorar via WebSocket.

​

Escopos e estratégia de escrita

​

Estratégias

• overwrite (unique_per_scope = true): substitui o valor oficial
• append (unique_per_scope = false): acumula valores distintos

​

Recursos de operação

• Captura orientada por IA a partir de conversas
• Atualização de valores e progresso em tempo real com WebSocket
• Rastreabilidade de execução para auditoria operacional
• Configuração de proteção de dados sensíveis

​

Operação via Interface

O FormFlow é totalmente operável pela interface do Tolky Create, sem necessidade de chamar a API. O menu Formulários organiza a operação em três abas:

​

Aba “Formulários” (/forms/list)

Editor visual de catálogos em duas colunas:

• Coluna esquerda — Configuração: nome, descrição, Escopo (lead / conversation / host), Janela de captura (período opcional), modo de execução (always ou conditional)
• Coluna direita — Campos: arrastar variáveis da biblioteca para o formulário, reordenar via drag-and-drop, marcar Obrigatório e Perguntar ao usuário por campo, sobrescrever descrição e instruções em tempo real
• Botão + Criar Campo abre modal para criar nova variável sem sair do editor
• Aba secundária Respostas exibe tabela de dados capturados para o formulário corrente, com contador de registros

Toggle no topo ativa/desativa o FormFlow no avatar inteiro. Toggle por catálogo ativa/desativa cada formulário individualmente — formulários inativos aparecem acinzentados na sidebar.

​

Aba “Variáveis” (/forms/fields)

Biblioteca global de variáveis disponíveis para qualquer formulário:

• Buscar, criar, editar, desabilitar ou excluir variáveis
• Cada variável mostra label, key (auto-slug), tipo (texto, email, número, telefone, datetime, url, boolean, enum), escopo (lead / conversation) e valores esperados (alerta visual se > 80 itens)
• Modal de criação cobre label, key, tipo, escopo, flag de obrigatório, descrição, instruções em tempo real e opções (para enum/json)

​

Aba “Dados Capturados” (/forms/captured-data)

Visão tabular dos leads e seus dados capturados, com filtros:

• Período: hoje, esta semana, este mês, intervalo customizado
• Formulário: filtra quais formulários exibir
• Filtro customizado: condições sobre qualquer campo capturado
• Seletor de colunas: alterna visibilidade de campos do sistema (createdAt, formulários, nome, telefone) e variáveis customizadas
• Detalhe do lead: linha do tempo de captura (quando cada campo foi preenchido, histórico de edição)
• Botão Criar campanha gera campanha a partir das linhas selecionadas

​

Modal de validação por campo

Cada campo do formulário pode ter regras de validação configuradas via FieldValidationModal, com regras específicas por tipo:

​

Edição manual pelo gestor

O gestor pode corrigir valores capturados diretamente pela interface. Ao salvar:

• O sistema marca edit_source = 'manual_edit' e registra o gestor que editou
• O campo entra em bloqueio: a IA não sobrescreve mais aquele valor até que seja explicitamente destravado
• O histórico (previews_values) preserva todas as versões anteriores com origem (ai_capture ou manual_edit) e identidade do editor
• Existe ação para destravar e devolver o campo ao fluxo de captura automática

Esse mecanismo dá ao gestor controle pontual sem perder a auditoria de origem de cada valor.

​

WebSocket

O namespace /formflow publica eventos de captura, progresso, atualização de valores e execução de steps.

• Guia completo em WebSocket

​

CRUD conversacional

O CRUD conversacional permite criar, consultar, atualizar e encadear operações do FormFlow a partir de instruções:

• Planner: Gerar plano de etapas
• Retomada: Retomar execução
• Ações e referências dinâmicas: Referência de ações

​

Endpoints disponíveis

​

Consultas

• Buscar campos — variáveis disponíveis no host
• Buscar catálogos — formulários existentes
• Schema de um catálogo — schema JSON completo
• Buscar valores capturados — valores oficiais por lead
• Schema de captura para conversa — campos pendentes por conversa

​

Mutações

• Criar variável
• Criar catálogo
• Atualizar variável
• Atualizar catálogo

​

Captura com IA

• Capturar a partir de conversas
• FormFlow v4 - batchAnalyzeDialogue

​

Doc Analyzer

• Guia FormFlow e Doc Analyzer
• Doc Analyzer - analyzeDialogue
• Doc Analyzer - batchAnalyzeDialogue
• Doc Analyzer - buildInstructionFromNatural

​

Outros

• WebSocket