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

​

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