Tutorial: Integração com WhatsApp

Neste tutorial, você vai criar um chatbot automatizado no WhatsApp que processa mensagens, responde automaticamente e gerencia pedidos.

O Que Você Vai Construir

Um sistema completo de atendimento via WhatsApp que: 1. Recebe mensagens do WhatsApp Business API 2. Identifica a intenção do cliente 3. Responde automaticamente com informações 4. Processa pedidos 5. Salva interações no banco de dados 6. Notifica a equipe sobre pedidos

Tempo estimado: 30 minutos

Pré-requisitos

• ✅ Conta no Lumina Flow Builder
• ✅ WhatsApp Business API configurada (ou conta de teste)
• ✅ Tutorial básico completo (Primeiro Flow)
• ✅ Conhecimento básico de webhooks

Arquitetura do Sistema

WhatsApp → Webhook → Validar Mensagem → Identificar Intenção
                                              ↓
                          Responder Menu ← Switch/Case → Processar Pedido
                                              ↓              ↓
                                          FAQ             Salvar DB
                                                             ↓
                                                      Notificar Equipe

Passo 1: Configurar WhatsApp Business API

1.1. Obter Credenciais

1. Acesse Facebook Developers
2. Crie uma aplicação Business
3. Adicione o produto WhatsApp
4. Anote as credenciais:
5. Phone Number ID: 123456789
6. Access Token: EAAx...
7. Webhook Verify Token: Crie um token único

1.2. Configurar Webhook

O WhatsApp vai enviar mensagens para seu webhook.

URL do Webhook:

https://api.lumina.app.br/v1/webhooks/wh_[SEU_ID]

Verify Token: Use o token que você criou

Passo 2: Criar o Flow

2.1. Criar Novo Flow

1. Dashboard → "+ Novo Flow"
2. Nome: "Chatbot WhatsApp"
3. Descrição: "Atendimento automatizado via WhatsApp"
4. Tags: "whatsapp", "chatbot", "atendimento"

2.2. Adicionar Variáveis Globais

Clique em Configurações e adicione:

{
  "whatsappToken": "EAAx...",
  "whatsappPhoneId": "123456789",
  "apiBaseUrl": "https://graph.facebook.com/v18.0",
  "menuMessage": "Olá! 👋 Como posso ajudar?\n\n1️⃣ Ver produtos\n2️⃣ Fazer pedido\n3️⃣ Falar com atendente\n4️⃣ Horário de funcionamento",
  "businessHours": "Seg-Sex: 9h às 18h\nSáb: 9h às 13h"
}

Passo 3: Configurar Webhook Receiver

3.1. Adicionar Webhook Trigger

1. Arraste "Webhook" para o canvas
2. Configure:
3. Nome: "Receber Mensagem WhatsApp"
4. Método: POST
5. Verificação: Habilitada

3.2. Validar Webhook do WhatsApp

O WhatsApp envia uma verificação inicial. Adicione um nó "If/Else":

// Condição: É verificação do webhook?
{{ $trigger.query['hub.mode'] === 'subscribe' && $trigger.query['hub.verify_token'] === 'seu_verify_token' }}

Se verdadeiro, retorne o challenge:

{{ $trigger.query['hub.challenge'] }}

Passo 4: Processar Mensagens

4.1. Extrair Dados da Mensagem

Adicione nó "Transform" chamado "Extrair Dados":

{{
  (() => {
    const entry = $trigger.body.entry?.[0];
    const change = entry?.changes?.[0];
    const message = change?.value?.messages?.[0];
    const contact = change?.value?.contacts?.[0];

    if (!message) {
      return { hasMessage: false };
    }

    return {
      hasMessage: true,
      messageId: message.id,
      from: message.from,
      timestamp: message.timestamp,
      type: message.type,
      text: message.text?.body || '',
      name: contact?.profile?.name || 'Cliente',
      phoneNumberId: change?.value?.metadata?.phone_number_id
    };
  })()
}}

4.2. Verificar Se Há Mensagem

Adicione "If/Else" para verificar:

{{ $node.output.hasMessage === true }}

Passo 5: Identificar Intenção

