Referência técnica (JSON)

Esta página descreve o arquivo de automação do Columba (.columba-flow.json): o mesmo que o botão Exportar do editor gera e que Importar, na lista de Automações, aceita. Serve para quem monta ou revisa fluxos fora do editor, inclusive com ajuda de uma IA.

Usa só o editor?

Você não precisa desta página. Ela é gerada a partir do código do Columba, então vale sempre para a versão atual.

Estrutura do arquivo

json

{
  "format": "columba-flow",
  "formatVersion": 1,
  "flow": {
    "name": "Nome do fluxo",
    "description": "Opcional",
    "triggerType": "trigger_new_conversation",
    "triggerConfig": { "allowedChannels": ["whatsapp"] },
    "priority": 50,
    "nodes": [ ... ],
    "edges": [ ... ]
  }
}

format e formatVersion são fixos.
triggerType é o type do nó gatilho e triggerConfig é o data dele. Se divergirem, a importação usa o tipo do nó e junta as duas configurações.
priority vai de 1 a 100 (padrão 50): quando mais de um fluxo publicado pode disparar na mesma conversa, o de número menor é avaliado primeiro.
O fluxo entra sempre como rascunho; nome repetido ganha "(importado)". Limite de 1 MB.
kbId do nó Resposta IA é ignorado: a importação aplica a Base do Assistente padrão da conta.
Ids de times, usuários, etapas do funil, números de WhatsApp e campanhas são da conta de origem. Se não existirem na conta que importa, a importação avisa e você escolhe de novo no editor. Em arquivo gerado fora do Columba, deixe esses campos vazios.

Nós

json

{ "id": "boas_vindas", "type": "action_send_text", "position": { "x": 320, "y": 240 }, "data": { "label": "Boas-vindas", "message": "Olá!" } }

id: texto único no fluxo (ex.: boas_vindas, n1).
type: um dos tipos do catálogo abaixo. Exatamente um gatilho por fluxo.
position: coordenadas no editor. Deixe ~320 px entre colunas e ~180 px entre linhas; mantenha o desenho em até ~3300 × 1950 px para caber na tela.
data.label: nome do passo no card. Os demais campos de data dependem do tipo.

Arestas

json

{ "id": "e3", "source": "espera_menu", "target": "menu", "sourceHandle": "true", "label": "Resposta" }

source e target são ids de nós. label é opcional (texto na seta).
sourceHandle diz de qual saída a aresta sai. Nós de saída única usam aresta sem sourceHandle; Condição, Aguardar Resposta, Limite Repetição e Checar Respostas usam "true"/"false"; a Escolha Múltipla usa o texto de cada opção e "default".
Uma saída sem aresta encerra a execução ali.
Para repetir um trecho, ligue a aresta de volta a um nó anterior (nunca ao gatilho) e proteja o laço com um Limite Repetição.

Variáveis

Campos marcados com "Aceita variáveis" trocam {{escopo.caminho}} pelo valor na hora de executar. Referência que não existe fica como texto literal — o contato veria as chaves.

Variável	Valor
`{{contact.name}}`, `{{contact.phone}}`, `{{contact.city}}`, `{{contact.state}}`	Dados do contato
`{{message.body}}`	Última mensagem do contato
`{{flow.nome}}`	Variável do fluxo (Definir Variável, Salvar informações da IA)
`{{flow.last_ai_response}}`	Última resposta do nó Resposta IA
`{{flow.http_response}}`, `{{flow.http_status}}`, `{{flow.http_error}}`	Resultado da Integração externa (aceita caminho: `{{flow.http_response.data.id}}`)
`{{flow._missing_vars}}`	O que faltou no Checar Respostas
`{{webhook.campo}}`	Corpo do POST do gatilho Webhook (aceita caminho: `{{webhook.lead.origem}}`)

Nomes de variável usam letras sem acento, números e _ (ex.: {{flow.nome_cliente}}).

O que a importação confere

A importação recusa o arquivo, listando todos os problemas, quando: um nó tem type que não existe, dois nós ou duas arestas repetem o id, uma aresta aponta para um nó que não existe, ou o fluxo não tem gatilho.

Ela importa com avisos quando algo vai funcionar diferente do esperado: campo que o nó não usa (com sugestão do nome certo), campo obrigatório vazio, valor fora das opções, sourceHandle que não existe, variável sem escopo, nó que nenhuma aresta alcança, saída de segurança (Timeout, Máximo) solta e ids que não existem na conta. A lista aparece na tela e pode ser copiada.

Catálogo de nós

Organizado como a barra lateral do editor. Para cada nó: o nome no editor, o type, os campos de data e as saídas. Campos marcados "O editor não mostra este campo" funcionam, mas só por arquivo.

Gatilhos

Nova Conversa — `trigger_new_conversation`

Inicia o fluxo quando uma conversa nova é criada com um contato.

Campo	Tipo	Obrigatório	Detalhes
`allowedChannels`	lista de opções	—	O gatilho só vale para conversas nestes canais. Vazio ou ausente = todos. Valores: `whatsapp` (WhatsApp), `webchat` (Webchat), `telegram` (Telegram).
`allowedWhatsappNumbers`	lista de ids	—	Ids dos números de WhatsApp (conectores) em que o gatilho vale. Vazio ou ausente = todos os números. Id de número de WhatsApp da conta.

Saída: uma só — aresta sem sourceHandle.

