whatsapp-web-mcp: Instructions file for Codex

WhatsApp MCP Agent Instructions

Public API v1

Use somente:

• whatsapp_status
• whatsapp_list_chats
• whatsapp_find
• whatsapp_get_contact
• whatsapp_get_chat_info
• whatsapp_get_message
• whatsapp_get_messages
• whatsapp_get_chat
• whatsapp_get_media
• whatsapp_understand
• whatsapp_send_message
• whatsapp_jobs
• whatsapp_settings

Todas as chamadas recebem um objeto request tipado. Não use ferramentas antigas, aliases, Playwright externo, DOM, SQLite, IndexedDB, WasIstLos, ZapZap, MyZap ou automação de browser para compensar falha de domínio.

Domain Contract

1. Peça dados de domínio: chats, contatos, mensagens, mídia, entendimento, jobs, settings ou envio. O MCP resolve OpenWA, histórico, artefatos, transcrição e confirmação internamente.
2. Não faça preflight com whatsapp_status antes de uma leitura comum. Chame a ferramenta da intenção; se ela retornar login_required, execute whatsapp-web-mcp auth --profile default quando houver shell local e diga apenas que o navegador foi aberto para o QR. Use status para diagnóstico.
3. Nunca cole, anexe, descreva ou reconstrua QR Code no chat.
4. Use whatsapp_list_chats para descobrir um chat. Quando o chat já for conhecido, vá direto a whatsapp_get_messages; não use busca global. whatsapp_find é para identidade ou conteúdo sem chat conhecido. Depois prefira IDs públicos como c_..., m_..., a_....
5. Não peça JID, endpoint, API key, sessão, seletor, scroll, DOM, composer ou posição de tela ao usuário.
6. whatsapp_get_chat_info é barato; whatsapp_get_chat pode hidratar histórico e gerar artefatos.
7. Passe períodos naturais diretamente, como hoje, ontem, março de 2026, últimos 30 dias ou 13/06/2026 das 13h ate 14h. O MCP normaliza datas, carrega lotes antigos e declara cobertura; não tente controlar scroll, DOM ou paginação de tela.
8. Resultados grandes devem virar conversation.md, conversation.jsonl e manifest.json; não despeje histórico enorme no contexto.
9. Leituras nunca enviam, limpam ou substituem drafts do usuário.
10. Use whatsapp_get_media pelo message_id; nunca associe mídia por chute.
11. Use whatsapp_understand para transcrição WhisperX, OCR, extração de documentos e ZIP. Ele aceita message_id e captura a mídia internamente. Transcrição é compacta; peça formats=["segments"] apenas quando necessário.
12. Trate perfil, sessão, API key, exports, mídia, transcripts e actions como dados sensíveis.
13. Para a mídia mais recente de um chat, use types e limit=1. audio inclui notas de voz; ptt seleciona somente notas de voz.