5.1. Adicionar Switch Node

Adicione nó "Switch" chamado "Identificar Intenção":

// Expression
{{ $nodes['extrair-dados'].output.text.toLowerCase().trim() }}

5.2. Configurar Cases

Configure os seguintes cases:

Case 1: Menu

// Matches: "menu", "oi", "olá", "início"
{{ ['menu', 'oi', 'olá', 'ola', 'inicio', 'start'].includes($switch.value) }}

Case 2: Produtos

// Matches: "1", "produtos", "ver produtos"
{{ $switch.value === '1' || $switch.value.includes('produto') }}

Case 3: Fazer Pedido

// Matches: "2", "pedido", "comprar"
{{ $switch.value === '2' || $switch.value.includes('pedido') || $switch.value.includes('comprar') }}

Case 4: Atendente

// Matches: "3", "atendente", "humano"
{{ $switch.value === '3' || $switch.value.includes('atendente') || $switch.value.includes('humano') }}

Case 5: Horário

// Matches: "4", "horário", "horario"
{{ $switch.value === '4' || $switch.value.includes('horario') }}

Passo 6: Criar Respostas

6.1. Resposta: Menu Principal

Adicione nó "Transform" no Case "Menu":

{{
  {
    "messaging_product": "whatsapp",
    "to": $nodes['extrair-dados'].output.from,
    "type": "text",
    "text": {
      "body": $vars.menuMessage
    }
  }
}}

6.2. Resposta: Lista de Produtos

Adicione "HTTP Request" para buscar produtos:

// URL
{{ $vars.apiBaseUrl }}/products

// Method
GET

Depois, adicione "Transform" para formatar:

{{
  (() => {
    const products = $node.output.data;
    const list = products.map((p, i) =>
      `${i + 1}. ${p.name} - R$ ${p.price.toFixed(2)}`
    ).join('\n');

    return {
      "messaging_product": "whatsapp",
      "to": $nodes['extrair-dados'].output.from,
      "type": "text",
      "text": {
        "body": `📦 Nossos Produtos:\n\n${list}\n\nDigite o número do produto para fazer pedido.`
      }
    };
  })()
}}

6.3. Resposta: Processar Pedido

Adicione "Transform" para validar pedido:

{{
  (() => {
    const text = $nodes['extrair-dados'].output.text;
    const productNumber = parseInt(text);

    if (isNaN(productNumber)) {
      return {
        valid: false,
        message: "❌ Número inválido. Digite apenas o número do produto."
      };
    }

    return {
      valid: true,
      productNumber: productNumber
    };
  })()
}}

Se válido, busque o produto e salve no banco:

// Database Query Node
{
  "operation": "insert",
  "table": "orders",
  "data": {
    "customer_phone": "{{ $nodes['extrair-dados'].output.from }}",
    "customer_name": "{{ $nodes['extrair-dados'].output.name }}",
    "product_id": "{{ $node.output.productId }}",
    "status": "pending",
    "created_at": "{{ new Date().toISOString() }}"
  }
}

Responda ao cliente:

{{
  {
    "messaging_product": "whatsapp",
    "to": $nodes['extrair-dados'].output.from,
    "type": "text",
    "text": {
      "body": `✅ Pedido confirmado!\n\n📦 Produto: ${$node.output.productName}\n💰 Valor: R$ ${$node.output.price.toFixed(2)}\n\nEm breve entraremos em contato para finalizar.`
    }
  }
}}

6.4. Resposta: Falar com Atendente

{{
  {
    "messaging_product": "whatsapp",
    "to": $nodes['extrair-dados'].output.from,
    "type": "text",
    "text": {
      "body": "🙋 Você será transferido para um atendente.\n\nPor favor, aguarde alguns instantes..."
    }
  }
}}

Depois, notifique a equipe (via email, Slack, etc).

6.5. Resposta: Horário

{{
  {
    "messaging_product": "whatsapp",
    "to": $nodes['extrair-dados'].output.from,
    "type": "text",
    "text": {
      "body": `⏰ Horário de Funcionamento:\n\n${$vars.businessHours}`
    }
  }
}}