Mensagem Recebida — `trigger_message_received`

Inicia o fluxo a cada mensagem recebida do contato (quando não há outro fluxo em andamento).

Campo	Tipo	Obrigatório	Detalhes
`allowedChannels`	lista de opções	—	O gatilho só vale para conversas nestes canais. Vazio ou ausente = todos. Valores: `whatsapp` (WhatsApp), `webchat` (Webchat), `telegram` (Telegram).
`allowedWhatsappNumbers`	lista de ids	—	Ids dos números de WhatsApp (conectores) em que o gatilho vale. Vazio ou ausente = todos os números. Id de número de WhatsApp da conta.
`keywords`	texto (linhas)	—	Opcional: só dispara se a mensagem casar com uma destas palavras (uma por linha). O editor não mostra este campo.
`matchMode`	opção	—	Como comparar `keywords`. Valores: `contains` (Contém), `exact` (Exato), `regex` (Regex). Padrão: `"contains"`. O editor não mostra este campo.

Saída: uma só — aresta sem sourceHandle.

Conversa Reaberta — `trigger_conversation_reopened`

Inicia o fluxo quando o contato volta a escrever depois de a conversa ter sido encerrada.

Campo	Tipo	Obrigatório	Detalhes
`allowedChannels`	lista de opções	—	O gatilho só vale para conversas nestes canais. Vazio ou ausente = todos. Valores: `whatsapp` (WhatsApp), `webchat` (Webchat), `telegram` (Telegram).
`allowedWhatsappNumbers`	lista de ids	—	Ids dos números de WhatsApp (conectores) em que o gatilho vale. Vazio ou ausente = todos os números. Id de número de WhatsApp da conta.

Saída: uma só — aresta sem sourceHandle.

Palavra-Chave — `trigger_keyword`

Inicia o fluxo quando a mensagem do contato casa com uma das palavras-chave.

Campo	Tipo	Obrigatório	Detalhes
`keywords`	texto (linhas)	sim	Uma por linha. Sem nenhuma, o gatilho nunca dispara.
`matchMode`	opção	—	Comparação sem diferenciar maiúsculas. Valores: `contains` (Contém), `exact` (Exato), `regex` (Regex). Padrão: `"contains"`.
`allowedChannels`	lista de opções	—	O gatilho só vale para conversas nestes canais. Vazio ou ausente = todos. Valores: `whatsapp` (WhatsApp), `webchat` (Webchat), `telegram` (Telegram).
`allowedWhatsappNumbers`	lista de ids	—	Ids dos números de WhatsApp (conectores) em que o gatilho vale. Vazio ou ausente = todos os números. Id de número de WhatsApp da conta.

Saída: uma só — aresta sem sourceHandle.

Resposta Campanha — `trigger_campaign_reply`

Inicia o fluxo na primeira resposta do contato a uma mensagem de campanha (até 48 h depois).

Campo	Tipo	Obrigatório	Detalhes
`campaignId`	id	—	Id da campanha. Vazio = qualquer campanha. Id de campanha da conta.
`allowedChannels`	lista de opções	—	O gatilho só vale para conversas nestes canais. Vazio ou ausente = todos. Valores: `whatsapp` (WhatsApp), `webchat` (Webchat), `telegram` (Telegram).
`allowedWhatsappNumbers`	lista de ids	—	Ids dos números de WhatsApp (conectores) em que o gatilho vale. Vazio ou ausente = todos os números. Id de número de WhatsApp da conta.

Saída: uma só — aresta sem sourceHandle.

Negócio Mudou de Etapa — `trigger_deal_stage_changed`

Inicia o fluxo quando um negócio do funil muda de etapa (só entre etapas abertas, com conversa vinculada e aberta).

Campo	Tipo	Obrigatório	Detalhes
`allowedWhatsappNumbers`	lista de ids	—	Ids dos números de WhatsApp (conectores) em que o gatilho vale. Vazio ou ausente = todos os números. Id de número de WhatsApp da conta.

Saída: uma só — aresta sem sourceHandle.

As etapas que disparam são configuradas em Configurações › Funil de vendas, não no nó.

Negócio Parado — `trigger_deal_stale`

Inicia o fluxo quando um negócio passa do limite de dias sem atividade definido para a etapa.

Campo	Tipo	Obrigatório	Detalhes
`allowedWhatsappNumbers`	lista de ids	—	Ids dos números de WhatsApp (conectores) em que o gatilho vale. Vazio ou ausente = todos os números. Id de número de WhatsApp da conta.

Saída: uma só — aresta sem sourceHandle.

O limite de dias por etapa é configurado em Configurações › Funil de vendas.

Lead Sem Resposta — `trigger_deal_no_reply`

Em breve: iniciará o fluxo quando o lead ficar sem responder. HOJE NÃO DISPARA.

Campo	Tipo	Obrigatório	Detalhes
`allowedWhatsappNumbers`	lista de ids	—	Ids dos números de WhatsApp (conectores) em que o gatilho vale. Vazio ou ausente = todos os números. Id de número de WhatsApp da conta.

Saída: uma só — aresta sem sourceHandle.

Não use em fluxos de cliente: o gatilho ainda não dispara. Para retomar leads parados, use Negócio Parado.

Webhook — `trigger_webhook`

Um sistema externo faz POST na URL do fluxo: o contato é localizado ou criado pelo telefone e o fluxo começa com o corpo do POST em {{webhook.*}}.

