Fluxo - Novo Modelo de Configuração do Chabot

Modificado em Qua, 3 Jun na (o) 2:11 PM

Referência completa de todos os blocos disponíveis no editor de fluxo.

Como ler este documento

Quando usar	O cenário típico em que o bloco resolve o problema.
Configuração	Todos os campos da config (com defaults e limites).
Saídas (handles)	Para onde o fluxo pode seguir após o bloco.
Gotchas	Armadilhas comuns que valem a pena evitar.
type:	Tipo interno no JSON do fluxo, destacado no cabeçalho de cada node.

▶ Gatilhos

▶Início type: "start"

O que faz

Ponto de entrada padrão do fluxo. Cada fluxo tem exatamente um node Início, e ele dispara quando uma mensagem do contato chega num ticket vinculado ao fluxo.

Configuração

Nenhuma. O bloco é somente o ponto de entrada.

Saídas

● Saída (default)

Gotchas

⚠Se o ticket já estiver aberto com atendente humano (status="open" + userId setado), o fluxo não dispara.

⚠Mensagens fromMe (do bot/atendente) nunca disparam o fluxo.

⏲ Agendamento type: "scheduleTrigger"

O que faz

Dispara o fluxo automaticamente em horários definidos por uma expressão cron. Útil para campanhas recorrentes, lembretes diários e sincronizações periódicas.

Configuração

Campo	Tipo	Default	Descrição
`enabled`	boolean	true	Liga/desliga o trigger sem precisar remover.
`cron`	string	(vazio)	Expressão cron. Ex: `0 9 * * 1-5` (9h, segunda a sexta).
`timezone`	string	America/Sao_Paulo	Fuso usado para interpretar o cron.
`initialVars`	object	{}	Variáveis pré-carregadas no fluxo, acessíveis em qualquer node seguinte.

Gotchas

⚠Sem cron definido, o trigger fica parado — não dispara erro, só não roda.

⚠Execuções de schedule não têm ticket nem contact (headless). Use initialVars ou um node API/Script para carregar os contatos.

⚠Time-zone importa: 0 9 * * * em UTC é diferente de em America/Sao_Paulo.

? Receber Webhook type: "webhookTrigger"

O que faz

Cria uma URL pública. Quando um sistema externo faz POST nela, o fluxo dispara recebendo o body como initialVars.payload. Ideal para integrar CRM, ERP, formulários web ou receber notificações de pagamento.

Configuração

Campo	Default	Descrição
`enabled`	true	Liga/desliga sem remover.
`token`	(gerado no save)	Token único na URL. Não compartilhe.
`initialVars`	{}	Variáveis adicionais além de payload.

Saídas

● Saída (default) — a cada POST recebido

Gotchas

⚠O token só é gerado depois do primeiro save. Antes disso a URL não existe.

⚠O body chega cru em variables.payload. Para extrair campos, use um node Script ou Set Variable depois.

? Mensageria

? Conteúdo type: "content"

O que faz

Envia uma sequência de mensagens (texto e/ou mídia) ao contato. Itens são enviados na ordem com pequena pausa entre cada um para parecer natural.

Configuração

Campo	Descrição
`items[]`	Lista de itens. Cada item tem `kind` (`text`, `image`, `audio`, `video`, `document`) e o conteúdo correspondente.
`items[].text`	Texto (suporta `{{variaveis}}`).
`items[].url`	URL pública da mídia.
`items[].caption`	Legenda (opcional, para imagem/vídeo).

Gotchas

⚠Erro no envio de um item específico (URL inválida, mídia inacessível) é logado mas o fluxo continua com os próximos itens. Para WABA Cloud API, mídia precisa ser URL pública HTTPS.

❓ Pergunta type: "ask"

O que faz

Envia uma pergunta e pausa o fluxo aguardando a resposta do contato. A resposta é salva em uma variável. Pode validar formato e retentar automaticamente.

Configuração

