WhatsApp Engineer

Skill avançada para OpenClaw que ajuda terceiros a monitorar WhatsApp localmente com perfis separados, histórico em SQLite, MCP whatsapp-profiles, download/transcrição de mídia e entrega de resumos operacionais.

Escopo: leitura, busca, resumo, transcrição e entrega controlada. Escrita/admin em WhatsApp é modo avançado, bloqueado por padrão e exige confirmação explícita.

O que faz

• Pareia um número WhatsApp por QR em ambiente controlado.

• Mantém engine Baileys própria para leitura/sincronia local.

• Guarda histórico em SQLite local fora do Git.

• Expõe busca histórica via MCP whatsapp-profiles.

• Lista mensagens, links, documentos, imagens, vídeos e áudios.

• Transcreve áudios localmente quando mídia baixada está disponível.

• Gera resumos operacionais por período/perfil/chat.

• Entrega resultado em destino configurado: Telegram, Discord, manual ou adaptador próprio.

Related MCP server: WhatsApp MCP Server

Para quem é

• Times que precisam acompanhar WhatsApp de suporte, vendas ou operação.

• Agentes OpenClaw que precisam consultar histórico local sem expor bancos na nuvem.

• Desenvolvedores que querem uma base para criar monitoramento privado por perfil.

Não é skill para usuário leigo. Use em VPS/container ou máquina dedicada, com consentimento de quem pareia o número.

Instalação rápida

git clone https://github.com/spanevello0x/whatsapp-engineer.git ~/.openclaw/skills/whatsapp-engineer
cd ~/.openclaw/skills/whatsapp-engineer
npm install
python3 workspace/run.py status

Configuração guiada:

python3 scripts/configure.py

Wizard publico de instalacao, privacidade, QR e registro de telefones:

python3 workspace/run.py install-wizard

Simulacao sem conectar WhatsApp real:

python3 workspace/run.py simulate-install --print-plan

Pareamento por QR:

python3 workspace/run.py connect --project Equipe --name Principal --number PHONE_E164

Depois do scan, valide:

python3 workspace/run.py status-v2
python3 workspace/run.py history-search-v2 --limit 10

MCP embutido

O servidor MCP fica em:

embedded_mcp/whatsapp_profiles/

Ele lê profiles.json e os bancos messages.db dos perfis. Dados reais não ficam no repositório.

Registrar MCP:

python3 workspace/run.py setup-mcp \
  --profiles-config "$HOME/Documents/WhatsApp MCP Profiles/profiles.json" \
  --install \
  --register

Onde ficam dados sensíveis

Nunca versionar:

• QR codes;

• sessões WhatsApp;

• messages.db, whatsapp.db ou qualquer SQLite real;

• mídias baixadas;

• logs;

• tokens de Telegram/Discord/OpenClaw;

• exports de contatos ou conversas.

Por padrão, estado local fica em:

~/.openclaw/state/whatsapp-engineer/

Segurança operacional

• O pareamento pode baixar 100% das conversas acessiveis pelo WhatsApp Web para o ambiente local.

• O agente/sistema que consulta o historico precisa ter guardrails para nao vazar conversas a terceiros, grupos publicos ou canais errados.

• Antes de gerar QR, documente quem e dono do telefone, finalidade do monitoramento, escopo e consentimento.

• Sincronia 100% continua pode sobrecarregar o ambiente. Prefira rotina horaria, diaria ou horario comercial quando tempo real nao for necessario.

• Um número = uma engine dona por vez.

• Não rode junto com outro Baileys/gateway usando o mesmo número.

• Escrita/admin exige --execute e flags explícitas.

• Confirme destino antes do primeiro envio real.

• Use variáveis de ambiente para tokens; a skill salva só o nome da variável.

• Respeite consentimento, privacidade e legislação aplicável.

Exemplo de config

{
  "version": 1,
  "agent": { "name": "agent" },
  "source": {
    "mcp": "whatsapp-profiles",
    "profiles": ["vendas-principal"],
    "chats": [],
    "default_period": "last_24h"
  },
  "digest": {
    "include_links": true,
    "include_audio": true,
    "max_messages": 120,
    "format": "operational"
  },
  "destinations": {
    "primary": {
      "type": "telegram",
      "target_kind": "topic",
      "chat_id": "-1001234567890",
      "message_thread_id": 123,
      "token_env": "TELEGRAM_BOT_TOKEN",
      "parse_mode": "HTML"
    }
  },
  "safety": {
    "redact_phone_numbers": true,
    "require_confirmation_for_whatsapp_send": true,
    "confirm_first_delivery": true,
    "never_store_tokens": true
  }
}

Estrutura

embedded_mcp/whatsapp_profiles/  # MCP local para consultar perfis SQLite
scripts/                         # setup, QR, busca, transcrição, entrega
workspace/run.py                 # wrapper operacional principal
workspace/*.mjs                  # worker Baileys e helpers Node
references/                      # docs de configuração e operação

Wizard publico

O comando install-wizard conduz uma instalacao segura para OpenClaw, Hermes, Codex ou outro runtime:

• exibe aviso de privacidade antes do QR;

• registra telefones, donos, finalidade, escopo, consentimento e cadencia;

• gera um plano privado em ~/.openclaw/state/whatsapp-engineer/install/install-plan.json;

• atualiza ~/.openclaw/state/whatsapp-engineer/phone_registry.json;

• gera o QR como PNG e tenta entregar na conversa/canal de implementacao pelo gateway escolhido;

• sugere crons e modos de uso conforme a cadencia escolhida.

Fluxo recomendado:

python3 workspace/run.py install-wizard
python3 workspace/run.py install-wizard --generate-qr --monitor
python3 workspace/run.py status-v2

Use simulate-install para validar a experiencia sem conectar um telefone real.

Para entrega automatica no OpenClaw, informe gateway.channel e gateway.target no JSON de respostas, ou rode em um ambiente que exponha OPENCLAW_CHANNEL e OPENCLAW_TARGET. Sem destino explicito, o wizard imprime fallback MEDIA:/path/to/qr-handoff.png para evitar mandar QR sensivel no lugar errado.

Licença

MIT. Use como base, adapte com cuidado e nunca publique dados pessoais.