# Chatbot v4 - Features Completas
## Visão Geral
O v4 inclui todas as funcionalidades:
- Memória de contexto (Redis)
- Filtro de grupos (@menção)
- Agendamento de mensagens
- Envio em massa
- Relatórios e estatísticas
- Integrações (Google Sheets, Calendar)
---
## 1. Agendamento de Mensagens (Completo)
### Comandos de Criação
```
"mande oi pro João amanhã às 9h"
"agende mensagem para 5511999999999 dia 25/12 às 08:00"
"envie feliz natal para todos os contatos dia 25/12"
```
### Comandos de Gerenciamento
```
"listar agendamentos" → Ver todas as pendências
"ver pendências" → Mesmo que listar
"cancelar agendamento #1" → Remove da lista
"remover agendamento do João" → Remove por nome/destino
"enviar agora #1" → Prioridade - envia imediatamente
"manda agora o do João" → Envia imediato por referência
"pausar agendamento #1" → Pausa sem remover
"retomar agendamento #1" → Retoma pausado
"editar #1 para amanhã 10h" → Altera horário
```
### Status dos Agendamentos
| Status | Descrição |
|--------|-----------|
| `pendente` | Aguardando horário |
| `pausado` | Pausado manualmente |
| `enviando` | Sendo processado |
| `enviado` | Concluído |
| `erro` | Falhou ao enviar |
### Formato de data aceito
- "amanhã às 9h"
- "dia 25/12 às 08:00"
- "2024-12-25 09:00"
- "daqui 2 horas"
### Como funciona
1. Mensagem agendada é salva no Redis (`uazapi:schedule`)
2. Workflow **Scheduler** roda a cada minuto
3. Verifica se há mensagens prontas para enviar
4. Envia e remove da lista
### Workflows necessários
- `workflow-chatbot-v4-full.json` (principal)
- `workflow-scheduler.json` (cron - ativar separadamente!)
---
## 2. Mensagens em Massa (COM PROTEÇÃO ANTI-BAN)
### Guardrails de Segurança
⚠️ **PROTEÇÕES AUTOMÁTICAS:**
| Proteção | Descrição |
|----------|-----------|
| **Confirmação obrigatória** | NUNCA envia sem você confirmar |
| **Preview antes** | Mostra lista de destinatários |
| **Máximo 20 por lote** | Divide automaticamente |
| **Delay 3-5 segundos** | Entre cada mensagem |
| **Pausa 30 segundos** | A cada 10 mensagens |
| **Horário randômico** | Evita padrão de bot |
### Fluxo de Envio em Massa
```
1. Você: "mande promoção pra todos os contatos"
2. Bot: ⚠️ CONFIRMAÇÃO NECESSÁRIA
Mensagem: "Promoção especial..."
Destinatários (15 pessoas):
• João (+5511...)
• Maria (+5511...)
• Pedro (+5511...)
... e mais 12
⏱️ Tempo estimado: ~2 minutos
(delay de 3-5s entre cada)
Confirma envio? (sim/não)
3. Você: sim
4. Bot: ✅ Iniciando envio...
📤 1/15 - João ✓
📤 2/15 - Maria ✓
...
✅ Concluído! 15 mensagens enviadas.
```
### Comandos
```
"mande promoção pra todos" → Prepara + pede confirmação
"sim" ou "confirmar" → Executa o envio
"não" ou "cancelar" → Cancela
"enviar para 5511..., 5522..." → Lista específica
```
### Limites de Segurança
| Parâmetro | Valor | Motivo |
|-----------|-------|--------|
| Máx por lote | 20 | Evita detecção |
| Delay mínimo | 3 segundos | Simula humano |
| Delay máximo | 5 segundos | Variação natural |
| Pausa longa | 30s cada 10 | Respiro |
| Confirmação | SEMPRE | Evita acidentes |
---
## 3. Relatórios e Estatísticas
### Comandos
```
"relatório"
"quantas mensagens enviei?"
"minhas estatísticas"
"histórico de ações"
```
### Métricas rastreadas
| Métrica | Descrição |
|---------|-----------|
| `enviadas` | Total de mensagens enviadas |
| `grupos_criados` | Grupos criados pelo bot |
| `agendadas` | Mensagens agendadas |
| `contatos` | Contatos salvos na memória |
### Exemplo de resposta
```
📊 RELATÓRIO
📤 Mensagens enviadas: 127
👥 Grupos criados: 3
⏰ Agendamentos: 5
📇 Contatos salvos: 42
```
---
## 4. Integrações
### Google Sheets
#### Importar contatos
```
"importar contatos da planilha https://docs.google.com/spreadsheets/d/xxx"
```
**Formato esperado da planilha:**
| Nome | Telefone |
|------|----------|
| João | 5511999999999 |
| Maria | 5511888888888 |
#### Exportar dados
```
"exportar meus contatos para planilha"
"salvar relatório na planilha"
```
### Google Calendar
#### Buscar eventos
```
"quais meus eventos de hoje?"
"tem reunião hoje?"
```
#### Criar evento
```
"criar evento Reunião amanhã às 14h"
```
#### Notificar sobre eventos
```
"me avise 30 min antes das reuniões"
```
---
## Configuração das Integrações
### Google OAuth2 no n8n
1. Acesse Google Cloud Console
2. Crie projeto ou use existente
3. Ative APIs:
- Google Sheets API
- Google Calendar API
4. Configure OAuth consent screen
5. Crie credenciais OAuth 2.0
6. No n8n: Settings → Credentials → Google OAuth2
### Variáveis de ambiente
```env
# n8n .env
UAZAPI_INSTANCE_ID=sua_instancia
BOT_PHONE_NUMBER=5511999999999
```
---
## Estrutura Redis v4
### Chaves utilizadas
| Chave | Conteúdo | TTL |
|-------|----------|-----|
| `uazapi:user:{phone}` | Contexto do usuário | 7 dias |
| `uazapi:config` | Config global (grupos, etc) | Permanente |
| `uazapi:schedule` | Lista de agendamentos | Permanente |
| `uazapi:stats` | Estatísticas globais | Permanente |
### Estrutura do contexto do usuário
```json
{
"historico": [],
"contatos": [{"nome": "João", "numero": "5511..."}],
"grupos": [{"nome": "Trabalho", "id": "...@g.us"}],
"stats": {
"enviadas": 127,
"grupos_criados": 3,
"agendadas": 5
}
}
```
### Estrutura de agendamento
```json
{
"id": "sched_1234567890",
"numero": "5511999999999",
"mensagem": "Oi!",
"data_hora": "2024-12-25 09:00",
"criado_em": "2024-12-20T10:00:00Z",
"status": "pendente"
}
```
---
## Exemplos de Conversas
### Agendamento Completo
```
Você: manda feliz aniversário pro João amanhã às 8h
Bot: ✅ Agendado #1! Vou enviar "Feliz aniversário!" para João amanhã às 08:00.
Você: agende "bom dia" pra Maria dia 26 às 7h
Bot: ✅ Agendado #2! Enviarei para Maria em 26/12 às 07:00.
Você: listar agendamentos
Bot: 📅 AGENDAMENTOS PENDENTES:
#1 ⏳ João - "Feliz aniversário!"
📅 25/12 às 08:00 (em 2 dias)
#2 ⏳ Maria - "bom dia"
📅 26/12 às 07:00 (em 3 dias)
Você: enviar agora #1
Bot: ✅ Enviado AGORA para João!
Mensagem: "Feliz aniversário!"
(Removido da lista de agendamentos)
Você: cancelar #2
Bot: ❌ Agendamento #2 cancelado.
Maria não receberá "bom dia" em 26/12.
Você: ver pendências
Bot: 📅 Nenhum agendamento pendente.
```
### Envio em massa
```
Você: manda bom dia pra todos os contatos
Bot: Enviando "Bom dia!" para 15 contatos...
✅ Enviado para todos!
```
### Relatório
```
Você: minhas estatísticas
Bot: 📊 RELATÓRIO
📤 Mensagens enviadas: 127
👥 Grupos criados: 3
⏰ Agendamentos: 5
📇 Contatos salvos: 42
```
### Calendar
```
Você: tem reunião hoje?
Bot: 📅 Eventos de hoje:
1. 10:00 - Reunião de equipe
2. 14:00 - Call com cliente
3. 16:30 - Review do projeto
```
---
## Checklist de Setup
- [ ] Importar `workflow-chatbot-v4-full.json`
- [ ] Importar `workflow-scheduler.json`
- [ ] Configurar credenciais:
- [ ] OpenAI API
- [ ] UAZAPI (Header Auth)
- [ ] Redis
- [ ] Google OAuth2 (opcional)
- [ ] Configurar variáveis de ambiente
- [ ] Trocar `SEU_NUMERO_AQUI` pelo seu número
- [ ] Ativar ambos workflows
- [ ] Testar com "oi" no WhatsApp