Campo	Tipo	Descrição
`text`	string	A pergunta enviada ao contato (suporta variáveis).
`variableName`	string	Nome da variável onde a resposta é gravada.
`validation`	enum	`none`, `email`, `phone`, `cpf`, `cnpj`, `number`, `date`, `regex`.
`retry.enabled`	boolean	Se true, valida e retenta em caso de resposta inválida.
`retry.maxAttempts`	number	Máximo de tentativas antes de sair pelo handle `invalid`.
`noReply.enabled`	boolean	Se true, dispara timeout após X segundos sem resposta.

Saídas

● reply — resposta válida● invalid — estourou maxAttempts● no_reply — sem resposta no tempo● Saída (default)

Gotchas

⚠Sem variableName a resposta é descartada — sempre defina.

⚠retry requer validation ativa. Retry com validation: "none" não faz sentido.

⏸ Pausa type: "pause"

Pausa o fluxo por um intervalo de milissegundos. Útil entre mensagens para parecer natural. Para esperas longas (horas/dias), use o node Espera.

Campo	Default	Descrição
`mode`	fixed	`fixed`: pausa exata. `smart`: pausa aleatória entre min e max.
`minMilliseconds`	1500	Em `fixed`, é a duração; em `smart`, é o piso.
`maxMilliseconds`	1500	Só usado em `smart` (teto da janela aleatória).

? Opções type: "options"

Mostra uma lista de opções e pausa esperando o contato escolher. Funciona como menu numerado em qualquer canal (texto puro) e como botões nativos no WABA.

Campo	Descrição
`text`	Texto da pergunta (acima das opções).
`options[]`	Array `{id, label}`. Cada opção vira um handle de saída no canvas.
`saveAs`	Variável onde o label da escolha é salvo.
`noReply.enabled`	Timeout sem resposta → handle `no_reply`.

⚠O contato pode digitar o número da opção ou o label — o engine resolve. Sem options configuradas o node é inválido.

? Botões/Lista WABA type: "wabaInteractive"

Envia botões interativos (até 3) ou uma lista (até 10 linhas) usando a API nativa da WABA Cloud. Mais bonito e confiável que menu numerado.

Campo	Descrição
`mode`	`buttons` (máx 3) ou `list` (máx 10).
`body`	Texto da mensagem.
`header`	`{type: "none" \| "text" \| "image" \| "video" \| "document"}`.
`itemsSource`	`static` (lista fixa) ou `dynamic` (montada a partir de variável array).
`saveAs`	Variável onde o ID da escolha é salvo (default `lastSelectedOption`).
`textFallback`	Se true, em canais não-WABA envia versão texto numerada.

⚠WABA aceita no máximo 3 botões ou 10 linhas por mensagem.

⚠Itens dinâmicos precisam de arrayVar populado antes — geralmente um Script ou API anterior.

? Template WABA type: "wabaTemplate"

Envia um template HSM aprovado pela Meta. Único jeito de iniciar conversa fora da janela de 24h no WhatsApp Business.

Campo	Descrição
`templateHsmId`	ID do template no provedor.
`language`	Código do idioma (`pt_BR` etc).
`bodyParams[]`	Parâmetros do body do template, em ordem.
`headerMediaUrl`	URL da mídia do header (se o template tem).
`awaitReply`	Se true, pausa esperando resposta. Sai por `reply` ou `no_reply`.

Saídas

● success● reply (com awaitReply)● no_reply (com awaitReply)● error

⚠Template precisa estar aprovado pela Meta. Parâmetros têm que casar exatamente com o que foi submetido na aprovação (quantidade e ordem).

? Inteligência

? Agente IA type: "agent"

O bloco mais poderoso do fluxo. Conversa com o contato em linguagem natural usando um LLM (OpenAI). Pode chamar tools para agir (consultar API, transferir para humano, encerrar), coletar dados estruturados, lembrar de interações anteriores e agregar mensagens picadas. Decide sozinho quando sair do node escolhendo um handle de saída.