Passo 7: Enviar Respostas

7.1. Criar Função Auxiliar de Envio

Todas as respostas convergem para um nó "HTTP Request" chamado "Enviar Mensagem WhatsApp":

// Method
POST

// URL
{{ $vars.apiBaseUrl }}/{{ $vars.whatsappPhoneId }}/messages

// Headers
{
  "Authorization": "Bearer {{ $vars.whatsappToken }}",
  "Content-Type": "application/json"
}

// Body
{{ $node.output }}

Passo 8: Logging e Analytics

8.1. Salvar Interação

Adicione "Database Query" para registrar todas as mensagens:

{
  "operation": "insert",
  "table": "whatsapp_messages",
  "data": {
    "message_id": "{{ $nodes['extrair-dados'].output.messageId }}",
    "from": "{{ $nodes['extrair-dados'].output.from }}",
    "name": "{{ $nodes['extrair-dados'].output.name }}",
    "message": "{{ $nodes['extrair-dados'].output.text }}",
    "intention": "{{ $nodes['identificar-intencao'].output.case }}",
    "timestamp": "{{ $nodes['extrair-dados'].output.timestamp }}",
    "created_at": "{{ new Date().toISOString() }}"
  }
}

8.2. Adicionar Logs

Adicione nós de "Log" em pontos críticos:

// Log: Mensagem Recebida
{{
  {
    "event": "message_received",
    "from": $nodes['extrair-dados'].output.from,
    "text": $nodes['extrair-dados'].output.text
  }
}}

// Log: Resposta Enviada
{{
  {
    "event": "message_sent",
    "to": $nodes['extrair-dados'].output.from,
    "response": $node.output
  }
}}

Passo 9: Error Handling

9.1. Adicionar Try-Catch

Configure error handling nos nós críticos:

1. Clique em "HTTP Request" (enviar mensagem)
2. Aba "Advanced"
3. Configure:
4. On Error: Continue
5. Max Retries: 3
6. Retry Delay: 2000ms

9.2. Resposta de Erro

Adicione nó "Transform" no caminho de erro:

{{
  {
    "messaging_product": "whatsapp",
    "to": $nodes['extrair-dados'].output.from,
    "type": "text",
    "text": {
      "body": "❌ Desculpe, ocorreu um erro temporário. Por favor, tente novamente em alguns instantes."
    }
  }
}}

Passo 10: Testar o Chatbot

10.1. Teste Via WhatsApp

Envie mensagens para o número configurado:

Teste 1: Menu

Cliente: Oi
Bot: Olá! 👋 Como posso ajudar?
     1️⃣ Ver produtos
     2️⃣ Fazer pedido
     ...

Teste 2: Produtos

Cliente: 1
Bot: 📦 Nossos Produtos:
     1. Produto A - R$ 50.00
     2. Produto B - R$ 75.00
     ...

Teste 3: Pedido

Cliente: 2
Bot: ✅ Pedido confirmado!
     📦 Produto: Produto B
     💰 Valor: R$ 75.00
     ...

10.2. Testar Webhook Manualmente

Use cURL para simular mensagem do WhatsApp:

curl -X POST https://api.lumina.app.br/v1/webhooks/wh_[SEU_ID] \
  -H "Content-Type: application/json" \
  -d '{
    "entry": [{
      "changes": [{
        "value": {
          "messages": [{
            "id": "msg_123",
            "from": "5511999999999",
            "timestamp": "1640000000",
            "type": "text",
            "text": {
              "body": "menu"
            }
          }],
          "contacts": [{
            "profile": {
              "name": "João Teste"
            }
          }],
          "metadata": {
            "phone_number_id": "123456789"
          }
        }
      }]
    }]
  }'

Passo 11: Melhorias Avançadas

11.1. Adicionar Sessão de Conversa

Mantenha contexto da conversa:

// Salvar estado da sessão
{
  "operation": "upsert",
  "table": "whatsapp_sessions",
  "data": {
    "phone": "{{ $nodes['extrair-dados'].output.from }}",
    "state": "awaiting_product_number",
    "context": "{{ JSON.stringify({ lastIntent: 'products' }) }}",
    "updated_at": "{{ new Date().toISOString() }}"
  }
}

