---

---

📑 Sumário

• 🔗 Links úteis
• 🎥 Demo
• ⚡ Guia rápido
• 🔄 Fluxo visual resumido
• 🧱 Estrutura do projeto
• ✅ Pré-requisitos
• 🔐 Configuração do .env
• 🧪 Testes em camadas
• 🌐 Webhook Flask (WhatsApp Cloud API)
• 🧠 Anti-duplicados
• ✉️ E-mail com botão “Responder no WhatsApp”
• 🧯 Problemas comuns
• 🧩 Comandos úteis
• 🗺️ Roadmap
• 📜 Licença
• 👩‍💻 Autora & Contato

---

🔗 Links úteis

• 📊 Planilha demo (view-only): Google Sheets
• 📘 Docs de deploy: ./docs/DEPLOY.md
• ⚙️ Exemplo de configuração: ./.env.example

⚠️ Observação: Esta planilha contém apenas dados fictícios usados para teste e demonstração.
Nenhuma informação real de clientes ou contatos foi utilizada.

---

🎥 Demo

Clique para ver a demo

O que o GIF mostra: envio de um lead de teste via /webhook, inserção automática na aba leads, updated_at preenchido e diff_minutos = 0.
Extras visuais: duplicado de WAMID destacado em laranja e validação de data em updated_at.

---

⚡ Guia rápido

Ativar ambiente

• Windows (CMD): .venv\Scripts\activate
• Windows (PowerShell): & ".\.venv\Scripts\Activate.ps1"
• Linux/Mac: source .venv/bin/activate

Instalar dependências

pip install -r requirements.txt

Rodar scripts básicos

• Setup planilha: python scripts/setup_sheet.py
• Adicionar lead: python scripts/append_lead.py
• Adicionar + enviar e-mail: python scripts/append_and_notify.py

Rodar webhook

python scripts/webhook.py

• Healthcheck: http://localhost:5000/ → OK
• Endpoint: http://localhost:5000/webhook

Abrir túnel (ngrok)

ngrok http 5000 → use a URL pública no Meta Developers

---

🔄 Fluxo visual resumido

📱 WhatsApp → 🌐 Webhook Flask → 📊 Google Sheets → ✉️ E-mail → 📝 Logs + Anti-duplicados

---

🧱 Estrutura do projeto (esperada)

whatsapp-sheets-email-bot/
├─ .env
├─ .env.example
├─ creds/
│ └─ service-account.json
├─ data/
│ └─ state.db # criado automaticamente (anti-duplicados)
├─ logs/
│ └─ app.log # logs do webhook
├─ scripts/
│ ├─ setup_sheet.py
│ ├─ append_lead.py
│ ├─ send_email.py
│ ├─ append_and_notify.py
│ ├─ dedupe.py
│ └─ webhook.py
└─ .venv/ # ambiente virtual

---

✅ Pré-requisitos

• Python 3.10+
• Conta Google + Google Cloud com:
  • Google Sheets API e Google Drive API habilitadas
  • Service Account (arquivo JSON baixado)
• Conta WhatsApp Cloud API no Meta Developers
• Senha de app no Gmail (para SMTP) ou credenciais do Mailtrap

---

---

🔐 Configuração do .env

Arquivo: ./.env.example

# ==========================
# 🔧 App / Server
# ==========================
ENV=dev                 # dev | prod
HOST=127.0.0.1
PORT=5000
TZ=America/Sao_Paulo
LOG_LEVEL=INFO          # DEBUG | INFO | WARNING | ERROR

# ==========================
# 📄 Google Sheets
# ==========================
# ID da planilha (trecho entre /d/ e /edit na URL do Google Sheets)
SHEET_ID=SUA_SHEET_ID_AQUI
SHEET_TAB=leads

# Caminho para o JSON da Service Account (arquivo não deve ser commitado)
GOOGLE_SERVICE_ACCOUNT_JSON=./creds/service-account.json
# E-mail da service account com permissão de Editor na planilha
SHARE_WITH_EMAIL=seu_email_service_account@projeto.iam.gserviceaccount.com

