Flow Builder completo

Documentation Index

Fetch the complete documentation index at: https://docs.pingoai.com.br/llms.txt

Use this file to discover all available pages before exploring further.

​

Visao geral

O Flow Builder do ExclusiveDay tem duas camadas importantes:

• Editor visual (frontend): onde o time monta os nós e conexões.
• Engine de execucao (backend/channel): onde o fluxo roda de verdade.

Arquivos-chave:

• Editor: frontend/src/pages/FlowBuilderEditor/index.js
• Engine principal de nos (channel): channel-2/src/services/flow/runner.ts
• Registro de handlers de nos (channel): channel-2/src/services/flow/nodes/index.ts
• Normalizacao do diagrama: channel-2/src/services/flow/utils/flow.utils.ts
• Runner alternativo/simulacao (backend): Backend-1/src/services/FlowBuilderServices/FlowRunner.ts

​

Como a execucao funciona (channel)

1. Carrega o diagrama (nodes, edges, validation).
2. Inicializa variaveis de contexto (flow.user, flow.ticket, flow.channel, saudacao, datas).
3. Identifica o no start.
4. Executa no atual e escolhe proximo target.
5. Para nós que aguardam resposta, salva contexto de espera em sessao.
6. Quando o usuario responde, retoma no target correspondente.
7. Encerra no endFlow (limpa sessao e finaliza trace).

​

Tipos de no no editor (frontend)

Lista declarada em NODE_TYPES no FlowBuilderEditor:

• aiAgent (AI Agent)
• message (Mensagem)
• cta (CTA)
• hsm (Template HSM)
• interactive (Botoes/Listas)
• carousel (Carrossel)
• tag (Tags)
• queueTransfer (Transferir Atendimento)
• closeTicket (Finalizar Atendimento)
• randomizer (Distribuidor)
• condition (Condicao)
• delay (Delay)
• api (API Externa)
• webhook (Webhook)
• variable (Variavel)
• flowEnd (Fim do Fluxo)

​

O que cada no faz na execucao

​

start

• inicia trace do fluxo
• escolhe target success (ou next)
• passa para o primeiro no funcional

Handler: nodes/start/index.ts

​

message

• envia texto e/ou midia por canal
• suporta blocos e formatos de mensagem
• pode ativar espera de resposta (waitResponse/returnOptions)
• pode configurar inatividade e fallback por tempo

Handler: nodes/message/index.ts

​

interactive (botoes/listas)

• envia mensagem interativa (buttons/list)
• limita botoes e linhas conforme payload montado
• grava sessao aguardando resposta do usuario
• resposta selecionada determina o proximo target

Handler: nodes/interactive/index.ts

​

tag (tags do contato/ticket)

• vincula tags ao contato do ticket
• evita duplicar tags existentes
• segue para success (ou fallback)

Handler: nodes/tagTicket/index.ts

​

queueTransfer

• transfere ticket para fila/usuario/status
• atualiza tracking do ticket
• pode emitir notificacao socket

Handler: nodes/ticketTransfer/index.ts

​

closeTicket

• fecha ticket (status: closed)
• atualiza tracking de finalizacao
• emite evento de remocao no socket

Handler: nodes/closeTicket/index.ts

​

condition

• avalia condicoes com comparadores (eq, ne, gt, gte, lt, lte, contains, etc.)
• escolhe branch por indice (condition-0, condition-1, …)
• usa else quando nenhuma condicao casa

Handler: nodes/conditional/index.ts

​

delay

• aguarda tempo configurado (segundos na engine do channel)
• depois segue para next

Handler: nodes/waitTime/index.ts

​

variable

• grava/atualiza variaveis de fluxo em sessao
• permite reaproveitar dados em nos seguintes

Handler: nodes/flowVariable/index.ts

​

saveMessage (captura resposta)

• salva resposta do usuario em variavel customizada
• pode atualizar campos padrao (nome/email) e custom fields
• segue para success

Handler: nodes/saveMessage/index.ts

​

randomizer / split

• distribui caminho por percentual/peso
• escolhe target com base probabilistica

Handler: nodes/split/index.ts

​

jump

• salta para outro flow publicado
• carrega snapshot do flow destino
• opcionalmente retorna ao fluxo original

Handler: nodes/jump/index.ts

​

chatgpt

• chama API de completions da OpenAI
• salva resposta no contexto para proximo no
• segue por success ou error

Handler: nodes/chatgpt/index.ts

​

endFlow / flowEnd

• encerra fluxo e trace
• limpa sessoes relacionadas
• ajusta ticket para estado de saida (pending no handler atual)

Handler: nodes/endFlow/index.ts

​

Nos presentes no editor mas sem handler dedicado no channel

No registro nodes/index.ts, estes tipos estao em genericHandler (placeholder):

• json
• request
• dbQuery
• graphql
• code
• smtp
• closeTicket (existe handler dedicado em arquivo separado, mas no indice atual aparece generic)
• split (existe handler dedicado em arquivo separado, mas no indice atual aparece generic)
• timeInterval

Observacao importante:

• o editor mostra tipos como api, webhook, cta, hsm, carousel, aiAgent.
• para esses tipos, parte do comportamento pode depender de normalizacao/conversao de tipo e/ou fallback.
• em producao, sempre validar o caminho real no diagrama salvo (validation) e nos logs do runner.

​

Diferenca entre runner do channel e runner do backend

Existe tambem um runner em Backend-1/src/services/FlowBuilderServices/FlowRunner.ts:

• cobre fluxo simplificado (start, message, condition, delay, end)
• trata cta/interactive no bloco de mensagem simplificada
• usado em cenarios especificos de execucao/simulacao

Para fluxos ricos (com handlers de nos de integracao), o canal channel-2 e a referencia principal.

​

Boas praticas para construir fluxos

• sempre comecar por um start claro
• manter um caminho de erro/fallback por no critico
• em condition, nomear condicoes e revisar targets
• usar variable + saveMessage para contexto explicito
• evitar loops sem delay ou condicao de saida
• sempre fechar com flowEnd em caminhos terminais

​

Checklist de teste do Flow Builder

1. Publicar flow e confirmar validation com targets corretos.
2. Testar caminho feliz completo (inicio -> fim).
3. Testar caminho alternativo de condicao.
4. Testar timeout/inatividade quando configurado.
5. Testar captura de variavel e reutilizacao em mensagem seguinte.
6. Validar transferencia/finalizacao de ticket quando houver esses nos.
7. Conferir logs do runner para no executado e proximo target.