PHONE - Capturar Telefone

O que é este Node?

O PHONE é o node responsável por capturar números de telefone digitados pelo usuário com validação automática de formato, DDD, DDI e padrões internacionais.

Por que este Node existe?

Capturar telefones requer validação específica que texto livre não oferece. O PHONE existe para:

Validação automática: Garante que o número digitado está no formato correto (DDD + número)
Normalização: Aceita vários formatos (com parênteses, traços, espaços) e normaliza
Validação por país: Valida regras específicas de cada país (BR, US, PT, etc.)
Evitar erros: Impede que "123" ou "telefone" sejam aceitos
Integração facilitada: Formato padronizado para envio de SMS, WhatsApp, chamadas

Como funciona internamente?

Quando o PHONE é executado, o sistema:

Pausa o flow e exibe a pergunta
Aguarda entrada do usuário
Valida formato: Verifica se está no padrão do país (DDD, comprimento)
Normaliza: Remove caracteres especiais se format=digits_only
Se inválido: Pede novamente
Se válido: Salva na variável e continua

Código interno (basic-flow-executor.service.ts:212-231):

private async executePhone(parameters: any, context: any): Promise<any> {
  const { message, variable, format, country } = parameters;

  return {
    success: true,
    action: 'phone_input_requested',
    inputType: 'phone',
    message: message || 'Please enter your phone number:',
    variable: variable || 'user_phone',
    validation: {
      required: true,
      type: 'phone',
      format: format || 'international',
      country: country || 'BR'
    },
    awaitingUserInput: true
  };
}

Quando você DEVE usar este Node?

Use PHONE sempre que precisar de números de telefone válidos do usuário:

Casos de uso:

Cadastro: "Qual é o seu telefone?"
Confirmação SMS: "Telefone para envio do código"
Delivery: "Telefone para contato na entrega"
Agendamento: "Telefone para confirmação"
Suporte: "Telefone para ligação de retorno"
WhatsApp: "Telefone para contato via WhatsApp"

Quando NÃO usar PHONE:

Código numérico: Se é apenas código (ex: 123456), use NUMBER
Telefone internacional sem país: Use INPUT com pattern customizado

Parâmetros Detalhados

message (string, obrigatório)

O que é: A pergunta que será mostrada ao usuário.

Flow completo para testar:

{
  "name": "Teste PHONE - Message",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Pedir Telefone",
        "parameters": {
          "message": "Qual é o seu telefone com DDD?"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Telefone capturado: {{user_phone}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "phone_1" },
    { "source": "phone_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

variable (string, opcional)

O que é: Nome da variável onde o telefone será salvo.

Padrão: "user_phone"

Flow completo para testar:

{
  "name": "Teste PHONE - Variable",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Telefone Celular",
        "parameters": {
          "message": "Qual é o seu celular?",
          "variable": "celular"
        }
      }
    },
    {
      "id": "phone_2",
      "type": "phone",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Telefone Fixo",
        "parameters": {
          "message": "Qual é o seu telefone fixo?",
          "variable": "telefone_fixo"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Mostrar Telefones",
        "parameters": {
          "message": "📱 Celular: {{celular}}\n☎️ Fixo: {{telefone_fixo}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "phone_1" },
    { "source": "phone_1", "target": "phone_2" },
    { "source": "phone_2", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

format (string, opcional)

O que é: Define o formato esperado do telefone.

Padrão: "international"

Valores: - "international" → Aceita +55 11 98765-4321 - "national" → Aceita (11) 98765-4321 - "digits_only" → Aceita apenas 11987654321

Flow completo para testar format=digits_only:

{
  "name": "Teste PHONE - Format Digits Only",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Telefone Apenas Números",
        "parameters": {
          "message": "Digite seu telefone (apenas números, com DDD):",
          "variable": "telefone",
          "format": "digits_only"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Telefone: {{telefone}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "phone_1" },
    { "source": "phone_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite 11987654321 - aceita! Digite (11) 98765-4321 - normaliza!

country (string, opcional)

O que é: Código do país para validação específica.

Padrão: "BR" (Brasil)

Valores: BR, US, PT, AR, etc.

Flow completo para testar country=BR:

{
  "name": "Teste PHONE - Country BR",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Telefone Brasil",
        "parameters": {
          "message": "Qual é o seu telefone? (DDD + número)",
          "variable": "telefone_br",
          "country": "BR"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Telefone brasileiro: {{telefone_br}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "phone_1" },
    { "source": "phone_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite 11987654321 (válido), 123456 (inválido - muito curto)

Parâmetros

Campo	Tipo	Obrigatório	Descrição
message	string	Sim	Pergunta para o usuário
variable	string	Não	Nome da variável (padrão: "user_phone")
format	string	Não	Formato do telefone (padrão: "international")
country	string	Não	Código do país (padrão: "BR")

Exemplo 1: Cadastro de Telefone

Objetivo: Capturar telefone para contato

JSON para Importar

{
  "name": "Cadastro Telefone",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Pedir Telefone",
        "parameters": {
          "message": "Qual é o seu telefone? (com DDD)",
          "variable": "telefone",
          "country": "BR"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Telefone {{telefone}} cadastrado!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "phone_1" },
    { "source": "phone_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Qual é o seu telefone? (com DDD)
Usuário: 11987654321
Sistema: ✅ Telefone 11987654321 cadastrado!

Exemplo 2: Delivery com Telefone

Objetivo: Coletar endereço e telefone para entrega

JSON para Importar

{
  "name": "Pedido Delivery",
  "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": "Boas-vindas",
        "parameters": {
          "message": "🍕 Vamos fazer seu pedido!"
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Pedir Endereço",
        "parameters": {
          "message": "Qual é o endereço de entrega?",
          "variable": "endereco"
        }
      }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Pedir Telefone",
        "parameters": {
          "message": "Telefone para contato:",
          "variable": "telefone_contato",
          "country": "BR"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Confirmar Pedido",
        "parameters": {
          "message": "Perfeito!\n📍 Endereço: {{endereco}}\n📱 Telefone: {{telefone_contato}}\n\nPedido confirmado!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "input_1" },
    { "source": "input_1", "target": "phone_1" },
    { "source": "phone_1", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 🍕 Vamos fazer seu pedido!
Sistema: Qual é o endereço de entrega?
Usuário: Rua das Flores, 123
Sistema: Telefone para contato:
Usuário: 11999887766
Sistema: Perfeito!
         📍 Endereço: Rua das Flores, 123
         📱 Telefone: 11999887766

         Pedido confirmado!

Exemplo 3: Agendamento

Objetivo: Coletar telefone para confirmação de agendamento

JSON para Importar

{
  "name": "Agendamento com Telefone",
  "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": "Serviço",
        "parameters": {
          "message": "Você escolheu: Corte de Cabelo\n💰 Valor: R$ 50,00"
        }
      }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Pedir Telefone",
        "parameters": {
          "message": "Telefone para confirmarmos o agendamento:",
          "variable": "telefone_cliente",
          "country": "BR"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Agendamento confirmado!\nEntraremos em contato via {{telefone_cliente}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "phone_1" },
    { "source": "phone_1", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Você escolheu: Corte de Cabelo
         💰 Valor: R$ 50,00
Sistema: Telefone para confirmarmos o agendamento:
Usuário: 21987654321
Sistema: ✅ Agendamento confirmado!
         Entraremos em contato via 21987654321

Exemplo 4: Cadastro Completo

Objetivo: Flow completo com nome, email e telefone

JSON para Importar

{
  "name": "Cadastro Completo Cliente",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Nome",
        "parameters": {
          "message": "Qual é o seu nome completo?",
          "variable": "nome"
        }
      }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Qual é o seu email?",
          "variable": "email"
        }
      }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Telefone",
        "parameters": {
          "message": "Qual é o seu telefone?",
          "variable": "telefone",
          "country": "BR"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Resumo",
        "parameters": {
          "message": "✅ Cadastro concluído!\n\n👤 Nome: {{nome}}\n📧 Email: {{email}}\n📱 Telefone: {{telefone}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "email_1" },
    { "source": "email_1", "target": "phone_1" },
    { "source": "phone_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Resposta do Node

{
  "success": true,
  "action": "phone_input_requested",
  "inputType": "phone",
  "message": "Qual é o seu telefone? (com DDD)",
  "variable": "telefone",
  "validation": {
    "required": true,
    "type": "phone",
    "format": "international",
    "country": "BR"
  },
  "awaitingUserInput": true
}

Formatos Aceitos (Brasil)

Celular:
11987654321
(11) 98765-4321
+55 11 98765-4321

Fixo:
1133334444
(11) 3333-4444
+55 11 3333-4444

Parâmetros de Formato

Formato	Descrição	Exemplo
international	Formato internacional	+55 11 98765-4321
national	Formato nacional	(11) 98765-4321
digits_only	Apenas dígitos	11987654321

{
  "parameters": {
    "message": "Digite seu telefone:",
    "variable": "telefone",
    "format": "digits_only",  // Apenas números
    "country": "BR"           // Brasil
  }
}

Códigos de País

País	Código	DDI
Brasil	BR	+55
EUA	US	+1
Portugal	PT	+351
Argentina	AR	+54

Validação Automática

O node PHONE valida automaticamente:

✅ Formato: Verifica se está no formato correto ✅ Comprimento: Valida quantidade de dígitos ✅ DDD válido: Para Brasil, valida DDD

Se usuário digitar número inválido, sistema pede novamente.

Dicas

💡 Indique o formato: "Digite seu telefone com DDD" 💡 Aceite variações: Sistema normaliza diferentes formatos 💡 Country BR: Use para telefones brasileiros 💡 Confirme sempre: Mostre o telefone capturado

Próximo Node

→ DATE - Capturar data → EMAIL - Capturar email