Pular para conteúdo

START - Iniciar Flow

O que é este Node?

O START é o ponto de entrada obrigatório de todo flow no Lumina Flow Builder. Ele marca onde a execução começa e inicializa o contexto necessário para que todos os outros nodes possam funcionar corretamente.

Por que este Node existe?

Todo sistema de automação precisa de um ponto de início bem definido. O START serve para:

  1. Estabelecer o contexto inicial: Quando um flow é executado, ele precisa de dados básicos como ID do flow, ID do usuário, ID da sessão e timestamp. O START cria essas informações automaticamente.

  2. Garantir consistência: Sem um ponto de início único e padronizado, cada flow poderia começar de forma diferente, causando bugs e comportamentos imprevisíveis.

  3. Permitir rastreamento: Com o START gerando IDs únicos, você pode rastrear cada execução do flow nos logs, facilitando debug e análise de problemas.

  4. Criar variáveis base: O START popula variáveis fundamentais ({{flowId}}, {{userId}}, {{sessionId}}, {{timestamp}}) que qualquer node posterior pode usar.

Como funciona internamente?

Quando o START é executado, o sistema:

  1. Gera um flowId único para esta execução específica
  2. Captura o userId de quem iniciou o flow
  3. Cria um sessionId para agrupar múltiplas interações da mesma sessão
  4. Registra o timestamp exato do início
  5. Se você passar uma mensagem inicial, ela é enviada ao usuário
  6. Retorna sucesso e passa o controle para o próximo node conectado

Código interno (básico-flow-executor.service.ts:55-83): 

private async executeStart(parameters: any, context: any): Promise<any> {
  const { message } = parameters;

  return {
    success: true,
    data: {
      action: 'flow_started',
      timestamp: new Date().toISOString(),
      flowId: context.flowId || 'unknown',
      userId: context.userId || 'anonymous',
      sessionId: context.sessionId || 'default',
      message: message,
      messageType: 'text'
    }
  };
}

Quando você DEVE usar este Node?

SEMPRE! Todo flow precisa ter EXATAMENTE UM node START. É uma regra obrigatória do sistema.

Casos de uso:

  1. Chatbots: Quando usuário envia "oi" ou "/start", o flow inicia
  2. Webhooks: Quando recebe POST de sistema externo (ex: novo pedido na loja)
  3. Agendamentos: Quando cron job dispara execução automática (ex: enviar relatório diário)
  4. Eventos: Quando algo acontece no sistema (ex: novo cadastro, pagamento aprovado)

Parâmetros Detalhados

message (string, opcional)

O que é: Uma mensagem de texto que será enviada ao usuário assim que o flow iniciar.

Por que usar: Útil para dar contexto ao usuário sobre o que está acontecendo. Por exemplo, se o flow foi acionado por um webhook, você pode avisar "Seu pedido foi recebido!" antes de processar.

Quando NÃO usar: Se o próximo node já vai enviar uma mensagem, não precisa duplicar aqui.

Flow completo para testar:

