run-whatsapp-automation
Skill4 starsChanged 4 days agoApache-2.0View on GitHub
Build, run, and drive the WhatsApp group collector — the Baileys collector daemon, the Next.js panel, the MLX transcriber service, and the MCP server. Use to run/start/build/screenshot the project or to call its MCP tools (listar_grupos, ler_mensagens, buscar, resumo_do_dia, ver_imagem, ver_video, ler_documento, transcrever, listar_contatos, preparar_resposta, revisar_texto, responder, responder_midia, status_envio, cancelar_envio, alertar_chat, novidades). ALSO use whenever asked to send, reply, or draft a message in a WhatsApp group: the rule is to run the draft through preparar_resposta and the operator's voice skill, review it with revisar_texto, then confirm the exact text with the user before sending.
- Reads credentials
- Installs packages
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- autonomoSkill
- comunicacao-clienteSkill
- link-whatsappSkill
- plantaoSkill
- run-whatsapp-automationSkill
- agenda-radarSkill
- autonomoSkill
- comunicacao-clienteSkill
- plantaoSkill
- voz-do-operadorSkill
- watchSkill
The file
Files
Run: WhatsApp Automation
Coleta conteúdo de grupos de WhatsApp (áudio/vídeo/imagem/documento/texto) e expõe
tudo pra IA. São 5 processos: wa-collector (daemon Baileys), wa-panel
(Next.js em :3000), wa-transcriber (serviço MLX em :4320), wa-notifier
(notificação de mensagens de cliente, ver seção abaixo) e o MCP server
(stdio, sob demanda). O MCP é dirigido pelo driver abaixo. Tools de escrita
preparar_resposta (contexto antes de redigir) e revisar_texto (revisa sem
enviar) entram no pipeline de envio — ver seção "Regra: enviar mensagem no
grupo" abaixo.
Como os 3 primeiros rodam: em dev local é
npm run devna raiz, que sobe os três viaconcurrently— não pm2. Em produção é pm2 (ecosystem.config.cjs). Os dois caminhos existem; veja "Run" abaixo.pm2 lsvazio NÃO significa serviços fora — confirme sempre pelos smokecurl(:3000 / :4310 / :4320), não pelo pm2.
Plataforma: macOS Apple Silicon. A transcrição usa
mlx_whisper(MLX), que só roda em Apple Silicon — em Linux o coletor e o painel sobem, mas o transcriber não. Paths neste arquivo são relativos à raiz do repo.
Mais de uma conta: um MCP por coletor
whatsapp-collector= coletor principal. É o default.- Uma segunda conta (ex.: um WhatsApp pessoal) roda num coletor próprio, com um segundo MCP
(no exemplo,
whatsapp-pessoal): mesmas tools, mesmo código, outro trioWAC_*de acesso. Use quando o operador citar essa conta ou o chat não existir no principal. Contas diferentes → slugs diferentes;listar_gruposem cada um. Plantão nela:PLANTAO_CLOUD=pessoalnoplantao-stream.sh.
⚠️ Regra: enviar mensagem (grupo ou DM) → humanizar SEMPRE
Sempre que o usuário pedir para enviar, responder ou redigir uma mensagem num
grupo (via responder, responder_midia com legenda, pelo painel, ou pela API de controle :4310):
Pipeline de envio, nesta ordem: preparar_resposta(grupo) → skill de voz do operador
(voz-do-operador preenchida (o nome vem de WAC_SKILL_VOZ)) → comunicacao-cliente (conduta) →
no modo confirmar, revisar_texto e mostrar ao operador o texto já revisado → responder
com candidatos (2-3 versões) ou baloes. humanizer não entra em balão de conversa. Se a revisão recusar, reescreva seguindo sugestoes; não use revisao: 'ignorar'
sem OK explícito do operador.
- Antes de redigir, chame
preparar_resposta(grupo)— devolve o estilo recente do chat e o que o cliente deixou em aberto, cominstrucoesnuméricas. - Rascunhe a mensagem com a skill de voz do operador (
voz-do-operador). - Se for mensagem pra cliente/parceiro, aplique depois a skill
comunicacao-cliente— a camada de conduta: o que responder e o que deixar, os três modos (factual/delicado/grave), como comunicar erro sem se rebaixar, regras de relação e qualurgenciapassar. Ela não opina sobre forma (isso é da voz) nem repete os tells (isso oresponderrecusa em código).humanizersó em prosa longa, se o operador pedir. - Confirme antes de enviar (mostre texto + grupo), EXCETO quando o usuário já
liberou envio direto pra aquele contexto (ex: suporte técnico onde ele autorizou
responder o cliente na hora). A exceção NÃO cobre primeiro contato: mensagem pra quem a
conta nunca falou sempre passa pelo OK do texto. No modo
confirmar, roderevisar_textoprimeiro e mostre ao operador o texto já revisado (fica mais fácil aprovar sabendo que passou). - Só então envie:
responderaceitacandidatos(2-3 versões — o código envia a que menos destoa do chat) oubaloes(já decidida a quebra). A revisão de estilo (web/lib/estilo/) roda dentro doresponder/responder_midia/editar_mensagemantes do envio de verdade; se recusar, ela devolvehits/sugestoes— reescreva e chame de novo, nada foi enviado.revisao: 'ignorar'pula só o score (nunca os bloqueios) e só com OK explícito do operador pro texto exatamente como está. - Ticket e cancelamento:
responderdevolve umticketna hora e a entrega sai depois, com latência humana (segundos numa conversa ativa, minutos a horas numa fria). Guarde o ticket;status_envio(ticket)consulta. Se o plantão imprimirEntrega interrompida (mensagem nova, …), o cliente falou antes do balão sair:ler_mensagens→preparar_resposta→responderde novo (o novo ticket substitui o anterior). Se o operador disser "cancela", chamecancelar_envio(grupo)NA HORA, sem confirmar. Depois de qualquer cancelamento ou interrupção,ler_mensagensantes de reenviar — parte pode ter saído.urgencia: 'agora'só quando o cliente espera um ok imediato.
Isso vale para qualquer envio, a grupo ou a DM (primeiro contato incluído) — é uma regra fixa, não opcional.
🚨 Regras duras de envio
O caso clássico: um envio "falha" no transporte, o agente contorna re-enviando por outro canal — e o destinatário recebe a mensagem em dobro (a original TINHA saído), mais um "teste" solto no meio. Pra isso nunca acontecer:
- Nunca envie mensagem sem pedido explícito do operador PARA AQUELE chat — nem "teste", nem diagnóstico, nem "confirmar que o canal voltou". Envio falhou? Reporte a falha e pare; não contorne enviando por outro canal.
- Mensagem de teste é só em chat de teste (um grupo dedicado a isso) — jamais em chat real.
- Antes de re-tentar um envio que "falhou": rode
ler_mensagensno chat e confira se a mensagem original saiu (fromMerecente com o mesmo texto). Erro de transporte NÃO significa que a mensagem não chegou. Só re-envie se comprovadamente não saiu. Erro: fetch failednorespondernormalmente é o MCP da sessão desatualizado (config carregada no boot) ou o coletor local desligado. O fix é reconectar o MCP (/mcp→ reconnect) ou reiniciar a sessão — não é improvisar um canal alternativo de envio.
Opcional, só para prosa longa (proposta, changelog): a skill
humanizer(git clone https://github.com/blader/humanizer.git ~/.claude/skills/humanizer). Nunca em balão de conversa.
Prerequisites
# Node 20+ (testado v24), pm2, ffmpeg, e o mlx_whisper via uv tool
brew install ffmpeg
npm install -g pm2
uv tool install mlx-whisper # instala em ~/.local/share/uv/tools/mlx-whisperPrecisa de uma conta de WhatsApp pra parear (QR na 1ª execução).
Build
npm install # deps do coletor (raiz)
npm run build # coletor -> dist/
cd web && npm install && npm run build && cd .. # painel + MCP (Next.js)Run
Dev local: um comando na raiz sobe os três processos via concurrently.
npm run dev # roda `npm run sync` e sobe collector + panel + transcriberProdução (24/7): pm2.
pm2 start ecosystem.config.cjs && pm2 save
pm2 ls # wa-collector / wa-panel / wa-transcriber = onlineNão confie no
pm2 lspra saber se está no ar — em dev ele vem vazio mesmo com tudo rodando. Use os smokecurlabaixo.
1ª vez — parear: abra http://localhost:3000/config (o QR aparece ali). Escaneie no
WhatsApp › Aparelhos conectados. A sessão fica em auth/ e reconecta sozinha depois.
Marque os grupos a monitorar em /config.
Smoke dos serviços (todos devem responder):
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/ # 200
curl -s http://127.0.0.1:4310/health # {"ok":true} (controle/envio)
curl -s http://127.0.0.1:4320/health # {"ok":true,...} (transcriber)Drive the MCP (agent path) — primary
O driver sobe o MCP server, faz o handshake stdio e lista/chama ferramentas:
# lista as ferramentas
node .claude/skills/run-whatsapp-automation/driver.mjs
# chamar uma ferramenta (args em JSON)
node .claude/skills/run-whatsapp-automation/driver.mjs call listar_grupos
node .claude/skills/run-whatsapp-automation/driver.mjs call buscar '{"texto":"MCP"}'
node .claude/skills/run-whatsapp-automation/driver.mjs call resumo_do_dia '{"grupo":"meu-grupo"}'
node .claude/skills/run-whatsapp-automation/driver.mjs call ver_imagem '{"grupo":"meu-grupo","mediaPath":"meu-grupo/image/<arquivo>.jpg"}'
node .claude/skills/run-whatsapp-automation/driver.mjs call ler_documento '{"grupo":"meu-grupo","mediaPath":"meu-grupo/document/<arquivo>.pdf"}'
node .claude/skills/run-whatsapp-automation/driver.mjs call ver_video '{"grupo":"meu-grupo","mediaPath":"meu-grupo/gif/<arquivo>.mp4","frames":3}' # GIF/vídeo: amostra frames (precisa de ffmpeg)
# responder_midia ENVIA de verdade — só após confirmar com o usuário (legenda na voz do operador, revisada como o responder):
node .claude/skills/run-whatsapp-automation/driver.mjs call responder_midia '{"grupo":"Acme Corp","kind":"document","path":"/abs/contrato.pdf","fileName":"contrato.pdf","caption":"segue o contrato"}'
# alertar_chat liga/desliga a notificação de tela de um chat; novidades puxa o que chegou (ver seção abaixo):
node .claude/skills/run-whatsapp-automation/driver.mjs call alertar_chat '{"grupo":"dm-<id>","ativar":true}'
node .claude/skills/run-whatsapp-automation/driver.mjs call novidades '{}'O driver resolve a raiz do repo sozinho e injeta WAC_DATA_DIR/WAC_GROUPS_CONFIG
absolutos. Saída de texto vai pro stdout; imagens viram [imagem image/jpeg, N bytes].
No Claude Code o MCP já está registrado em .mcp.json (escopo do projeto) —
aprove no 1º uso; ferramentas novas exigem reload da sessão.
Drive the panel (web)
Web app em http://localhost:3000. Telas: / (grupos), /g/<slug> (timeline),
/config (conexão/QR, grupos, time, modelo), /novo (nova conversa), /links
(linkar projeto↔conversa, ver seção abaixo). Verificado por navegador (screenshot)
e pelos curl acima.
Monitorar / acompanhar (grupos e DMs)
Três coisas distintas — não confunda (é onde os agentes mais se perdem):
- Coleta (
watch): a flagwatchemgroups.config.json(ou no painel/config) liga/desliga a captura — e só vale pra grupo. DM é coletado SEMPRE, automaticamente, desde a 1ª mensagem; não há (nem precisa) flag pra ligar. O slug de um DM édm-<id>(ex:dm-<id>). - Copiloto do painel (
copilotno.triage.json): liga sugestões de resposta dentro da interface web (não envia nada). É uma IA embutida no painel, opt-in por conversa, ligada só pelo painel. NÃO é o agente que consome este MCP — se você é o Claude/Codex usando o MCP, o copiloto do painel não te diz respeito. - Alerta / wake-on-message (
alertarno.triage.json): opt-in por conversa pra ser avisado quando chega mensagem de cliente. Liga comalertar_chat {grupo, ativar}(ou no painel). Um processowa-notifier(separado) observa os chats marcados e dispara uma notificação de tela (macOS) quando o cliente escreve. Ao ser avisado, chamenovidadespra puxar o que chegou desde a última vez (avança um checkpoint próprio;marcar:falsesó espia). - Triagem:
marcar_resolvido/silenciar_grupo/anotar/ler_notas/estado_triagem— tudo por slug, vale pra DM também.
Pedido típico: "acompanhar/monitorar o contato do fulano". O DM já está coletado (procure a pasta
dm-<id>emdata/, uselistar_grupos/ler_mensagens). Não saia procurando uma flag de watch pra DM — ela não existe. Pra "ser avisado quando ele escrever", liguealertar_chat; owa-notifierte notifica e você puxa comnovidades. (Lembrete técnico: não há push que acorde uma sessão Claude ociosa — a notificação é pro humano, que então te aciona; daí você chamanovidades.)
Pedido típico: "manda mensagem pro fulano, o número é X" e a conta NUNCA falou com esse número. Funciona, e não precisa de nada antes: não procure em
listar_contatos, não procure pastadm-<id>(ela só nasce depois da 1ª mensagem), não conclua que "não dá". Chameresponder { grupo: "dm-<55DDDnúmero>" }: só dígitos, prefixe55+ DDD se o operador passou sem ("11 99999-9999" viradm-5511999999999), e deixe o nono dígito COMO VEIO, sem testar variações.preparar_resposta,revisar_textoeestado_triagemfuncionam nesse slug mesmo com o chat ainda vazio (modoconfirmar, conversa fria), então o fluxo de redação é o de sempre. O coletor pergunta ao WhatsApp qual é a conta desse número antes de enviar: no Brasil muita conta é registrada SEM o nono dígito, e mandar pro número digitado dá um tique e nunca entrega. Três desfechos:
- entregou no mesmo número → segue normal.
- retorno com
jid_corrigido_de→ a conta é outra grafia do número; passe a usar oslug_corretodo retorno pra ler e responder (é lá que a resposta da pessoa vai cair).- recusa "não está no WhatsApp" → nada saiu; confira o número com o operador.
Latência: chat sem histórico cai no regime FRIO (a mensagem pode levar de minutos a horas pra sair). Se a pessoa acabou de pedir contato e está esperando, passe
urgencia: "agora".Conduta de primeiro contato (quem, o quê, quanto): skill
comunicacao-cliente.
Linkar um projeto a uma conversa
Amarra um repositório de cliente a um grupo/DM, pra qualquer Claude aberto naquele repo já saber qual conversa consultar. Dois lados:
- No repo do cliente:
.claude/whatsapp.json({ grupo, cliente, tipo, notas },grupo= slug) + uma linha entre<!-- wa-link:start -->/<!-- wa-link:end -->noCLAUDE.md(é ela que faz o Claude descobrir o link sozinho no boot). Versionar é a critério do dono do repo. - Aqui:
data/links.json(índice central slug→repo que o painel usa). Gitignored.
Criar (não improvise outro caminho): o slash command /link-whatsapp rodado dentro
do repo do cliente, ou a tela /links do painel. Os dois escrevem os dois lados.
Consumir (Claude no repo do cliente): leia .claude/whatsapp.json, pegue o grupo,
e use esse slug nas chamadas do MCP whatsapp-collector (resumo_do_dia, ler_mensagens,
buscar, etc.). Se central e repo divergirem (ex: repo movido), re-rode o link em vez
de caçar o caminho certo.
Human path
cd web && npm run dev sobe só o painel em :3000 (útil pra mexer no front sem o coletor).
O npm run dev da raiz sobe os três juntos (ver "Run").
Sync nuvem→local (opcional)
Quando o coletor roda 24/7 na nuvem (captura mesmo com a máquina local desligada), a máquina local puxa
o que perdeu no período off via WAC_CLOUD_URL/WAC_CLOUD_USER/WAC_CLOUD_PASS no
.env (URL do painel na nuvem + Basic Auth). Com isso:
npm run devrodanpm run syncantes de subir o coletor local (janela segura) — merge poriddomessages.jsonl(+ sidecars) da nuvem nodata/local, sem perder o que o coletor local já gravou.npm run syncroda o pull à mão.- Mídia sob demanda: ao transcrever/ver uma mídia que só chegou na nuvem durante
o off (
ensureLocalMedia), a máquina local baixa o arquivo e cacheia. SemWAC_CLOUD_URL, tudo se comporta como antes (sync e fallback desligados). - O coletor local segue rodando (redundância); a nuvem é o backup que preenche gaps.
- Escopo (
WAC_SYNC_SCOPE):local(default) só sincroniza grupos que a máquina local já tem;alltraz tudo (a nuvem costuma ter dez vezes mais grupos/DMs da history sync do que os acompanhados). Paralelismo viaWAC_SYNC_CONCURRENCY(default 8). O texto vai gzipado (otailscale serveuserspace trava com payloads >~1.5MB).
Gotchas (cicatrizes)
- MLX é Apple-Silicon only.
mlx_whispernão importa no python padrão (instalado viauv tool); oecosystem.config.cjsaponta ointerpreterpra~/.local/share/uv/tools/mlx-whisper/bin/python. Em Linux, troque por whisper.cpp. - Transcriber é preguiçoso/morno: ~2.4MB parado, carrega o modelo no 1º uso (~3.8s), reusa quente (~1.3s), e libera a RAM após 180s ocioso. Se o serviço estiver fora, o Node cai pro CLI
mlx_whisper(mais lento). - Mensagens próprias enviadas pela API vêm como
type:'append'no Baileys (não'notify') — por isso ogateway.sendTextmapeia e emite a própria mensagem; senão o balão "Você" não aparece. As enviadas do celular em tempo real são'notify'. - MCP via tsx: o
tsxestá emweb/node_modules(não na raiz). O driver usaweb/node_modules/.bin/tsx.webnão étype:module→ o server usamain()(top-level await quebraria em CJS). - Envio é real e local: controle (:4310) e painel mandam mensagem como você — só em
127.0.0.1, nunca expor. Boot do pm2 exigepm2 startup(sudo, 1x). data/,auth/,groups.config.jsonsão gitignored (conteúdo + sessão). Não versionar.- Grupo renomeado NÃO muda o slug. O slug é estável por jid (persistido no
groups.config.jsonna primeira vez que o grupo é visto); renomear só troca oname.listar_grupostraz um blocorenomeadosquando nome atual ≠ slug, eler_mensagens/responderaceitam o nome novo e traduzem pro slug estável sozinhos. Se um chat parecer "mudo"/congelado, suspeite de rename ANTES de achar que o sync quebrou. Diretório duplicado de rename antigo (anterior à feature): fundir comnpm run migrar-slug -- <slug-canonico> <slug-duplicado>(na nuvem: viarailway ssh,cd /app && npx tsx scripts/migrar-slug.ts ...).
Troubleshooting
| Sintoma | Fix |
ModuleNotFoundError: mlx_whisper | Use o python do uv tool (o ecosystem já seta interpreter). |
driver: spawn .../tsx ENOENT | cd web && npm install -D tsx |
Top-level await ... cjs no MCP | server precisa do wrapper main() (já aplicado). |
| Balão "Você" não aparece após enviar | coletor precisa do gateway.sendText que auto-emite (rebuild npm run build + pm2 restart wa-collector). |
connection: qr não some | pareie o QR em /config; sessão deslogada → apague auth/ e pareie de novo. |
| Chat "parou de receber" mas outros chats seguem vivos | Provável rename do grupo: confira renomeados no listar_grupos e siga usando o slug estável; split antigo → npm run migrar-slug. |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