Anatomia — 6 abas no inspector

Aba	O que define
① Prompt	persona + promptTemplate (instruções).
② Coleta	Campos a extrair (nome, email, CPF, etc) com validação por tipo.
③ Tools	Ferramentas que o agente pode chamar (built-in + customizadas).
④ Saídas	Handles de saída do node + fallbacks de erro/maxTurns.
⑤ Memória	Pré-contexto, compactação, memória persistente, debounce.
⑥ Modelo	Modelo OpenAI + parâmetros de inferência.

① Prompt

Campo	Descrição
`persona`	Como o agente se apresenta. Entra no topo do system prompt. Mantenha curto (1–2 frases).
`promptTemplate`	Instruções específicas da tarefa. Aceita templates: `{{contact.name}}`, `{{produto}}`. Resolvido em runtime.

? A persona ditará o tom; o promptTemplate ditará o quê fazer. Mantenha a persona curta e o template detalhado.

② Coleta

Quando collection.enabled = true, o agente recebe a tool collect_data automaticamente.

Atributo	Descrição
`name`	Nome da variável de destino.
`description`	Texto que o LLM lê para entender o que coletar.
`type`	`text · email · phone · cpf · cnpj · number · date · enum · regex`
`required`	Se obrigatório. Com `guardrails.requireValidation`, o agente é obrigado a coletar antes de finalizar.
`example`	Exemplo mostrado ao LLM. Melhora a precisão da extração.

③ Tools (built-in)

Kind	Função	Quando o LLM usa
`end_success`	Encerra saindo pelo handle de sucesso.	Conversa atingiu o objetivo.
`end_error`	Encerra saindo pelo handle de erro.	Cliente desistiu, fora do escopo.
`transfer_human`	Transfere para fila/usuário humano.	Cliente pede atendente, caso complexo.
`datetime`	Retorna data/hora atual.	Calcular agendamento, validar se está aberto.
`http`	Faz request HTTP configurado.	Consultar estoque, status de pedido.
`knowledge_base`	Busca em base de FAQs.	Responder perguntas frequentes.
`collect_data`	(automática) Grava campos coletados.	Quando `collection.enabled`.
`route_to`	(automática) Escolhe handle de saída.	Quando há mais de 1 handle.

⑤ Memória — 4 mecanismos independentes

Mecanismo	Campo	Default	Descrição
Pré-contexto	`includeTicketHistory`	true	Hidrata o history com mensagens anteriores do ticket.
Pré-contexto	`historyMessages`	20	Últimas N mensagens do ticket.
Persistente	`persistAcrossSessions`	true	Lembra do contato em conversas futuras com o mesmo fluxo.
Compactação	`summarizeAfterTokens`	0 (off)	Sumariza histórico ao passar o limiar. Recomendado: 4000.
Compactação	`compactKeepTail`	6	Mensagens recentes preservadas após sumarizar.
Debounce	`debounceMs`	0 (off)	Agrega mensagens picadas. Recomendado: 4000 ms.

⑥ Modelo (LLM)

Campo	Default	Descrição
`model`	gpt-4o-mini	`gpt-4o-mini`, `gpt-4o`, `gpt-4-turbo`, `o1-mini`, `gpt-3.5-turbo`.
`temperature`	0.7	0 (determinístico) a 2 (criativo). Coleta: ≤ 0.3; conversação livre: 0.6–0.8.
`maxTokens`	1024	Tamanho máximo da resposta por turn.
`maxTurns`	15	Limite de rodadas LLM por sessão. Estourou → sai por `onMaxTurnsHandle`.

Saídas

● success — conversa atingiu o objetivo● error — erro de LLM, maxTurns, guardrail● handles customizados (via route_to)

Boas práticas

