Referência técnica dos nós do chatbot

Modelo mental

Como o motor lê um fluxo

Um fluxo publicado tem start, lista de nodes e lista de edges. Cada nó tem uma chave única, um tipo e uma configuração. Cada edge liga uma porta de saída a outro nó.

Campos comuns de um nó

id ou key: chave única do nó no fluxo.
type: tipo técnico do nó, como message, menu ou api.
title: rótulo exibido no editor e nos logs.
config: objeto JSON com campos específicos do tipo.
position: posição visual do nó no canvas.

Validação obrigatória

O fluxo precisa ter ao menos um nó.
O nó inicial precisa existir.
Chaves de nós não podem duplicar.
Conexões precisam apontar para portas válidas.
Menus precisam de opções com id, label e match.

Referência

Tipos de nó, configuração e portas

Esta tabela segue os tipos aceitos pelo runtime do RitmaChat.

Tipo	Uso	Configuração principal	Portas de saída
`message` Mensagem	Envia texto ao contato e segue automaticamente.	`text`. Também aceita texto no nível do nó por compatibilidade.	`default`, `next`
`question` Pergunta	Envia pergunta e aguarda resposta do contato.	`text`, `variable`, `timeout_minutes`, `max_attempts`.	`matched`, `fallback`, `timeout`, `default`
`menu` Menu	Mostra opções e escolhe a saída conforme a resposta.	`text`, `options` com `id`, `label` e `match`.	`option_<id>`, `fallback`, `timeout`, `default`
`condition` Condição	Compara variável do contexto e segue por verdadeiro ou falso.	`variable`, `operator`, `value`. Operadores: `equals`, `contains`, `not_empty`, `not_equals`.	`true`, `false`, `fallback`, `default`
`ai` IA	Chama OpenAI no runtime e pode salvar a resposta em variável.	`prompt`, `instructions`, `model`, `max_output_tokens`, `response_variable`.	`success`, `fallback`, `error`, `default`
`api` API externa	Faz chamada HTTP externa assinada ou simples.	`url`, `method`, `payload_template`, `timeout_seconds`, `response_variable`, `auth_endpoint_slug`.	`success`, `error`, `timeout`, `default`
`webhook` Webhook	Dispara endpoint externo cadastrado em webhooks do RitmaChat.	`endpoint_slug`, `payload_template`, `response_variable`.	`success`, `error`, `timeout`, `default`
`department` Departamento	Transfere atendimento para um departamento.	`department_slug`, `note`.	`handoff`, `not_found`, `default`
`human` Humano	Pausa o fluxo para atendimento humano.	`note`. Use para explicar o motivo do handoff.	`handoff`, `default`
`schedule` Agendamento	Cria lembrete ou mensagem agendada para a conversa.	`message`, `title`, `delay_minutes` ou `scheduled_for`.	`scheduled`, `error`, `default`
`end` Fim	Finaliza o fluxo e opcionalmente encerra ou arquiva a conversa.	`close_action` com `none`, `close` ou `archive`; `reason`.	Nenhuma.

Condições

Operadores e comparações

Condições devem ser simples e legíveis. Quando a regra ficar grande, divida em mais de um nó ou use API externa para decisão complexa.

Operador	Comportamento	Exemplo
`equals`	Valor da variável precisa ser igual ao valor esperado.	`answers.tipo` igual a `financeiro`.
`not_equals`	Segue por verdadeiro quando o valor é diferente.	Cliente não escolheu opção bloqueada.
`contains`	Texto precisa conter trecho informado.	Resposta contém `boleto`.
`not_empty`	Variável precisa existir e ter conteúdo.	Documento foi informado antes de chamar API.

Variáveis

Interpolação de texto

Textos, prompts e payloads podem usar variáveis no formato {{ nome_da_variavel }}. O runtime substitui valores conhecidos do contexto da conversa.

Variável	Origem	Exemplo de uso
`{{ input }}`	Última entrada recebida.	Enviar para IA ou API externa.
`{{ last_input }}`	Última resposta processada.	Condição ou prompt de qualificação.
`{{ protocol_number }}`	Protocolo da conversa.	Mensagem de confirmação ao cliente.
`{{ customer.name }}`	Cliente vinculado, quando disponível.	Personalizar saudação.
`{{ answers.nome }}`	Resposta salva por nó de pergunta.	Reusar dados coletados no fluxo.

Falhas

Timeout, fallback e erro

Todo nó que depende de resposta humana ou serviço externo precisa ter saída de contingência conectada.

Quando usar cada saída

fallback: resposta não bateu com menu, pergunta ou condição esperada.
timeout: contato ou serviço externo demorou mais que o limite configurado.
error: IA, API ou webhook retornou falha técnica.
not_found: departamento ou recurso referenciado não existe ou está inativo.
handoff: automação entregou o atendimento para humano ou departamento.

Padrão de recuperação

Explique ao contato que não foi possível concluir a etapa.
Salve contexto útil antes de transferir.
Envie para departamento com nota objetiva.
Finalize somente quando a operação aceita encerrar sem intervenção.

Exemplo

Menu com opções e portas

O id da opção define a porta option_<id>. Neste exemplo, as saídas válidas são option_financeiro e option_suporte.

{
  "id": "menu_inicial",
  "type": "menu",
  "title": "Menu inicial",
  "config": {
    "text": "Como podemos ajudar?",
    "options": [
      {"id": "financeiro", "label": "Financeiro", "match": ["1", "financeiro", "boleto"]},
      {"id": "suporte", "label": "Suporte", "match": ["2", "suporte", "ajuda"]}
    ],
    "timeout_minutes": 60,
    "max_attempts": 3
  }
}