11.2. Integrar com ChatGPT

Para respostas mais inteligentes:

// HTTP Request to OpenAI
{
  "method": "POST",
  "url": "https://api.openai.com/v1/chat/completions",
  "headers": {
    "Authorization": "Bearer {{ $vars.openaiKey }}",
    "Content-Type": "application/json"
  },
  "body": {
    "model": "gpt-3.5-turbo",
    "messages": [
      {
        "role": "system",
        "content": "Você é um atendente virtual de uma loja online. Seja educado e prestativo."
      },
      {
        "role": "user",
        "content": "{{ $nodes['extrair-dados'].output.text }}"
      }
    ]
  }
}

11.3. Adicionar Botões Interativos

Use botões ao invés de texto:

{{
  {
    "messaging_product": "whatsapp",
    "to": $nodes['extrair-dados'].output.from,
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": {
        "text": "Como posso ajudar?"
      },
      "action": {
        "buttons": [
          {
            "type": "reply",
            "reply": {
              "id": "btn_products",
              "title": "Ver Produtos"
            }
          },
          {
            "type": "reply",
            "reply": {
              "id": "btn_order",
              "title": "Fazer Pedido"
            }
          },
          {
            "type": "reply",
            "reply": {
              "id": "btn_contact",
              "title": "Falar com Atendente"
            }
          }
        ]
      }
    }
  }
}}

11.4. Enviar Imagens de Produtos

{{
  {
    "messaging_product": "whatsapp",
    "to": $nodes['extrair-dados'].output.from,
    "type": "image",
    "image": {
      "link": "{{ $node.output.productImageUrl }}",
      "caption": "{{ $node.output.productName }} - R$ {{ $node.output.price.toFixed(2) }}"
    }
  }
}}

Estrutura Final do Flow

Webhook → Verificar Challenge → Retornar Challenge
   ↓
Extrair Dados → Tem Mensagem? → Não → End
   ↓                 ↓
   ↓               Sim
   ↓                 ↓
   └──> Switch (Identificar Intenção)
             ├─ Menu → Enviar Menu
             ├─ Produtos → Buscar Produtos → Formatar Lista → Enviar
             ├─ Pedido → Validar → Salvar DB → Notificar → Enviar Confirmação
             ├─ Atendente → Enviar Transferência → Notificar Equipe
             └─ Horário → Enviar Horário
                   ↓
            Salvar Log → End

Monitoramento

Dashboard de Métricas

Crie queries para monitorar:

-- Mensagens por dia
SELECT DATE(created_at) as date, COUNT(*) as total
FROM whatsapp_messages
GROUP BY DATE(created_at)
ORDER BY date DESC;

-- Intenções mais comuns
SELECT intention, COUNT(*) as count
FROM whatsapp_messages
GROUP BY intention
ORDER BY count DESC;

-- Taxa de conversão
SELECT
  (SELECT COUNT(*) FROM orders WHERE created_at > NOW() - INTERVAL '7 days') * 100.0 /
  (SELECT COUNT(*) FROM whatsapp_messages WHERE created_at > NOW() - INTERVAL '7 days')
  as conversion_rate;

Conceitos Aprendidos

Você aprendeu:

• ✅ Integrar WhatsApp Business API
• ✅ Processar webhooks do WhatsApp
• ✅ Identificar intenções com Switch
• ✅ Enviar mensagens formatadas
• ✅ Processar e salvar pedidos
• ✅ Implementar error handling robusto
• ✅ Adicionar logging e analytics
• ✅ Usar botões interativos
• ✅ Manter contexto de conversação

Próximos Passos

1. Processar Planilhas

2. Integre com Google Sheets

3. Adicionar Pagamento

4. Integre com Stripe/Mercado Pago

5. Dashboard de Atendimento

6. Crie painel para equipe

7. Notificações Push

8. Envie updates proativos

Recursos Úteis

• WhatsApp Business API Docs
• Variáveis
• Expressões
• API Reference

---

← Primeiro Flow | Processar Planilhas →