Temperatura baixa para coleta	Use 0.2–0.4 para dados estruturados. Para conversação livre, 0.6–0.8.
Modelo certo para a tarefa	gpt-4o-mini resolve a maioria dos casos a baixo custo. Use gpt-4o para raciocínio sofisticado.
Compactação em conv. longas	Ligue `summarizeAfterTokens: 4000` para controlar custo.
Descrição da tool é crucial	O LLM lê o `description` para decidir quando usar. Uma boa descrição vale mais que três frases no prompt.
Nome da tool	Sem acento e sem espaço. Use `consultar_pedido`, não "Consultar Pedido".
maxTurns alinhado à tarefa	Triagem rápida: 5–6 turnos. Coleta complexa ou suporte: 15–25.

⚙ Lógica

⏳Esperatype: "wait"

Pausa o fluxo por uma duração configurável sem ocupar o worker — agenda uma retomada futura via fila. Bom para esperas longas (horas/dias), campanhas e follow-ups.

Campo	Descrição
`mode`	`duration` (intervalo) ou `until` (data/hora alvo).
`durationValue / durationUnit`	Ex: `5 + minutes`. Unidades: `seconds`, `minutes`, `hours`, `days`.
`timezone`	Fuso para interpretar o `until`.

?Condiçãotype: "condition"

Ramifica o fluxo baseado no valor de uma variável. Cada branch tem operador, valor de comparação e label.

Operadores

equals · notEquals · contains · startsWith · endsWith · regex · gt · gte · lt · lte · isEmpty · isNotEmpty · fallback

⚠Sem branch fallback e nenhum match → o engine para nesse node. Sempre tenha um fallback.

⚠source aceita caminho com ponto: contact.customFields.cnpj.

?Variáveltype: "setVariable"

Define uma ou mais variáveis no contexto do fluxo. Valores podem ser literais ou templates {{variavel}}. Variáveis também viram customField do contato automaticamente.

Campo	Descrição
`assignments[]`	Lista `{name, value, valueKind}`. valueKind: `string`, `number`, `boolean`, `json`, `template`.

?APItype: "api"

Chamada HTTP a uma URL externa. Suporta todos os métodos, autenticação variada (Bearer, Basic, OAuth2, Custom Header), retry com backoff e mapeamento da resposta em variáveis.

Campo	Default	Descrição
`method`	GET	Método HTTP.
`bodyType`	none	`none`, `json`, `form`, `urlencoded`, `raw`.
`auth`	{type:"none"}	`none`, `basic`, `bearer`, `oauth2`, `customHeader`.
`timeoutMs`	30000	Timeout em ms.
`retry.enabled`	false	Re-tenta em erros de rede/5xx.
`responseVar`	(vazio)	Variável onde grava a resposta inteira.
`responseMap`	{}	Mapeia `{nomeVar: "$.json.path"}` (JSONPath).

● success (2xx)● error (4xx, 5xx, timeout)

{ } Script JStype: "script"

Roda um trecho de JavaScript em ambiente isolado e seguro. Útil para transformações, validações, cálculos e regras leves entre nodes. Não tem acesso à internet — para HTTP use o node API.

Disponível no código	O que é
`vars`	Todas as variáveis do fluxo (leitura).
`contact`	Dados do contato: `id`, `name`, `number`, `email`, `customFields`.
`ticket`	Dados do ticket: `id`, `status`, `channel`, `queueId`, `userId`.
`setVariable(name, value)`	Salva variável no fluxo (e no contato).
`console.log/warn/error`	Aparecem na aba "Logs" do node.

Exemplo

const total = produtos.reduce((s, p) => s + p.preco * p.qty, 0); setVariable("totalPedido", total); if (total > 1000) setVariable("temDesconto", true); return { ok: true, total };

?Enviar Webhooktype: "webhook"

Envia um POST (ou outro método) para uma URL externa com dados do contato/ticket/fluxo. Otimizado para notificar outro sistema, não para buscar dados.

