Configurar e gerenciar o sistema
Você é responsável por importar contatos, criar campanhas, conectar o WhatsApp, cadastrar usuários e manter o anti-ban saudável. Aqui está como fazer cada coisa.
📥 1. Importar contatos
/contacts/import aceita CSV com cabeçalho. A importação roda em background.
Formato esperado do CSV
Campos reconhecidos
| Campo | Obrigatório | Notas |
|---|---|---|
| telefone | ✅ Sim | Aceita com/sem DDI/DDD; é normalizado pra E.164 |
| nome | Recomendado | Usado em {{primeiro_nome}} |
| cpf | Opcional | Mascarado nos logs (LGPD) |
| orgao | Opcional | Útil pra segmentação |
| vinculo | Opcional | Ativo / Pensionista / Aposentado |
| margem | Opcional | Decimal — para priorização |
Passo a passo
- Acesse /contacts/import.
- Escolha o arquivo CSV.
- (Opcional) Selecione tags pra aplicar a todos os contatos do arquivo.
- Clique em Importar. O sistema processa em background.
- Acompanhe o status na lista de jobs — quando terminar, os contatos aparecem em /contacts.
📣 3. Criar campanha
Em /campaigns/new você combina: tags, mensagem, cadência, datas e prompts.
Campos da campanha
| Campo | Para que serve |
|---|---|
| Nome | Identificação interna da campanha |
| Tags | Quais contatos vão receber (1 ou mais tags) |
| Mensagem | Suporta {{primeiro_nome}}. Incluir instrução de saída pra LGPD. |
| vCard | Cartão do consultor (nome + telefone) anexado à mensagem |
| Início / Fim | Janela em que a campanha pode disparar |
| Intervalo | Range em segundos entre cada envio (jitter) |
| Contatos/dia | Quantos números diferentes recebem por dia |
| Mensagens/dia | Total absoluto de envios por dia |
| Prompts IA | Override do classificador/bot (avançado) |
📋 Clonar campanha
Botão 📋 Clonar na tela da campanha cria uma cópia em DRAFT com a mesma mensagem, prompts e limites — datas ficam em branco. Útil pra disparar a mesma régua pra outro grupo.
▶️ 4. Disparar e acompanhar
Acompanhe o progresso e os motivos de parada.
Bloco "Por que ainda não há envios?"
Se total_sent = 0, o sistema mostra exatamente o que está bloqueando:
- Kill switch global ativo em /admin/settings
- Nenhuma instância Z-API conectada/saudável
- Fora da janela ativa (9h–18h BR)
- Aguardando data de início
- Janela da campanha expirou (ends_at)
- Fila vazia — todos opt-out / blacklist / cooldown
Ações disponíveis
📅 5. Datas e limites diários
Configure a janela e os tetos da campanha.
Mensagens aguardam até essa data. Útil pra preparar uma campanha agora e disparar na segunda de manhã.
Quando chega o fim, mensagens restantes viram FAILED e a campanha vira COMPLETED. Evita continuar mandando uma promoção que já acabou.
Quantos telefones diferentes podem receber por dia. Ao atingir, o restante é adiado pra amanhã às 9h BR.
Teto absoluto de envios da campanha por dia. Considera SENT/DELIVERED/READ.
Você tem 1.000 contatos e quer disparar em 5 dias úteis, sem queimar a conta. Configure: início = segunda 9h, fim = sexta 18h, contatos/dia = 200. O sistema espalha o envio e respeita o teto.
📤 6. Botão "Enviar teste"
Antes de disparar pra todo mundo, mande a mensagem pro seu próprio número.
- Envia imediatamente pelo Z-API.
- Bypassa anti-ban, cooldown, janela 9h-18h e fila.
- Usa o texto da campanha por padrão, com {{nome}} virando "Teste".
- Você pode digitar um texto diferente no campo de cima pra testar variações.
- Audit log registra CAMPAIGN_TEST_SEND com últimos 4 dígitos do número (PII mascarada).
🔌 7. Z-API (WhatsApp)
O envio real de WhatsApp passa pelo Z-API. Você cadastra suas instâncias (números) no painel.
Como conectar um número
- Crie uma conta em z-api.io e crie uma instância.
- Anote: instance ID, token e client token.
- No painel, vá em /admin/instances → Nova instância.
- Preencha os 3 campos + nome de exibição + telefone associado.
- Salve e clique em Conectar QR — escaneie com o WhatsApp do número.
- Status muda de DISCONNECTED pra CONNECTED.
Webhooks Z-API
Em /admin/settings → Integrações, você encontra a URL do webhook pra colar no painel do Z-API. Os eventos que devem estar habilitados:
🛡️ 8. Anti-ban e kill switch
Mecanismos pra reduzir risco de banimento das contas.
Quando usar o kill switch
- Cliente importou lista errada por engano → pausa enquanto investiga.
- Atendente reportou cliente reclamando muito → pausa pra revisar mensagem.
- Z-API caiu → pausa pra não acumular falhas.
🤖 9. Prompts da IA
O sistema usa Claude (Anthropic) pra classificar respostas e gerar auto-respostas. Os prompts são configuráveis.
Dois prompts por campanha
Lê a resposta do cliente e devolve uma de 4 categorias: GREEN_INTEREST, NEUTRAL, YELLOW_DISINTEREST, RED_AGGRESSIVE.
Gera a próxima mensagem do bot. Pode devolver "ESCALATE" pra sinalizar que precisa de humano.
Onde editar
- Global: /admin/settings → Prompts — vale pra todas as campanhas sem override.
- Por campanha: seção "Prompts de IA" no formulário da campanha.
- Modelos prontos: /admin/prompt-templates — crie templates e aplique em campanhas.
⚡ 10. Snippets
Textos pré-prontos que os atendentes inserem no chat.
Gerencie em /admin/snippets. Cada snippet tem um título (mostrado na lista) e o texto (vai pro campo de mensagem ao clicar).
Sugestões de snippets úteis
👥 11. Usuários e SSO
Cadastre quem pode acessar o painel.
Cadastro manual
- Acesse /admin/users.
- Clique em Novo usuário.
- Preencha email, nome, senha temporária e perfil (ADMIN ou OPERATOR).
- Compartilhe a senha com o usuário (peça pra ele trocar no primeiro login).
Perfis
Login com Google (SSO)
- Acesse Google Cloud Console, crie um OAuth Client ID.
- Adicione o redirect URI mostrado em /admin/settings → Auth.
- Copie o Client ID e Client Secret pro painel.
- Habilite "Login com Google" no toggle.
- (Opcional) Auto-cadastro: usuários novos via Google viram OPERATOR automaticamente.
Toggle "Login com senha"
Você pode desligar o login com senha e forçar todos via SSO Google em /admin/settings → Auth.
📋 12. Audit log
Registro de toda ação sensível. Acesse em /admin/audit.
Ações registradas
CPF vira ***.***.***-**, telefone vira 55********4321, e-mail vira j***@empresa.com. O log é purgado automaticamente após 180 dias.
🚫 13. Blacklist
Números bloqueados nunca recebem mensagem, mesmo que sejam reimportados.
Como um número entra na blacklist
- Atendente seleciona conversas e clica em 🚫 Blacklist em lote.
- Administrador adiciona manualmente em /admin/blacklist.
- Importação CSV de blacklist (linhas com E.164).
Gerenciar a blacklist
/admin/blacklist lista todos os números com motivo, origem e quem adicionou. Pra remover, clique em Excluir ao lado do número. A remoção é registrada no audit log.
⚖️ 14. LGPD
O sistema foi pensado pra cumprir a Lei Geral de Proteção de Dados.
🔧 15. Problemas comuns
Disparei a campanha mas ninguém recebeu
Cheque o bloco amarelo "Por que ainda não há envios?" na tela da campanha. Causas mais comuns:
- Kill switch global ativo
- Nenhuma instância Z-API conectada
- Fora da janela 9h–18h BR
- Aguardando data de início
- Fila vazia (todos contatos em opt-out/cooldown)
Instância caiu — como reconectar?
Vá em /admin/instances, clique na instância afetada e use Reconectar QR. Escaneie de novo com o WhatsApp do número.
A IA está classificando errado
2 opções:
- Atendentes podem usar "✎ Ajustar…" pra override manual.
- Refine o prompt em /admin/settings → Prompts ou direto na campanha. Adicione exemplos do que está errando.
Como pausar TUDO em emergência
Ative o kill switch global em /admin/settings ou pelo banner vermelho no topo. Pausa todos os envios em 1 clique.
Quero remover um número da blacklist
/admin/blacklist → busque o número → clique em Excluir. A remoção fica registrada no audit log.
Backup e restore
Banco MySQL e diretório /storage/media devem ser incluídos no backup. Snapshots completos ficam em /root/backup quando rodados via script.