Campo	Tipo	Obrigatório	Detalhes
`channel`	opção	—	`whatsapp` abre a conversa no número e fala com o contato; `none` roda só ações internas. Valores: `whatsapp` (WhatsApp), `none` (Sem canal). Padrão: `"whatsapp"`.
`instanceId`	id	—	Id do número por onde a conversa nasce. Vazio = primeiro número conectado. Id de número de WhatsApp da conta.
`phoneField`	texto	—	Caminho do telefone no corpo do POST (ex.: `phone`, `lead.telefone`). Padrão: `"phone"`.
`nameField`	texto	—	Caminho do nome no corpo do POST. Padrão: `"name"`.
`emailField`	texto	—	Caminho do e-mail no corpo do POST (opcional).
`defaultCountryCode`	texto	—	DDI aplicado quando o telefone chega sem código do país. Padrão: `"55"`.
`contactTags`	lista de textos	—	Nomes de tags aplicadas ao contato (novo ou existente).
`contactSource`	texto	—	Origem gravada no contato novo. Padrão: `"webhook"`.
`onActiveFlow`	opção	—	Se já houver um fluxo rodando na conversa: reinicia ou ignora o evento. Valores: `restart` (Reiniciar), `skip` (Ignorar). Padrão: `"restart"`.

Saída: uma só — aresta sem sourceHandle.

A URL e o token do webhook são gerados pelo Columba depois de salvar; nunca vêm no arquivo.

Com channel: "none", nós que falam com o contato (mensagens, IA, Aguardar Resposta, transferir, encerrar) são pulados.

Ações

Enviar Texto — `action_send_text`

Envia uma mensagem de texto ao contato.

Campo	Tipo	Obrigatório	Detalhes
`message`	texto (linhas)	sim	Texto enviado. Vazio = o nó é pulado. Aceita variáveis.

Saída: uma só — aresta sem sourceHandle.

Precisa de conversa: é pulado quando o gatilho de webhook roda em modo "Sem canal".

Enviar Mídia — `action_send_media`

Envia imagem, vídeo, documento ou áudio (nota de voz) ao contato.

Campo	Tipo	Obrigatório	Detalhes
`mediaType`	opção	—	Tipo do arquivo. Valores: `image` (Imagem), `video` (Vídeo), `document` (Documento), `audio` (Áudio (nota de voz)). Padrão: `"image"`.
`mediaUrl`	texto	sim	URL pública (https) do arquivo. No editor, o upload preenche sozinho. Aceita variáveis.
`caption`	texto (linhas)	—	Legenda opcional (ignorada em áudio). Aceita variáveis.

Saída: uma só — aresta sem sourceHandle.

Precisa de conversa: é pulado quando o gatilho de webhook roda em modo "Sem canal".

Botões/Lista — `action_send_interactive`

Envia uma mensagem com até 3 botões de resposta rápida.

Campo	Tipo	Obrigatório	Detalhes
`bodyText`	texto (linhas)	sim	Texto principal da mensagem. Aceita variáveis.
`buttons`	texto (linhas)	sim	Um botão por linha, no máximo 3 (as demais linhas são ignoradas), até 20 caracteres cada.
`title`	texto	—	Título opcional. Aceita variáveis. O editor não mostra este campo.
`footer`	texto	—	Rodapé opcional. Aceita variáveis. O editor não mostra este campo.

Saída: uma só — aresta sem sourceHandle.

Precisa de conversa: é pulado quando o gatilho de webhook roda em modo "Sem canal".

O nó só ENVIA. Para ramificar pela escolha, ligue-o a um Aguardar Resposta e, na saída Resposta, a uma Escolha Múltipla com os mesmos textos dos botões.

Se o envio dos botões falhar, o Columba manda o texto com as opções numeradas (1., 2., 3.). Em menus longos ou números por QR Code, prefira Enviar Texto com opções numeradas + Escolha Múltipla com 1, 2, 3.

Resposta IA — `action_ai_response`

A IA responde o contato seguindo as instruções do nó e consultando a Base do Assistente.

Campo	Tipo	Obrigatório	Detalhes
`systemPrompt`	texto (linhas)	sim	Prompt do assistente: papel, tom, o que fazer, regras e quando transferir. Vazio = "Você é um assistente de atendimento." Aceita variáveis.
`model`	opção	—	Modelo de IA. Valores: `claude-haiku-4-5` (Claude Haiku 4.5). Padrão: `"claude-haiku-4-5"`.
`temperature`	número	—	0 = preciso, 1 = criativo. De 0 a 1. Padrão: `0.7`.
`ragEnabled`	true/false	—	Consulta a base de conhecimento antes de responder. Padrão: `false`.
`kbId`	texto	—	Id da base de conhecimento. Ignorado na importação: o Columba aplica a base padrão da conta (e liga `ragEnabled`).
`toolsEnabled`	true/false	—	A IA pode executar ações sozinha (as de `enabledTools`). Padrão: `false`.
`enabledTools`	lista de opções	—	Ferramentas liberadas no Modo Autônomo. Vazio = todas, menos as opt-in (funil e imóveis), que só entram se listadas. Valores: `tag_contact` (Adicionar/remover tags), `transfer_to_human` (Transferir para humano), `close_conversation` (Encerrar conversa), `update_contact` (Atualizar dados do contato), `notify_team` (Notificar equipe), `save_information` (Salvar informações (variáveis do fluxo)), `list_tickets` (Consultar chamados), `create_ticket` (Abrir chamado), `create_deal` (Registrar negócio (funil, opt-in)), `update_deal` (Qualificar negócio (funil, opt-in)), `move_deal_stage` (Mover de etapa (funil, opt-in)), `mark_deal_lost` (Marcar perda (funil, opt-in)), `search_property_listings` (Buscar imóveis (nicho, opt-in)), `search_knowledge_base` (Buscar na base (automática com ragEnabled + kbId)).
`silent`	true/false	—	Sem Modo Autônomo: não envia ao contato, só guarda a resposta em `{{flow.last_ai_response}}` (para classificar, resumir etc.). Padrão: `false`.
`mediaEnabled`	true/false	—	Imagens e PDFs recentes do contato vão para a IA. Padrão: `true`.