Campo	Default	Descrição
`payload.mode`	preset	`preset` (flags abaixo) ou `custom` (JSON livre).
`payload.contact/ticket/variables`	true	Inclui dados do contato, ticket e variáveis no payload.
`fireAndForget`	false	Se true, não espera resposta e segue imediatamente.

⚠Use fireAndForget quando o resultado da chamada não importa para o fluxo — evita travar esperando timeout em endpoint lento.

?Horário Comercialtype: "businessHours"

Decide se está em horário de atendimento, fora do horário ou em feriado, e ramifica o fluxo nas três saídas correspondentes.

Campo	Default	Descrição
`timezone`	America/Sao_Paulo	Fuso usado para "agora".
`days[]`	seg-sex 9–18h	Array de 7 dias (Dom..Sab). Cada um: `{enabled, intervals[]}`.
`holidays[]`	(feriados nacionais)	Lista de `MM-DD`. Datas que sobrepõem a regra normal.

● open — dentro do horário● closed — fora do horário● holiday — feriado

⚡ Ações

⚡Açãotype: "action"

Executa uma sequência de operações sobre o ticket/contato/usuário. As steps rodam em ordem; se alguma é terminal (encerra ticket, transfere para humano), o fluxo para nela.

Tipos de step

Kind	Terminal?	O que faz
`addTag`	—	Adiciona tag ao contato.
`removeTag`	—	Remove tag.
`updateContact`	—	Atualiza campos do contato (nome, email, customFields).
`transferUser`	✓	Transfere o ticket para um atendente específico.
`transferQueue`	✓	Transfere para uma fila/departamento.
`transferFluxo`	✓*	Chama outro fluxo. Com `awaitReturn:true` volta ao terminar (sub-fluxo).
`closeTicket`	✓	Encerra o atendimento (motivo configurável).
`blockContact`	✓	Bloqueia o contato (blacklist ou broadcast).

⚠Steps são executadas em ordem. A primeira terminal interrompe o restante.

⚠transferFluxo com awaitReturn: true funciona como sub-fluxo: ao terminar, o cliente volta para o fluxo que chamou e segue dali.

? Glossário

Termo	Definição
Fluxo	Conjunto de blocos conectados que define como o atendimento acontece.
Node / Bloco	Cada elemento do fluxo. Pode mandar mensagem, perguntar, ramificar, chamar API, rodar IA, etc.
Handle / Saída	Pontos de saída de um bloco. Blocos simples têm 1 (default); outros têm vários identificados por nome.
Variável	Valor nomeado disponível ao longo do fluxo. Acessível por `{{nome}}` em qualquer campo de texto.
Template	A sintaxe `{{algo}}` que substitui pelo valor real em runtime.
Contato	A pessoa do outro lado da conversa. Tem nome, número, email e customFields.
Ticket	Cada atendimento aberto. Tem status, canal, fila, atendente responsável e fluxo associado.
Headless	Execução de fluxo sem um contato fixo na origem (Agendamento, Receber Webhook).
Sub-fluxo	Um fluxo chamado por outro via Ação com `awaitReturn: true`. Quando termina, o fluxo pai continua.
Tool / Ferramenta	Função que o Agente IA pode chamar entre respostas. O LLM lê nome e description para decidir quando usar.
Persona	Texto curto que define quem o Agente IA é (tom, papel). Aparece no topo do prompt.
Debounce	Janela de espera que agrega mensagens picadas do cliente. Cada nova mensagem reinicia o cronômetro.
WABA	WhatsApp Business API — canal oficial com botões nativos, templates aprovados e janela de 24h.
Template HSM	Mensagem pré-aprovada pela Meta. Único jeito de iniciar conversa fora da janela de 24h.
Fallback	Caminho "senão" — para onde o fluxo vai quando nenhuma condição coincidiu.
LLM	Large Language Model — o modelo de IA que gera as respostas do Agente. Hoje: OpenAI (GPT-4o, GPT-4o mini etc).
Token	Unidade de medida do que o LLM lê e escreve. ~4 caracteres = 1 token. Define o custo por rodada.