💬 Integração WhatsApp Business
Conecte seu número WhatsApp Business ao UpBeez e responda clientes automaticamente com IA.
Como funciona
O UpBeez recebe as mensagens dos seus clientes via webhook da Meta (WhatsApp Cloud API), processa com IA usando sua base de conhecimento, e envia a resposta automaticamente. Tudo aparece no dashboard em tempo real.
⚡ Conexão Rápida (Recomendado)
A forma mais rápida de conectar o WhatsApp é pelo Embedded Signup — sem copiar tokens ou configurar webhooks manualmente:
- No UpBeez, vá em 📱 Canais → WhatsApp
- Clique em "Conectar com Facebook"
- Faça login com sua conta Meta Business no popup
- Selecione ou crie uma conta WhatsApp Business
- Verifique seu número de telefone (OTP)
- Pronto! O UpBeez configura tudo automaticamente (token, webhook, etc.)
Se preferir configurar manualmente (avançado), siga o guia detalhado abaixo.
Pré-requisitos (Configuração Manual)
- Conta Meta Business — Crie em business.facebook.com
- Meta App — Crie em developers.facebook.com
- Número de telefone — Um número verificado no WhatsApp Business (pode usar o número de teste da Meta para começar)
- Conta no UpBeez — Crie aqui
Configuração Passo a Passo
Passo 1.Criar um Meta App
- Acesse developers.facebook.com/apps
- Clique em "Criar App"
- Escolha o tipo "Business" (ou "Outro" → Business)
- Dê um nome ao app (ex: "Meu Chatbot UpBeez")
- Selecione sua conta Business
- Após criar, vá em "Adicionar produto" e selecione "WhatsApp"
Passo 2.Obter Phone Number ID e Access Token
No painel do Meta App, vá em WhatsApp → API Setup:
- Você verá um Phone Number ID — é um número tipo
1234567890 - Clique em "Generate Temporary Access Token" para obter um token de teste (expira em 24h)
- Copie ambos os valores
Passo 3.Conectar no UpBeez
- No UpBeez, vá em 📱 Canais no menu
- Na aba WhatsApp, clique em "Conectar"
- Cole o Phone Number ID e o Access Token
- Opcionalmente, adicione o App Secret (em App Settings → Basic → App Secret) para verificação de segurança
- Clique em "Conectar"
O UpBeez vai validar suas credenciais com a API da Meta. Se tudo estiver correto, você receberá:
- Webhook URL — A URL que você vai configurar na Meta
- Verify Token — O token de verificação do webhook
Passo 4.Configurar o Webhook na Meta
De volta ao painel do Meta App:
- Vá em WhatsApp → Configuration
- Em "Webhook", clique em "Edit"
- Cole a Webhook URL fornecida pelo UpBeez:
https://api.upbeez.com/webhooks/whatsapp/SEU_TENANT_ID - Cole o Verify Token fornecido pelo UpBeez
- Clique em "Verify and Save"
- Em "Webhook Fields", marque "messages" e clique em "Subscribe"
Passo 5.Testar!
- Envie uma mensagem para o número WhatsApp Business configurado
- O UpBeez recebe, processa com IA e responde automaticamente
- A conversa aparece em tempo real no dashboard em 💬 Conversas
🔑 Token Permanente (Produção)
O token temporário expira em 24h. Para produção, você precisa de um token permanente:
- Criar System User:
- Acesse Business Settings → System Users
- Clique em "Add"
- Nome: "UpBeez Bot" (ou o que preferir)
- Role: Admin
- Vincular assets:
- Clique no System User criado
- Clique em "Add Assets"
- Selecione Apps → seu Meta App
- Marque "Full Control"
- Gerar token permanente:
- Clique em "Generate New Token"
- Selecione seu Meta App
- Marque as permissões:
whatsapp_business_messagingwhatsapp_business_management
- Clique em "Generate Token"
- Copie o token (ele só aparece uma vez!)
- Atualizar no UpBeez:
- Desconecte e reconecte o WhatsApp com o novo token permanente
⚙️ Configurações Avançadas
Após conectar, vá em Canais → WhatsApp → Configurações:
| Configuração | Descrição | Padrão |
|---|---|---|
| Auto-reply | Responder automaticamente com IA | Ativado |
| Mensagem de boas-vindas | Enviada quando um novo contato inicia conversa | — |
| Tamanho da resposta | Número máximo de parágrafos (1-5) | 3 |
| Mostrar fontes | Exibir de onde veio a informação | Desativado |
| App Secret | Verificação HMAC-SHA256 dos webhooks | — |
🧠 Smart Reply (Resposta Inteligente)
Clientes no WhatsApp costumam enviar várias mensagens seguidas antes de terminar o pensamento. O Smart Reply agrupa essas mensagens e responde tudo de uma vez:
[14:01] Oi
[14:01] Tudo bem?
[14:02] Qual o preço do plano básico?
[14:02] E tem desconto anual?
↓ (espera 3 segundos de silêncio)
[14:05] Bot responde TUDO de uma vez 🎯Configure em Agente → Resposta Inteligente:
- Janela de espera: Tempo após última mensagem antes de responder (padrão: 3s)
- Espera máxima: Tempo máximo total antes de forçar resposta (padrão: 15s)
- Máximo de mensagens: Responde imediato se atingir (padrão: 10)
🔒 Segurança do Webhook
Para proteger seu webhook contra requisições falsas, configure o App Secret:
- No Meta App, vá em Settings → Basic
- Copie o App Secret
- No UpBeez, adicione-o ao conectar o WhatsApp (ou depois nas configurações via API)
Com isso, o UpBeez verifica a assinatura X-Hub-Signature-256 de cada webhook, rejeitando requisições falsificadas.
🔧 Troubleshooting
Token expirado
Se o bot parar de responder, provavelmente o token temporário expirou (24h). Gere um token permanente conforme descrito acima.
Webhook não verificando
- Verifique se o Verify Token está correto (copie novamente do UpBeez)
- Confirme que a URL está exatamente como fornecida (com HTTPS)
- Teste acessando
GET /webhooks/whatsapp/SEU_TENANT_ID?hub.mode=subscribe&hub.challenge=test&hub.verify_token=SEU_TOKEN
Mensagens não chegando
- Verifique se subscreveu o campo "messages" no webhook
- Se usando número de teste, confirme que seu número está na lista de test numbers
- Confira no Meta App se há erros em WhatsApp → Insights
Erro "Credenciais inválidas"
O Phone Number ID ou Access Token estão incorretos. O Phone Number ID não é o número de telefone em si — é o ID numérico mostrado na página "API Setup" do Meta.
📡 Endpoints da API
Para automação via API:
Conectar WhatsApp
POST /tenants/me/whatsapp/connect
{
"phone_number_id": "1234567890",
"access_token": "EAAxxxxxxx...",
"app_secret": "abc123...", // opcional
"welcome_message": "Olá! 👋", // opcional
"auto_reply": true
}Ver status
GET /tenants/me/whatsapp/statusAtualizar config
PATCH /tenants/me/whatsapp/config
{
"auto_reply": true,
"welcome_message": "Olá!",
"show_sources": false,
"max_response_length": 3
}Desconectar
POST /tenants/me/whatsapp/disconnect