Saltar al contenido principal
GOWA sirve un Protocolo de Contexto del Modelo endpoint del mismo proceso que la API REST. Cualquier cliente MCP que soporte el transporte streamable HTTP puede enviar mensajes, leer chats y administrar grupos a través de él.
  • URL: http://<host>:3000<APP_BASE_PATH>/mcp (por defecto http://localhost:3000/mcp)
  • Activado por defecto. Deshabilita con MCP_ENABLED=false o --mcp-enabled=false.
  • Sin estado: no hay sacudidas de mano de sesión para mantener vivo entre llamadas.
¿Vas a actualizar desde una versión anterior? El comando independiente ./whatsapp mcp y su endpoint SSE en el puerto 8080 (/sse) ya no están disponibles. Ejecuta ./whatsapp rest y configura los clientes para que apunten a /mcp. El antiguo conjunto de una herramienta por operación se ha sustituido por las herramientas consolidadas que se muestran a continuación.

Conectar un cliente

/mcp se sienta detrás de la misma Auth Básica que la API REST. Envía la cabecera Authorization, más X-Device-Id si ejecutas más de un dispositivo:
YWRtaW46Y2hhbmdlbWU= es base64("admin:changeme"); genera el tuyo con echo -n 'user:pass' | base64. Omita Authorization si Basic Auth está apagado, y X-Device-Id si sólo hay un dispositivo. El formato de configuración exacto depende del cliente. Si un cliente sólo puede lanzar servidores stdio, use un puente como mcp-remote.

Herramientas

GOWA expone siete herramientas. Cada una acepta un argumento type (para enviar) o action (para todas las demás operaciones) que selecciona la operación. Notas sobre argumentos:
  • whatsapp_send siempre necesita type y phone. Los medios son enviados sólo por URL (image_url, video_url, audio_url, file_url, sticker_url); MCP no puede subir archivos locales. link necesita link y caption; forward necesita message_id.
  • whatsapp_send acepta los campos de programación (scheduled_at, timezone, recurrence, weekdays, day_of_month, end_at, occurrence_limit). Administra el resultado con whatsapp_schedule (get, pause, resume y cancel necesitan schedule_id).
  • whatsapp_message necesita phone (el chat) y message_id; edit también necesita message.
  • En GOWA main después de v9.9.0, whatsapp_message con action: "edit" acepta media_type: "image" o media_type: "document" para reemplazar un título. Coincide con el tipo de medio original y omite el link. Vea Editar un subtítulo.
  • whatsapp_chat: get_messages necesita chat_jid; archive necesita chat_jid y archived.
  • whatsapp_app: login_code necesita phone.
Los botones experimentales, la solicitud de ubicación y los envíos de carrusel solo están disponibles a través de REST. Ver mensajes interactivos. Herramientas de boletines de soporte para descubrimiento de canales, contadores de historial y suscripciones de actualización en vivo automáticamente renovadas. Ver newsletters. Las descargas de URL multimedia aplican las mismas comprobaciones de dirección pública que REST envía y conecta directamente sin HTTP_PROXY o HTTPS_PROXY. Las subidas desde archivos locales requieren la API REST. Su cliente MCP muestra el esquema de entrada completo de cada herramienta. El endpoint HTTP acepta POST y DELETE. GET SSE streaming está deshabilitado.

Selección de dispositivo

Cada llamada resuelve su dispositivo en este orden:
  1. El argumento device_id en la llamada de herramienta.
  2. La cabecera X-Device-Id en la conexión MCP.
  3. El único dispositivo registrado, cuando existe exactamente.
De lo contrario, la llamada falla con device identification required: set the X-Device-Id header or pass device_id. Vea Multi-device.

Clientes remotos con OAuth

Clientes alojados como Claude custom connectors no pueden conectar un encabezado Basic Auth. Para ellos, GOWA puede ejecutar un servidor de autorización OAuth 2.1 para /mcp. Está desactivado por defecto.
Requisitos y comportamiento:
  • Debe establecerse APP_BASIC_AUTH: la página de autorización firma a los usuarios con esas mismas cuentas. El inicio falla sin él.
  • Emisor y recurso deben ser las URL HTTPS públicas que ven los clientes, no direcciones internas como http://gowa:3000.
  • Con OAuth encendido, /mcp acepta un token Bearer o Basic Auth. No se aceptan fichas en rutas REST o UI.
  • Los clientes se registran a sí mismos (RFC 7591 registro dinámico de clientes), los cuerpos de registro están limitados a 16 KiB y cada URI de redirección a 2 KiB. Los registros están limitados a 40 por hora y 1.000 clientes almacenados; los no utilizados se podan después de 24 horas.
  • PKCE S256 es obligatorio. Los códigos expiran después de 5 minutos, los tokens de acceso después de 1 hora; actualizan los tokens de rotación y reutilizan un antiguo revoca toda la familia de token. Solo se almacenan hash SHA-256 de tokens, en MCP_OAUTH_DB_URI (por defecto file:storages/oauth.db).
Las URIs de redirección deben coincidir exactamente con los valores registrados. Los clientes nativos pueden usar callbacks IP de bucle HTTP con un puerto dinámico. Las callbacks localhost requieren un puerto explícito y una coincidencia exacta. Otras redirecciones requieren HTTPS. El OAuth resource está vinculado a la URL canónica MCP; las peticiones de token pueden omitirlo, pero un valor proporcionado debe coincidir. Las respuestas de autorización exitosas incluyen iss. Los códigos y tokens caducados son podados durante las escrituras de OAuth. Los hasacks rotados de refresco siguen siendo necesarios para detectar la repetición contra una familia en vivo, para como máximo una vida útil de 30 días más. La eliminación o sustitución de la base de datos OAuth invalida a los clientes y becas existentes. Endpoints, en relación al emisor: /oauth/authorize, /oauth/token, /oauth/register. Discovery metadata uses path-insertion known URLs at the domain root so with APP_BASE_PATH=/gowa your proxy must route:
Comprobar descubrimiento desde fuera:
Luego añade https://gowa.example.com/mcp como un conector personalizado e inicia sesión con una cuenta APP_BASIC_AUTH.
Asegúrate de que Cloudflare Access, desafíos de bot o proxies de autenticación delante de GOWA no intercepte las rutas bien conocidas, /oauth/* o /mcp. Fallo al iniciar sesión en /oauth/authorize en tu proxy.