Saída: uma só — aresta sem sourceHandle.

Precisa de conversa: é pulado quando o gatilho de webhook roda em modo "Sem canal".

A resposta fica em {{flow.last_ai_response}} (útil numa Condição com field: "ai.lastResponse").

Para a IA conversar várias rodadas, faça o laço Resposta IA → Aguardar Resposta → Limite Repetição → Resposta IA.

Aguardar — `action_delay`

Pausa o fluxo pelo tempo configurado e depois continua.

Campo	Tipo	Obrigatório	Detalhes
`duration`	número	—	Quantidade de tempo. Mínimo 1. Padrão: `5`.
`unit`	opção	—	Unidade da duração. Valores: `seconds` (Segundos), `minutes` (Minutos), `hours` (Horas). Padrão: `"minutes"`.

Saída: uma só — aresta sem sourceHandle.

Definir Variável — `action_set_variable`

Guarda um valor numa variável do fluxo, lida depois como {{flow.nome}}.

Campo	Tipo	Obrigatório	Detalhes
`varName`	texto	sim	Nome sem espaços e sem `{{ }}` (ex.: `nome_cliente`).
`varValue`	texto	—	Valor fixo ou variável (ex.: `{{message.body}}` guarda o que o contato acabou de escrever). Aceita variáveis.

Saída: uma só — aresta sem sourceHandle.

Integração externa — `action_http_request`

Chama uma API externa. A resposta fica em {{flow.http_response}} e o status em {{flow.http_status}}.

Campo	Tipo	Obrigatório	Detalhes
`method`	opção	—	Método HTTP. Valores: `GET` (GET), `POST` (POST), `PUT` (PUT), `DELETE` (DELETE). Padrão: `"GET"`.
`url`	texto	sim	Endereço chamado. Aceita variáveis.
`body`	texto (linhas)	—	Corpo enviado como `application/json` (ignorado em GET). Aceita variáveis.

Saída: uma só — aresta sem sourceHandle.

Não há campo de cabeçalhos: autenticação só por parâmetro na URL ou no corpo.

Em falha de rede, o erro fica em {{flow.http_error}} e o fluxo segue.

Lógica

Condição — `logic_condition`

Compara um valor com o que você definir e segue por Sim ou Não.

Campo	Tipo	Obrigatório	Detalhes
`field`	opção	—	O que comparar. O motor também aceita uma referência direta (ex.: `webhook.lead.origem`, `flow.http_response.status`), mas o editor só oferece as opções listadas. Valores: `message.body` (Conteúdo da Mensagem), `ai.lastResponse` (Resposta da IA), `contact.city` (Cidade do Contato), `contact.tags` (Tags do Contato), `flow.variable` (Variável da Automação). Padrão: `"message.body"`.
`variableName`	texto	—	Com `field: "flow.variable"`: nome da variável (sem `{{flow. }}`).
`operator`	opção	—	Comparação, sem diferenciar maiúsculas. Valores: `contains` (Contém), `equals` (Igual a), `starts_with` (Começa com), `not_contains` (Não contém), `regex` (Regex). Padrão: `"contains"`.
`value`	texto (linhas)	sim	Um ou mais valores, um por linha: basta um casar (em "Não contém", nenhum pode casar).

Saídas: true = Sim: a condição é verdadeira; false = Não: a condição é falsa.

Escolha Múltipla — `logic_switch`

Ramifica pela última mensagem do contato: uma saída para cada opção e uma saída Padrão.

Campo	Tipo	Obrigatório	Detalhes
`switchOptions`	texto (linhas)	sim	Uma por linha (ex.: `1`, `2`, `3` ou `Vendas`). A mensagem inteira do contato é comparada com cada opção, sem diferenciar maiúsculas e acentos.

Saídas: uma por opção de switchOptions (sourceHandle = texto exato da opção) e default (nenhuma opção casou).

Cada aresta de saída usa como sourceHandle o texto EXATO da opção (como está em switchOptions), ou default para a saída Padrão.

Compara a mensagem inteira: "quero vendas" não casa com a opção "Vendas". Para menus, peça ao contato um número.

Coloque depois de um Aguardar Resposta (saída Resposta), para comparar a resposta ao menu.

Aguardar Resposta — `logic_wait_for_reply`

Pausa o fluxo até o contato responder, com tempo limite.