# ==========================
# ✉️ SMTP / E-mail
# ==========================
EMAIL_ENABLED=0         # 0 = desativado | 1 = ativado
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_STARTTLS=1
SMTP_USER=seu_email@gmail.com
SMTP_PASS=sua_senha_de_app
EMAIL_FROM=seu_email@gmail.com
EMAIL_TO=destinatario@exemplo.com
EMAIL_SUBJECT=Novo lead do WhatsApp

# Alternativa Mailtrap (para testes seguros)
# EMAIL_ENABLED=1
# SMTP_HOST=smtp.mailtrap.io
# SMTP_PORT=587
# SMTP_STARTTLS=1
# SMTP_USER=SEU_USER_MAILTRAP
# SMTP_PASS=SEU_PASS_MAILTRAP
# EMAIL_FROM=bot@meubot.dev
# EMAIL_TO=you@example.com

# ==========================
# 🔗 Meta Webhook
# ==========================
VERIFY_TOKEN=sua_chave_de_verificacao
WHATSAPP_TOKEN=seu_token_da_meta

# ==========================
# 🧪 Testes locais
# ==========================
TEST_BASE_URL=http://127.0.0.1:5000
TEST_FROM=5511999999999
TEST_NAME=Usuario Teste
TEST_BODY="Ola, quero um orcamento"

---

🧪 Testes em camadas

1. Sheets — criar aba e cabeçalhos: python scripts/setup_sheet.py → Esperado: ✅ Planilha OK!
2. Sheets — inserir lead manual: python scripts/append_lead.py → Esperado: ✅ Lead adicionado
3. E-mail — inserir e enviar: python scripts/append_and_notify.py → Esperado: 📧 Email enviado!

---

🌐 Webhook Flask (WhatsApp Cloud API)

1. Subir o servidor local: python scripts/webhook.py
2. Abrir túnel HTTPS (ngrok): ngrok http 5000
3. Configurar no Meta (Developers):
   • Webhook URL: https://abc123.ngrok.io/webhook
   • Verify Token: mesmo do .env
   • Webhook Fields → messages
4. Testes:
   • GET com curl → deve responder com challenge
   • POST simulando payload → gera novo lead no Sheets + e-mail enviado
   • Logs no terminal e em logs/app.log

---

🧠 Anti-duplicados

• Implementado em scripts/dedupe.py via SQLite (data/state.db)
• Usa wamid do WhatsApp como chave
• TTL padrão 24h
• Mensagens repetidas ignoradas

---

✉️ E-mail com botão “Responder no WhatsApp”

• Inclui botão https://wa.me/55XXXXXXXXXXX
• Suporte a logo (EMAIL_LOGO_URL)

---

🧯 Problemas comuns

• 403 (Sheets API desabilitada) → habilite Sheets + Drive no Google Cloud
• SpreadsheetNotFound → compartilhe planilha com a service account
• SMTP falha → use senha de app do Gmail ou Mailtrap
• ngrok não acessa → suba o Flask antes

---

🧩 Comandos úteis

Ativar ambiente: .venv\Scripts\activate (Windows CMD) / & ".\.venv\Scripts\Activate.ps1" (PowerShell) / source .venv/bin/activate (Linux/Mac)
Scripts: python scripts/setup_sheet.py, python scripts/append_lead.py, python scripts/append_and_notify.py, python scripts/webhook.py
Ver logs: type .\logs\app.log (Windows) / cat ./logs/app.log (Linux/Mac)

---

🗺️ Roadmap

• Resposta ativa no WhatsApp
• Filtro anti-duplicados por telefone
• Deploy (Railway/Render/VPS)
• Painel HTML simples

Status atual: ✅ Sheets OK | ✅ E-mail OK | ✅ Webhook pronto | ✅ Anti-duplicados | ✅ Logs

---

📜 Licença

Este projeto está sob a licença MIT.

---

👩‍💻 Autora & Contato

Autora: NeusaM21
Contato: contact.neusam21@gmail.com

---