Pular para conteúdo

LOCATION - Capturar Localização

O que é este Node?

O LOCATION é o node responsável por capturar localização GPS (latitude/longitude) do usuário através de compartilhamento de localização em tempo real.

Por que este Node existe?

Capturar localização GPS permite funcionalidades baseadas em posição. O LOCATION existe para:

  1. Localização precisa: Captura latitude/longitude exatas do usuário
  2. Integração com mapas: Permite exibir localização no Google Maps, Waze, etc.
  3. Cálculo de distância: Possibilita calcular distância entre usuário e pontos de interesse
  4. Delivery/Serviços: Essencial para apps de entrega, táxi, serviços locais
  5. Geofencing: Validar se usuário está em área específica

Como funciona internamente?

Quando o LOCATION é executado, o sistema:

  1. Pausa o flow e exibe a mensagem
  2. Solicita permissão ao app (WhatsApp/Telegram) para acessar GPS
  3. Aguarda compartilhamento da localização pelo usuário
  4. Captura lat/lng: Recebe coordenadas GPS
  5. Salva na variável: Armazena objeto com latitude, longitude, endereço (se disponível)
  6. Continua o flow

Código interno (basic-flow-executor.service.ts:261-278): 

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

  return {
    success: true,
    action: 'location_requested',
    inputType: 'location',
    message: message || 'Please share your location:',
    variable: variable || 'user_location',
    validation: {
      required: true,
      type: 'location'
    },
    awaitingUserInput: true
  };
}

Quando você DEVE usar este Node?

Use LOCATION sempre que precisar da posição GPS do usuário:

Casos de uso:

  1. Delivery: "Compartilhe sua localização para entrega"
  2. Táxi/Transporte: "De onde você está partindo?"
  3. Serviços locais: "Envie sua localização para encontrarmos técnicos próximos"
  4. Check-in: "Compartilhe sua localização no evento"
  5. Emergência: "Envie sua localização para resgate"
  6. Lojas próximas: "Veja lojas perto de você"

Quando NÃO usar LOCATION:

  • Endereço texto: Se precisa apenas do endereço escrito, use INPUT
  • CEP: Use INPUT com pattern de validação
  • Cidade/Estado: Use INPUT ou botões de seleção

Parâmetros Detalhados

message (string, obrigatório)

O que é: A mensagem solicitando que o usuário compartilhe a localização.

Flow completo para testar:

{
  "name": "Teste LOCATION - Message",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "location_1",
      "type": "location",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Pedir Localização",
        "parameters": {
          "message": "Por favor, compartilhe sua localização atual para prosseguir"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "📍 Localização recebida: {{user_location}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "location_1" },
    { "source": "location_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

variable (string, opcional)

O que é: Nome da variável onde a localização será salva.

Padrão: "user_location"

Flow completo para testar:

{
  "name": "Teste LOCATION - Variable",
  "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": "Solicitar Origem",
        "parameters": {
          "message": "Vamos calcular a rota 🚗"
        }
      }
    },
    {
      "id": "location_1",
      "type": "location",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Localização Origem",
        "parameters": {
          "message": "Compartilhe o local de partida:",
          "variable": "origem"
        }
      }
    },
    {
      "id": "location_2",
      "type": "location",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Localização Destino",
        "parameters": {
          "message": "Agora compartilhe o destino:",
          "variable": "destino"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Mostrar Rota",
        "parameters": {
          "message": "🗺️ Rota calculada!\n\n📍 Origem: {{origem}}\n📍 Destino: {{destino}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "location_1" },
    { "source": "location_1", "target": "location_2" },
    { "source": "location_2", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Parâmetros

Campo Tipo Obrigatório Descrição
message string Sim Mensagem solicitando localização
variable string Não Nome da variável (padrão: "user_location")

Exemplo 1: Delivery Simples

Objetivo: Capturar localização para entrega

JSON para Importar

{
  "name": "Delivery - Capturar Localização",
  "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": "🍕 Pedido confirmado! Vamos preparar a entrega."
        }
      }
    },
    {
      "id": "location_1",
      "type": "location",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Pedir Localização",
        "parameters": {
          "message": "Compartilhe sua localização para calcularmos o frete:",
          "variable": "endereco_entrega"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Localização recebida!\n\n📍 Endereço: {{endereco_entrega}}\n\n⏱️ Tempo estimado: 30-40 minutos"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "location_1" },
    { "source": "location_1", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Exemplo 2: Cadastro com Localização

Objetivo: Coletar dados e localização do cliente

JSON para Importar

{
  "name": "Cadastro Completo com Localização",
  "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?",
          "variable": "nome"
        }
      }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Telefone",
        "parameters": {
          "message": "Qual é o seu telefone?",
          "variable": "telefone"
        }
      }
    },
    {
      "id": "location_1",
      "type": "location",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Localização",
        "parameters": {
          "message": "Compartilhe sua localização:",
          "variable": "localizacao"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Resumo",
        "parameters": {
          "message": "✅ CADASTRO COMPLETO\n\n👤 Nome: {{nome}}\n📱 Telefone: {{telefone}}\n📍 Local: {{localizacao}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "phone_1" },
    { "source": "phone_1", "target": "location_1" },
    { "source": "location_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Exemplo 3: Encontrar Loja Mais Próxima

Objetivo: Usar localização para indicar loja próxima

JSON para Importar

{
  "name": "Loja Mais Próxima",
  "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": "Apresentação",
        "parameters": {
          "message": "🏪 Vamos encontrar a loja mais próxima de você!"
        }
      }
    },
    {
      "id": "location_1",
      "type": "location",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Pedir Localização",
        "parameters": {
          "message": "Compartilhe sua localização:",
          "variable": "minha_localizacao"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Mostrar Loja",
        "parameters": {
          "message": "🎯 Loja mais próxima encontrada!\n\n📍 Shopping Center - 2.3km\nRua das Flores, 456\n\n🚗 Abrir no Google Maps: [Link]"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "location_1" },
    { "source": "location_1", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Resposta do Node

{
  "success": true,
  "action": "location_requested",
  "inputType": "location",
  "message": "Compartilhe sua localização:",
  "variable": "user_location",
  "validation": {
    "required": true,
    "type": "location"
  },
  "awaitingUserInput": true
}

Formato da Localização Capturada

Quando o usuário compartilha a localização, a variável contém:

{
  "latitude": -23.5505199,
  "longitude": -46.6333094,
  "address": "Av. Paulista, 1578 - Bela Vista, São Paulo - SP"
}

Campos: - latitude: Coordenada de latitude (número) - longitude: Coordenada de longitude (número) - address: Endereço aproximado (se disponível)

Como Usar a Localização

Exibir no Google Maps

https://www.google.com/maps?q={{user_location.latitude}},{{user_location.longitude}}

Calcular Distância

Use a fórmula de Haversine ou serviços como Google Distance Matrix API.

Validar Área

Verifique se latitude/longitude está dentro de range específico.

Validação Automática

O node LOCATION valida automaticamente:

✅ Formato: Verifica se são coordenadas GPS válidas ✅ Required: Localização obrigatória por padrão ✅ Tipo: Valida que é objeto com lat/lng

Se usuário enviar algo inválido, sistema pede novamente.

Dicas

💡 Explique o motivo: "Compartilhe sua localização para calcular frete" 💡 Privacidade: Deixe claro como a localização será usada 💡 Alternativa: Ofereça opção de digitar endereço se preferir 💡 Google Maps: Use coordenadas para gerar links de mapa

Próximo Node

→ MEDIA - Capturar imagem/vídeo/áudio → DATE - Capturar data