Campo	Tipo	Obrigatório	Detalhes
`timeoutMinutes`	número	—	Tempo máximo desta espera. De 1 a 1440. Padrão: `30`.
`maxConversationMinutes`	número	—	Opcional: prazo que começa na primeira espera e vale para as seguintes. 0 desliga. De 0 a 1440. Padrão: `0`.
`timeoutNodeId`	texto	—	Alternativa à saída `false`: id do nó para onde ir no timeout. Prefira a aresta `false`. O editor não mostra este campo.

Saídas: true = Resposta: o contato respondeu dentro do prazo; false = Timeout: o prazo venceu sem resposta.

Precisa de conversa: é pulado quando o gatilho de webhook roda em modo "Sem canal".

Sempre ligue a saída false (Timeout) — solta, a execução termina em silêncio quando o contato some.

Limite Repetição — `logic_loop_guard`

Evita que um trecho do fluxo se repita sem fim (por contador ou por avaliação da IA).

Campo	Tipo	Obrigatório	Detalhes
`mode`	opção	—	`counter` conta voltas; `ai_judge` pede à IA, a cada N voltas, para ver se a conversa travou. Valores: `counter` (Contador de iterações), `ai_judge` (Avaliação por IA). Padrão: `"counter"`.
`maxIterations`	número	—	Modo `counter`: voltas permitidas antes de sair por `false`. De 1 a 100. Padrão: `5`.
`judgeEvery`	número	—	Modo `ai_judge`: de quantas em quantas voltas a IA avalia. De 2 a 50. Padrão: `5`.
`hardLimit`	número	—	Modo `ai_judge`: teto de voltas, mesmo com a conversa avançando. De 5 a 200. Padrão: `30`.

Saídas: true = Continuar: dentro do limite; false = Máximo / Em loop: estourou o limite (ou a IA viu a conversa travada).

Sempre ligue a saída false a um desfecho (transferir, encerrar, avisar a equipe).

Checar Respostas — `logic_check_variables`

Confere se as variáveis obrigatórias já foram preenchidas; a lista do que falta vai para {{flow._missing_vars}}.

Campo	Tipo	Obrigatório	Detalhes
`variables`	texto (linhas)	sim	Nomes das variáveis, um por linha (sem `{{flow. }}`).
`emptyValues`	texto (linhas)	—	Um por linha. Vazio = padrão ("não informado", "não respondido", "-", "n/a").
`acceptUnanswered`	true/false	—	Liga: basta a variável existir, mesmo com valor de vazio. Padrão: `false`.

Saídas: true = Completo: todas preenchidas; false = Faltando: falta alguma ({{flow._missing_vars}} diz qual).

Integrações

Transferir Humano — `integration_transfer_human`

Passa a conversa para uma pessoa ou para a fila de um time e desliga a IA na conversa.

Campo	Tipo	Obrigatório	Detalhes
`assignTo`	id	—	Id do usuário. Vazio = fila geral (ou fila do time, com `teamId`). Id de usuário da conta.
`teamId`	id	—	Id do time: a conversa vai para a fila do time (sigilo conforme o time). Id de time da conta.
`restricted`	true/false	—	Com `teamId`: força a conversa sigilosa (true) ou não (false). Ausente = padrão do time.

Saída: uma só — aresta sem sourceHandle.

Precisa de conversa: é pulado quando o gatilho de webhook roda em modo "Sem canal".

Encerrar Conversa — `integration_close_conversation`

Encerra a conversa, registrando um motivo.

Campo	Tipo	Obrigatório	Detalhes
`reason`	texto	—	Motivo registrado. Vazio = "Fluxo automatico concluido". Aceita variáveis.

Saída: uma só — aresta sem sourceHandle.

Precisa de conversa: é pulado quando o gatilho de webhook roda em modo "Sem canal".

Tag no Contato — `integration_tag_contact`

Adiciona ou remove tags do contato.

Campo	Tipo	Obrigatório	Detalhes
`tagAction`	opção	—	Adicionar ou remover. Valores: `add` (Adicionar), `remove` (Remover). Padrão: `"add"`.
`tags`	texto	sim	Nomes separados por vírgula (ex.: `lead, orcamento`). Use tags já cadastradas em Configurações › Tags.

Saída: uma só — aresta sem sourceHandle.

Atualizar Contato — `integration_update_contact`

Grava um valor num campo do cadastro do contato.

Campo	Tipo	Obrigatório	Detalhes
`contactField`	opção	—	Campo do cadastro. Valores: `notes` (Observações), `city` (Cidade), `state` (Estado), `custom` (Campo Personalizado). Padrão: `"notes"`.
`contactValue`	texto	sim	Valor gravado (ex.: `{{flow.cidade}}`). Aceita variáveis.
`customFieldName`	texto	—	Com `contactField: "custom"`: nome do campo. Ausente = `custom`. O editor não mostra este campo.

Saída: uma só — aresta sem sourceHandle.

Notificar Equipe — `integration_notify_team`

Envia um aviso interno para a equipe no sino do Columba.

Campo	Tipo	Obrigatório	Detalhes
`notificationMessage`	texto (linhas)	sim	Texto do aviso. Vazio = "Atenção necessária no fluxo". Aceita variáveis.
`priority`	opção	—	Prioridade do aviso. Valores: `low` (Baixa), `medium` (Média), `high` (Alta). Padrão: `"medium"`.

Saída: uma só — aresta sem sourceHandle.

Avisar no WhatsApp — `integration_notify_whatsapp`

Envia um WhatsApp para um número da equipe (fora da conversa com o contato).

