Construtor de fluxo (chatbot)

O construtor de chatbot do PEPINO ZAP — fluxos automáticos por número, com nós de mensagem, menu, entrada, condição, espera, transferência e encerramento. Como o gatilho dispara, o que cada tipo de nó faz, as variáveis disponíveis, o comportamento em tempo de execução e como montar um fluxo pelo editor visual ou pela API.

O construtor de fluxo é um chatbot visual: você desenha, num canvas, o caminho que uma conversa percorre — uma saudação, um menu de opções, uma pergunta, uma condição, uma espera — e a plataforma executa esse fluxo automaticamente quando uma mensagem chega, antes de qualquer atendente humano. É o mesmo recurso do editor de Fluxos no painel; esta página explica o modelo e como operá-lo pela API.

No painel: Fluxos → (novo/editar) — editor visual com arrastar-e-soltar.
Na API: Fluxos — o editor usa exatamente estes endpoints.

Anatomia de um fluxo

Um fluxo é um cabeçalho (nome, instância, gatilho, ativo) + um conjunto de nós ligados por arestas. Regras:

Um fluxo é vinculado a uma instância (número) — ou a nenhuma, valendo para qualquer número do Projeto.
Só 1 fluxo pode ficar ATIVO por instância. Ativar um desativa os outros daquela instância automaticamente.
O nó de menor ordem é o ponto de partida.
Cada nó tem uma posição no canvas (posicaoX/posicaoY) — puramente visual — e um conteudo (objeto JSON) cujo formato depende do tipo.

O gatilho

Quando o fluxo dispara para uma conversa nova:

`triggerType`	Dispara quando
`any`	Qualquer mensagem recebida inicia o fluxo.
`keyword`	Só quando o texto recebido contém o `triggerValue` (sem diferenciar maiúsculas).

Tipos de nó

Cada nó tem um tipo e um conteudo. Os formatos:

`message` — envia um texto

{ "texto": "Olá {{nome}}, tudo bem? Bem-vindo à Loja X." }

Envia a mensagem e segue para o próximo nó (aresta padrão). Suporta variáveis.

{
  "texto": "Como posso ajudar?",
  "options": [
    { "id": "opt_1", "numero": 1, "texto": "Falar com vendas", "targetNodeId": "nd_vendas" },
    { "id": "opt_2", "numero": 2, "texto": "Suporte", "targetNodeId": "nd_suporte" }
  ]
}

Envia o texto seguido das opções numeradas automaticamente (1. Falar com vendas …) e espera a resposta. O contato pode responder pelo número (1) ou pelo texto da opção. A resposta leva ao targetNodeId daquela opção. Resposta que não casa com nenhuma opção → o menu é reenviado.

`input` — pergunta e guarda a resposta

{ "texto": "Qual o seu nome?", "variavel": "nome_cliente" }

Envia a pergunta, espera a resposta e guarda o que o contato digitar na variável indicada (aqui, {{nome_cliente}}), disponível nos próximos nós. Depois segue pela aresta padrão.

`condition` — bifurca o caminho

{ "variavel": "nome_cliente", "operador": "contem", "valor": "João", "onTrue": "nd_a", "onFalse": "nd_b" }

Avalia variavel <operador> valor e vai para onTrue ou onFalse. Operadores: == (igual), != (diferente), contem (substring, sem diferenciar maiúsculas). Não envia mensagem — só decide o ramo.

`delay` — espera antes de seguir

{ "segundos": 30 }

Pausa o fluxo pelo tempo indicado e depois segue. A espera é não-bloqueante: a sessão fica agendada e um agendador a retoma quando o tempo vence — não trava o atendimento. 0 segue na hora; o teto é 24 horas (86400s).

`action` — gancho de automação

Nó reservado para automações (ex.: criar um negócio no funil). Hoje apenas segue para o próximo nó; é o ponto de extensão para evoluções.

`transfer` — entrega ao humano

Encerra a parte automática e transfere para um atendente, seguindo a política de roteamento do Projeto (menos ocupado, rodízio ou manual). É como o bot "passa o bastão".

`close` — encerra a conversa

Finaliza o fluxo e marca a conversa como resolvida. Use ao fim de um autoatendimento que não precisa de humano.

Variáveis

No início de cada sessão, o fluxo já recebe dados do contato, usáveis com {{chave}} em qualquer texto:

Variável	Conteúdo
`{{nome}}`	Nome do contato (push name do WhatsApp).
`{{numero}}`	Número do contato.
`{{numero_formatado}}`	Número do contato (formatado).
`{{mensagem_inicial}}`	O texto da primeira mensagem que disparou o fluxo.

Nós do tipo input adicionam novas variáveis (o que o contato responder). Uma variável inexistente é substituída por vazio.

Comportamento em tempo de execução

O bot tem precedência sobre o roteamento humano. Se há um fluxo ativo na instância, ele decide o atendimento; o roteamento automático para atendentes só entra quando o fluxo chega a um nó transfer.

Convivência com humano. Se a conversa já tem um atendente atribuído, o bot pausa — não atropela o atendimento humano em andamento.
Uma sessão por conversa. O estado (nó atual, variáveis, espera agendada) é mantido por conversa enquanto o fluxo roda.
Envio durável. As mensagens do bot saem pela fila de envio confiável (com retries), igual aos demais envios da API.
Proteção contra laço. Um fluxo mal montado (ciclo entre nós que não esperam resposta) é interrompido após um limite de passos, em vez de rodar para sempre.
Apagar o fluxo encerra as sessões que estiverem rodando nele.

Montando um fluxo pela API

O editor visual faz isto nos bastidores; você pode reproduzir programaticamente:

Crie o fluxo — POST /v1/flows com name, instanceId e triggerType. Nasce inativo.
Adicione os nós — POST /v1/flows/{id}/nodes, um por nó, com tipo, conteudo, posição e ordem (o menor é o início).
Ligue os nós — a aresta padrão (linear) com PATCH .../nodes/{nodeId}/connection (proximoNodeId); as saídas de um menu com PATCH .../nodes/{nodeId}/option-connection (liga cada optionId a um nó).
Ative — PATCH /v1/flows/{id} com active: true. Isso desativa os outros fluxos da mesma instância (conflito retorna 409).

Ao ativar, garanta que o fluxo tem um nó inicial (a menor ordem) e que as ligações levam a um nó terminal (transfer ou close) — senão a conversa pode ficar no bot sem saída para um humano. Teste no ambiente sandbox antes de ativar em produção.