WhatsApp MCP Skill

Este skill permite enviar mensajes, archivos y gestionar grupos de WhatsApp desde GitHub Copilot usando el servidor MCP whatsapp-mcp-server (basado en whatsapp-web.js).

Paso 0 — Verificar si el MCP está disponible

Antes de cualquier operación, ejecuta healthcheck_whatsapp. Interpreta el resultado:

Flujo principal

Enviar mensaje de texto

1. Buscar contacto: findwhatsappcontact con nombre o número
2. Usar el id que termina en @c.us como chatId/phoneNumber
3. Siempre hacer dryRun: true primero para que el usuario confirme
4. Con confirmación: enviar con dryRun: false

Enviar archivo (PDF, imagen, VCF, etc.)

1. Verificar que el archivo existe en disco (ruta absoluta)
2. Si hay que convertir HTML→PDF: usar Chrome headless:

``bash /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \ --headless=new --disable-gpu --no-sandbox \ --print-to-pdf="/ruta/output.pdf" --print-to-pdf-no-header \ "file:///ruta/input.html" ``

1. dryRun: true → confirmar → sendmediamessage con dryRun: false

Grupos

• Listar grupos: listwhatsappgroups
• Añadir miembro: addgroupparticipant (necesita número normalizado)
• Eliminar miembro: removegroupparticipant
• Link de invitación: getgroupinvite_link

Historial de chat

• getchatmessages con chatId y limit (máx 100)
• ⚠️ Los mensajes contienen datos personales (números de teléfono, texto de conversaciones). No almacenar ni exponer más allá de lo necesario para la operación actual.

Normalización de números de teléfono

El MCP normaliza automáticamente los números antes de usarlos. Formato interno: <dígitos>@c.us.

Reglas de normalización (normalizePhoneToWaId):

1. Se eliminan espacios, guiones y paréntesis.
2. Se elimina el + inicial si existe.
3. Si empieza con 0 → número local (ej. Austria 069x) → se reemplaza el 0 por el DEFAULTCOUNTRYCODE configurado (43 por defecto).
4. Si ya tiene un código de país diferente al configurado (ej. 34..., 1...) → no se modifica. Pasar tal cual.

⚠️ Error histórico: Antes de la corrección del 2025-06, el server añadía 43 a cualquier número no local, causando que números españoles 34619880445 → [email protected] ❌. Esto está corregido en src/whatsapp/client.ts.

Reglas importantes

• Siempre dryRun primero antes de enviar — nunca enviar sin confirmación del usuario.
• Los chatId para contactos terminan en @c.us, para grupos en @g.us.
• Para números no austriacos (ej. españoles 34..., americanos 1...): pasar el número completo con código de país. El MCP lo detecta automáticamente y no le añade el 43.
• PDFs e imágenes: sendmediamessage acepta ruta absoluta en disco del servidor.
• Si el contacto no aparece: probar con apellido/nombre invertidos o variantes de mayúsculas.

Referencia de tools

Ver [references/tools.md](references/tools.md) para descripción completa de cada tool MCP disponible.

Instalación del MCP

Si el MCP no está disponible, ver [references/install.md](references/install.md) para guiar al usuario paso a paso.