Campo	Tipo	Obrigatório	Detalhes
`to`	texto	sim	Telefone com DDD (ex.: `11999998888` ou `5511999998888`). Aceita variáveis.
`message`	texto (linhas)	sim	Texto do aviso (ex.: resumo do lead com `{{contact.name}}` e `{{flow.*}}`). Aceita variáveis.

Saída: uma só — aresta sem sourceHandle.

Se o envio falhar (número inválido, limite do plano), a equipe recebe um aviso no sino.

Funil de vendas

Criar Negócio — `integration_create_deal`

Abre um negócio no funil para o contato (reaproveita o aberto, se já houver).

Campo	Tipo	Obrigatório	Detalhes
`dealTitle`	texto	—	Vazio = nome do contato e etapa. Aceita variáveis.
`dealValue`	texto	—	Valor em reais (ex.: `1.500,00` ou `{{flow.valor}}`). Aceita variáveis.
`pipelineId`	id	—	Id do funil. Vazio = funil padrão. Id de funil da conta.
`stageId`	id	—	Id de uma etapa aberta. Vazio = primeira etapa do funil. Id de etapa do funil da conta.
`ownerId`	id	—	Id do usuário responsável. Id de usuário da conta. O editor não mostra este campo.
`teamId`	id	—	Id do time do negócio. Id de time da conta. O editor não mostra este campo.
`sourceKind`	texto	—	Origem registrada. Vazio = canal da conversa. O editor não mostra este campo.

Saída: uma só — aresta sem sourceHandle.

Atualizar Negócio — `integration_update_deal`

Grava valor, previsão de fechamento e campos de qualificação no negócio aberto do contato.

Campo	Tipo	Obrigatório	Detalhes
`dealValue`	texto	—	Valor em reais. Aceita variáveis.
`expectedCloseDate`	texto	—	Data AAAA-MM-DD (ou variável que contenha a data). Aceita variáveis.
`qualification`	lista de pares	—	Pares `{ "key": "orcamento", "value": "{{flow.orcamento}}" }`.

Saída: uma só — aresta sem sourceHandle.

Sem negócio aberto para o contato, o nó é pulado — crie antes com Criar Negócio.

Mover de Etapa — `integration_move_stage`

Move o negócio aberto do contato para a etapa escolhida.

Campo	Tipo	Obrigatório	Detalhes
`stageId`	id	sim	Id da etapa de destino. Id de etapa do funil da conta.
`pipelineId`	id	—	Id do funil da etapa. Id de funil da conta.
`lossReasonId`	id	—	Obrigatório quando a etapa de destino é de perda. Id de motivo de perda da conta.
`lossNotes`	texto	—	Texto livre. Aceita variáveis. O editor não mostra este campo.

Saída: uma só — aresta sem sourceHandle.

Distribuir Negócio — `integration_assign_owner`

Define o responsável pelo negócio: uma pessoa ou o rodízio de um time.

Campo	Tipo	Obrigatório	Detalhes
`ownerId`	id	—	Id do usuário. Vazio = rodízio do time. Id de usuário da conta.
`teamId`	id	—	Id do time cujo rodízio escolhe o responsável. Id de time da conta.

Saída: uma só — aresta sem sourceHandle.

Preencha ownerId ou teamId.

Agendar Retorno — `integration_create_task`

Agenda um retorno para o responsável pelo negócio (aparece em "Meu dia").

Campo	Tipo	Obrigatório	Detalhes
`taskType`	opção	—	Tipo do retorno. Valores: `whatsapp` (WhatsApp), `ligacao` (Ligação), `reuniao` (Reunião), `visita` (Visita), `proposta` (Proposta), `outro` (Outro). Padrão: `"whatsapp"`.
`dueInHours`	número	—	Vence daqui a N horas. Mínimo 1. Padrão: `24`.
`taskTitle`	texto	—	Título do retorno. Aceita variáveis.
`taskNotes`	texto (linhas)	—	Texto livre. Aceita variáveis. O editor não mostra este campo.
`ownerId`	id	—	Id do usuário. Vazio = dono do negócio. Id de usuário da conta.

Saída: uma só — aresta sem sourceHandle.

Anotações

Sticky Note — `note_sticky`

Anotação visual para documentar o fluxo; não executa nada e não se conecta a outros nós.

Campo	Tipo	Obrigatório	Detalhes
`text`	texto (linhas)	—	Conteúdo da nota.

Saídas: nenhuma.

Exemplo completo

Menu de 3 opções: orçamento abre um negócio no funil e a IA conduz a conversa; dúvidas vão direto para a IA; errar o menu duas vezes, sumir ou travar a conversa leva para a equipe. Importe o arquivo e publique depois de revisar.

json