{
  "name": "Teste START com Message",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": {
        "label": "Início com Mensagem",
        "parameters": {
          "message": "Bem-vindo ao atendimento! Vou te ajudar agora."
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Segunda Mensagem",
        "parameters": {
          "message": "Como posso ajudar você hoje?"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Como testar: 1. Copie o JSON acima 2. Importe no Flow Builder 3. Execute 4. Observe que DUAS mensagens são enviadas: uma do START e outra do MESSAGE

Variáveis que o START cria

Após executar, o START disponibiliza estas variáveis para TODOS os nodes seguintes:

{{flowId}}

  • O que é: ID único desta execução específica do flow
  • Formato: String (ex: "flow_abc123xyz")
  • Uso: Rastrear esta execução nos logs, salvar no banco de dados para auditoria

Flow completo para testar flowId:

{
  "name": "Teste Variável flowId",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Mostrar Flow ID",
        "parameters": {
          "message": "🆔 Flow ID desta execução: {{flowId}}\n\nCada vez que você executar, terá um ID diferente!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Execute 2 vezes e veja IDs diferentes!

{{userId}}

  • O que é: ID do usuário que disparou o flow
  • Formato: String (ex: "user_456")
  • Uso: Personalizar mensagens, buscar dados do usuário no banco, registrar ações

{{sessionId}}

  • O que é: ID da sessão de conversa/interação
  • Formato: String (ex: "session_789")
  • Uso: Agrupar múltiplas execuções da mesma conversa, manter contexto entre flows

{{timestamp}}

  • O que é: Data e hora exata que o flow iniciou
  • Formato: ISO 8601 (ex: "2025-01-15T10:30:00.000Z")
  • Uso: Registros, logs, calcular tempo de execução, validar expiração

Flow completo para testar TODAS as variáveis do START:

{
  "name": "Teste TODAS Variáveis do START",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Mostrar Todas Variáveis",
        "parameters": {
          "message": "📊 DADOS DESTA EXECUÇÃO:\n\n🆔 Flow ID: {{flowId}}\n👤 User ID: {{userId}}\n💬 Session ID: {{sessionId}}\n⏰ Timestamp: {{timestamp}}\n\nTodas essas variáveis vêm automaticamente do START!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Como testar: 1. Copie o JSON acima 2. Importe no Flow Builder 3. Execute 4. Veja todos os dados gerados automaticamente pelo START

Resposta Técnica do Node

Quando o START executa, ele retorna este JSON:

{
  "success": true,
  "data": {
    "action": "flow_started",
    "timestamp": "2025-01-15T10:30:00.000Z",
    "flowId": "flow_abc123",
    "userId": "user_456",
    "sessionId": "session_789",
    "message": "Mensagem inicial se fornecida",
    "messageType": "text"
  }
}

Campos explicados: - success: true → Sempre true, START nunca falha - action: "flow_started" → Identifica que foi uma ação de início - timestamp → Momento exato da execução - flowId, userId, sessionId → IDs gerados/capturados - message → Só aparece se você passou mensagem nos parâmetros - messageType: "text" → Tipo da mensagem (sempre texto no START)

Exemplo Real: Flow Completo Explicado

Vou mostrar um flow simples e explicar CADA parte:

{
  "name": "Atendimento Básico",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": {
        "label": "Início do Atendimento",
        "parameters": {
          "message": "Olá! Atendimento iniciado."
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Mensagem de Boas-Vindas",
        "parameters": {
          "message": "Como posso ajudar você hoje?"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Fim do Atendimento"
      }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Explicação linha por linha:

  1. "name": "Atendimento Básico" → Nome do flow no sistema
  2. nodes → Array com todos os nodes (blocos) do flow
  3. "id": "start_1" → ID único deste node no flow (pode ser qualquer string)
  4. "type": "start" → Tipo do node (obrigatório ser "start")
  5. position: { x, y } → Posição visual no editor de flows
  6. "label": "Início do Atendimento" → Nome que aparece no editor
  7. parameters.message → A mensagem inicial que será enviada
  8. edges → Conexões entre nodes (de START → MESSAGE → END)

Fluxo de execução: 1. Sistema executa START → Envia "Olá! Atendimento iniciado." 2. Sistema executa MESSAGE → Envia "Como posso ajudar você hoje?" 3. Sistema executa END → Finaliza flow

Exemplo com Uso de Variáveis

{
  "name": "Flow com Rastreamento",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": {
        "label": "Início",
        "parameters": {
          "message": "Atendimento iniciado!"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Info Técnica",
        "parameters": {
          "message": "Flow ID: {{flowId}}\nIniciado em: {{timestamp}}\nSessão: {{sessionId}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

O que acontece: 1. START executa e cria: flowId="flow_xyz", timestamp="2025-01-15T10:30:00Z", sessionId="sess_123" 2. MESSAGE substitui as variáveis e envia: 

Flow ID: flow_xyz
Iniciado em: 2025-01-15T10:30:00Z
Sessão: sess_123

Erros Comuns e Como Evitar

❌ ERRO: Flow sem START

{
  "nodes": [
    { "id": "message_1", "type": "message" }
  ]
}
Problema: Flow não tem ponto de entrada Solução: Sempre adicione um START no início

❌ ERRO: Múltiplos STARTs

{
  "nodes": [
    { "id": "start_1", "type": "start" },
    { "id": "start_2", "type": "start" }
  ]
}
Problema: Flow só pode ter UM START Solução: Remova os STARTs extras

❌ ERRO: START conectado a nada

{
  "nodes": [
    { "id": "start_1", "type": "start" }
  ],
  "edges": []
}
Problema: START precisa conectar ao próximo node Solução: Adicione edge para o próximo node

Boas Práticas

✅ Use mensagem inicial apenas quando fizer sentido: Não duplique se o próximo node já envia mensagem

✅ Dê nomes descritivos ao label: "Início do Cadastro" é melhor que "Start 1"

✅ Use as variáveis do START para rastreamento: Salve flowId e timestamp no banco de dados para auditoria

✅ Conecte sempre a um próximo node: START nunca deve ser o único node do flow

Diferença entre START e outros nodes

Característica START MESSAGE INPUT
Obrigatório ✅ Sim ❌ Não ❌ Não
Quantidade 1 por flow Múltiplos Múltiplos
Cria variáveis ✅ Sim ❌ Não ✅ Sim (a que captura)
Aguarda usuário ❌ Não ❌ Não ✅ Sim

Integração com Sistema

O START é acionado quando:

  1. API REST recebe POST /flows/:flowId/execute
  2. Webhook externo dispara execução
  3. Usuário envia comando no WhatsApp/Telegram
  4. Cron job agenda execução automática
  5. Evento interno do sistema ocorre

Próximos Passos

Agora que você entende o START, aprenda sobre:

→ MESSAGE - Como enviar mensagens ao usuário → INPUT - Como capturar respostas do usuário → END - Como finalizar o flow corretamente