{
  "format": "columba-flow",
  "formatVersion": 1,
  "flow": {
    "name": "Atendimento com menu e IA",
    "description": "Menu de 3 opções; orçamento abre negócio no funil e a IA conduz a conversa.",
    "triggerType": "trigger_new_conversation",
    "triggerConfig": {
      "label": "Nova conversa",
      "allowedChannels": [
        "whatsapp"
      ]
    },
    "priority": 50,
    "nodes": [
      {
        "id": "gatilho",
        "type": "trigger_new_conversation",
        "position": {
          "x": 0,
          "y": 240
        },
        "data": {
          "label": "Nova conversa",
          "allowedChannels": [
            "whatsapp"
          ]
        }
      },
      {
        "id": "boas_vindas",
        "type": "action_send_text",
        "position": {
          "x": 320,
          "y": 240
        },
        "data": {
          "label": "Boas-vindas e menu",
          "message": "Olá, {{contact.name}}! Aqui é a [Empresa]. Como posso ajudar?\n\n1 - Pedir um orçamento\n2 - Tirar uma dúvida\n3 - Falar com a equipe\n\nResponda com o número da opção."
        }
      },
      {
        "id": "espera_menu",
        "type": "logic_wait_for_reply",
        "position": {
          "x": 640,
          "y": 240
        },
        "data": {
          "label": "Espera a opção",
          "timeoutMinutes": 60
        }
      },
      {
        "id": "menu",
        "type": "logic_switch",
        "position": {
          "x": 960,
          "y": 240
        },
        "data": {
          "label": "Opção escolhida",
          "switchOptions": "1\n2\n3"
        }
      },
      {
        "id": "criar_negocio",
        "type": "integration_create_deal",
        "position": {
          "x": 1280,
          "y": 0
        },
        "data": {
          "label": "Abre o orçamento no funil",
          "dealTitle": "Orçamento — {{contact.name}}"
        }
      },
      {
        "id": "ia",
        "type": "action_ai_response",
        "position": {
          "x": 1600,
          "y": 120
        },
        "data": {
          "label": "IA atende",
          "systemPrompt": "# Papel\nVocê é a assistente virtual da [Empresa], que [o que a empresa faz, em uma frase].\n\n# Tom de voz\n- Próximo e objetivo, tratando o cliente por \"você\". Frases curtas.\n\n# O que fazer\n- Entender o que o cliente precisa e responder com base na Base do Assistente.\n- Em pedidos de orçamento, colete: o que precisa, prazo e cidade. Salve cada resposta com save_information e registre valor e prazo no negócio com update_deal.\n\n# Regras\n- Nunca invente preços, prazos ou condições; se não souber, diga que vai confirmar com a equipe.\n\n# Quando transferir para um humano\n- O cliente pedir para falar com uma pessoa, reclamar ou quiser negociar valores.\n- Depois de coletar os dados do orçamento.",
          "model": "claude-haiku-4-5",
          "temperature": 0.5,
          "ragEnabled": true,
          "toolsEnabled": true,
          "enabledTools": [
            "save_information",
            "update_deal",
            "transfer_to_human",
            "close_conversation"
          ]
        }
      },
      {
        "id": "espera_ia",
        "type": "logic_wait_for_reply",
        "position": {
          "x": 1920,
          "y": 120
        },
        "data": {
          "label": "Espera o cliente",
          "timeoutMinutes": 30,
          "maxConversationMinutes": 240
        }
      },
      {
        "id": "limite_ia",
        "type": "logic_loop_guard",
        "position": {
          "x": 2240,
          "y": 0
        },
        "data": {
          "label": "Conversa andando?",
          "mode": "ai_judge",
          "judgeEvery": 5,
          "hardLimit": 30
        }
      },
      {
        "id": "limite_menu",
        "type": "logic_loop_guard",
        "position": {
          "x": 1280,
          "y": 480
        },
        "data": {
          "label": "Errou o menu",
          "mode": "counter",
          "maxIterations": 2
        }
      },
      {
        "id": "nao_entendi",
        "type": "action_send_text",
        "position": {
          "x": 1600,
          "y": 600
        },
        "data": {
          "label": "Pede a opção de novo",
          "message": "Não entendi. Responda só com 1, 2 ou 3."
        }
      },
      {
        "id": "transferir",
        "type": "integration_transfer_human",
        "position": {
          "x": 2560,
          "y": 360
        },
        "data": {
          "label": "Passa para a equipe"
        }
      },
      {
        "id": "avisar_equipe",
        "type": "integration_notify_team",
        "position": {
          "x": 2240,
          "y": 240
        },
        "data": {
          "label": "Avisa que o cliente sumiu",
          "notificationMessage": "{{contact.name}} parou de responder no atendimento automático.",
          "priority": "medium"
        }
      },
      {
        "id": "encerrar",
        "type": "integration_close_conversation",
        "position": {
          "x": 2560,
          "y": 120
        },
        "data": {
          "label": "Encerra",
          "reason": "Sem resposta do contato"
        }
      },
      {
        "id": "nota",
        "type": "note_sticky",
        "position": {
          "x": 0,
          "y": 480
        },
        "data": {
          "label": "Como funciona",
          "text": "Menu 1-2-3. Orçamento abre negócio e a IA coleta os dados. Errou o menu 2 vezes, some ou a conversa travou: vai para a equipe."
        }
      }
    ],
    "edges": [
      {
        "id": "e1",
        "source": "gatilho",
        "target": "boas_vindas"
      },
      {
        "id": "e2",
        "source": "boas_vindas",
        "target": "espera_menu"
      },
      {
        "id": "e3",
        "source": "espera_menu",
        "target": "menu",
        "sourceHandle": "true",
        "label": "Resposta"
      },
      {
        "id": "e4",
        "source": "espera_menu",
        "target": "encerrar",
        "sourceHandle": "false",
        "label": "Timeout"
      },
      {
        "id": "e5",
        "source": "menu",
        "target": "criar_negocio",
        "sourceHandle": "1",
        "label": "1"
      },
      {
        "id": "e6",
        "source": "menu",
        "target": "ia",
        "sourceHandle": "2",
        "label": "2"
      },
      {
        "id": "e7",
        "source": "menu",
        "target": "transferir",
        "sourceHandle": "3",
        "label": "3"
      },
      {
        "id": "e8",
        "source": "menu",
        "target": "limite_menu",
        "sourceHandle": "default",
        "label": "Padrão"
      },
      {
        "id": "e9",
        "source": "limite_menu",
        "target": "nao_entendi",
        "sourceHandle": "true",
        "label": "Continuar"
      },
      {
        "id": "e10",
        "source": "limite_menu",
        "target": "transferir",
        "sourceHandle": "false",
        "label": "Máximo"
      },
      {
        "id": "e11",
        "source": "nao_entendi",
        "target": "espera_menu"
      },
      {
        "id": "e12",
        "source": "criar_negocio",
        "target": "ia"
      },
      {
        "id": "e13",
        "source": "ia",
        "target": "espera_ia"
      },
      {
        "id": "e14",
        "source": "espera_ia",
        "target": "limite_ia",
        "sourceHandle": "true",
        "label": "Resposta"
      },
      {
        "id": "e15",
        "source": "espera_ia",
        "target": "avisar_equipe",
        "sourceHandle": "false",
        "label": "Timeout"
      },
      {
        "id": "e16",
        "source": "limite_ia",
        "target": "ia",
        "sourceHandle": "true",
        "label": "Continuar"
      },
      {
        "id": "e17",
        "source": "limite_ia",
        "target": "transferir",
        "sourceHandle": "false",
        "label": "Em loop"
      },
      {
        "id": "e18",
        "source": "avisar_equipe",
        "target": "encerrar"
      }
    ]
  }
}

Referência técnica (JSON) ​

Estrutura do arquivo ​

Nós ​

Arestas ​

Variáveis ​

O que a importação confere ​

Catálogo de nós ​

Gatilhos ​

Nova Conversa — trigger_new_conversation ​

Mensagem Recebida — trigger_message_received ​

Conversa Reaberta — trigger_conversation_reopened ​

Palavra-Chave — trigger_keyword ​

Resposta Campanha — trigger_campaign_reply ​

Negócio Mudou de Etapa — trigger_deal_stage_changed ​

Negócio Parado — trigger_deal_stale ​

Lead Sem Resposta — trigger_deal_no_reply ​

Webhook — trigger_webhook ​

Ações ​

Enviar Texto — action_send_text ​

Enviar Mídia — action_send_media ​

Botões/Lista — action_send_interactive ​

Resposta IA — action_ai_response ​

Aguardar — action_delay ​

Definir Variável — action_set_variable ​

Integração externa — action_http_request ​

Lógica ​

Condição — logic_condition ​

Escolha Múltipla — logic_switch ​

Aguardar Resposta — logic_wait_for_reply ​

Limite Repetição — logic_loop_guard ​

Checar Respostas — logic_check_variables ​

Integrações ​

Transferir Humano — integration_transfer_human ​

Encerrar Conversa — integration_close_conversation ​

Tag no Contato — integration_tag_contact ​

Atualizar Contato — integration_update_contact ​

Notificar Equipe — integration_notify_team ​

Avisar no WhatsApp — integration_notify_whatsapp ​

Funil de vendas ​

Criar Negócio — integration_create_deal ​

Atualizar Negócio — integration_update_deal ​

Mover de Etapa — integration_move_stage ​

Distribuir Negócio — integration_assign_owner ​

Agendar Retorno — integration_create_task ​

Anotações ​

Sticky Note — note_sticky ​

Exemplo completo ​

Referência técnica (JSON)

Estrutura do arquivo

Nós

Arestas

Variáveis

O que a importação confere

Catálogo de nós

Gatilhos

Nova Conversa — `trigger_new_conversation`

Mensagem Recebida — `trigger_message_received`

Conversa Reaberta — `trigger_conversation_reopened`

Palavra-Chave — `trigger_keyword`

Resposta Campanha — `trigger_campaign_reply`

Negócio Mudou de Etapa — `trigger_deal_stage_changed`

Negócio Parado — `trigger_deal_stale`

Lead Sem Resposta — `trigger_deal_no_reply`

Webhook — `trigger_webhook`

Ações

Enviar Texto — `action_send_text`

Enviar Mídia — `action_send_media`

Botões/Lista — `action_send_interactive`

Resposta IA — `action_ai_response`

Aguardar — `action_delay`

Definir Variável — `action_set_variable`

Integração externa — `action_http_request`

Lógica

Condição — `logic_condition`

Escolha Múltipla — `logic_switch`

Aguardar Resposta — `logic_wait_for_reply`

Limite Repetição — `logic_loop_guard`

Checar Respostas — `logic_check_variables`

Integrações

Transferir Humano — `integration_transfer_human`

Encerrar Conversa — `integration_close_conversation`

Tag no Contato — `integration_tag_contact`

Atualizar Contato — `integration_update_contact`

Notificar Equipe — `integration_notify_team`

Avisar no WhatsApp — `integration_notify_whatsapp`

Funil de vendas

Criar Negócio — `integration_create_deal`

Atualizar Negócio — `integration_update_deal`

Mover de Etapa — `integration_move_stage`

Distribuir Negócio — `integration_assign_owner`

Agendar Retorno — `integration_create_task`

Anotações

Sticky Note — `note_sticky`

Exemplo completo