WhatsApp API Multi Device Version

Un servidor de API de WhatsApp multidispositivo para agentes y herramientas de IA.

Documentación

Go WhatsApp — Diseñado para un Uso Eficiente de Memoria

Si estás usando esta herramienta para generar ingresos, considera apoyar su desarrollo convirtiéndote en miembro de Patreon.

Tu apoyo ayuda a garantizar que el proyecto se mantenga actualizado y reciba actualizaciones periódicas.

Soporte para ARM, AMD64 y MCP

Descargas:

Nodo de Comunidad para n8n

Paquete n8n
Ve a Configuración → Nodos de Comunidad, ingresa @aldinokemal2104/n8n-nodes-gowa y selecciona Instalar.

Cambios Importantes

v6
- El modo REST requiere <binary> rest en lugar de <binary>.
  - Ejemplo: ./whatsapp rest en lugar de ./whatsapp.
  - El modo MCP requería <binary> mcp.
  - Ejemplo: ./whatsapp mcp.
v7
- A partir de la versión 7.x, los binarios se compilan con GoReleaser y se pueden descargar desde el último release.
v8
- Soporte multi-dispositivo: Ahora puedes conectar y gestionar múltiples cuentas de WhatsApp simultáneamente en una única instancia del servidor.
  - Nueva API de Gestión de Dispositivos: Nuevos endpoints bajo /devices gestionan múltiples dispositivos.
  - Ámbito de dispositivo requerido: Todas las llamadas a la API REST con ámbito de dispositivo ahora requieren:
  - El encabezado X-Device-Id, o - El parámetro de consulta device_id. - Si solo hay un dispositivo registrado, se usa como predeterminado.
  - Ámbito de dispositivo por WebSocket: Conéctate a /ws?device_id=<id> para limitar la conexión WebSocket a un dispositivo específico.
  - Soporte de UI remota: CORS permite los encabezados Authorization y X-Device-Id, por lo que una interfaz web independiente (por ejemplo, gowa-ui) alojada en otro origen puede llamar a la API directamente. GET /app/info expone la versión y los límites de tamaño de medios. Como los navegadores no pueden establecer encabezados en conexiones WebSocket, pasa /ws?device_id=<id>&authorization=<base64(user:pass)> cuando la Autenticación Básica esté habilitada (usa TLS; la credencial es visible en la URL).
  - Cambios en los payloads de webhooks: Todos los payloads de webhooks ahora incluyen un campo device_id de nivel superior que identifica qué dispositivo recibió el evento:
```
{
  "event": "message",
  "device_id": "628123456789@s.whatsapp.net",
  "payload": { ... }
}
```
v9
- MCP y API están unificados bajo rest: MCP ya no es un modo o proceso separado. Ejecuta ./whatsapp rest para servir tanto la API REST como MCP; MCP está disponible en /mcp (sin subcomando independiente mcp). Consulta Servidor MCP (Model Context Protocol) para detalles de migración.
  - La UI se movió a un repositorio separado: El panel web ya no está incluido en este repositorio. Ahora vive en aldinokemal/gowa-ui y se distribuye como un único gowa-ui.html autocontenido. El servidor descarga la última versión del panel al iniciar, verifica su digest SHA-256, lo almacena en caché bajo storages/ui/ y lo sirve en /. Consulta Panel web (gowa-ui) para la configuración de APP_UI_*, el anclaje de la cadena de suministro y la implementación en entornos aislados.

Características

Envía mensajes de WhatsApp a través de la API HTTP. Consulta docs/openapi.yaml para más detalles.
Soporte de servidor MCP (Model Context Protocol) — Integración con agentes y herramientas de IA mediante un protocolo estandarizado.
OAuth 2.1 MCP opcional — Conecta clientes MCP remotos que no pueden proporcionar un encabezado de Autenticación Básica. Consulta MCP OAuth.
Mencionar usuarios:
- @phoneNumber
  - Ejemplo: Hello @628974812XXXX, @628974812XXXX
Menciones fantasma (mencionar a todos) — Menciona a los participantes del grupo sin mostrar @phone en el texto del mensaje.
- Pasa números de teléfono en el campo mentions para mencionar usuarios sin un @ visible en el mensaje.
  - Usa la palabra clave especial @everyone para mencionar automáticamente a todos los participantes del grupo.
Publicar estados de WhatsApp.
Marcar mensajes de audio entrantes y notas de voz como reproducidos.
Enviar stickers — Convierte automáticamente imágenes al formato WebP para stickers.
- Soporta formatos JPG, JPEG, PNG, WebP y GIF.
  - Redimensiona automáticamente las imágenes a 512×512 píxeles.
  - Preserva la transparencia en imágenes PNG.
  - Los stickers WebP animados son compatibles, pero deben cumplir los requisitos de WhatsApp:
  - Exactamente 512×512 píxeles. - Menos de 500 KB. - No más de 10 segundos de duración. - Si un sticker animado no cumple estos requisitos, rediménsionalo antes de subirlo con una herramienta como ezgif.com.
Comprimir imágenes antes de enviarlas.
Comprimir videos antes de enviarlos.
Personalizar el nombre del sistema operativo que se muestra como nombre del dispositivo vinculado en WhatsApp:
- --os=Chrome o --os=MyApplication
Autenticación Básica con múltiples credenciales:
- --basic-auth=kemal:secret,toni:password,userName:secretPassword
  - Forma corta: -b=kemal:secret,toni:password,userName:secretPassword
Soporte de implementación en subruta:
- --base-path="/gowa" permite la implementación bajo una ruta como /gowa.
Puerto personalizable y modo de depuración:
- --port 8000
  - --debug true
Respuestas automáticas a mensajes entrantes:
- --autoreply="Don't reply to this message"
Marcar automáticamente los mensajes entrantes como leídos:
- --auto-mark-read=true
Descargar automáticamente medios de mensajes entrantes:
- --auto-download-media=false desactiva la descarga automática de medios (predeterminado: true).
Rechazar automáticamente llamadas entrantes:
- --auto-reject-call=true o WHATSAPP_AUTO_REJECT_CALL=true (consulta Webhook Payload para eventos de llamadas).
Presencia configurable al conectar:
- --presence-on-connect=unavailable o WHATSAPP_PRESENCE_ON_CONNECT=unavailable
  - available — Marca la cuenta como en línea (suprime las notificaciones del teléfono).
  - unavailable — Registra el nombre de push sin ponerse en línea (predeterminado; preserva las notificaciones del teléfono).
  - none — Omitir la presencia por completo (el nombre de push no se registra, por lo que los contactos pueden ver - como nombre).
Pulso de presencia diario:
- --presence-pulse-enabled=true o WHATSAPP_PRESENCE_PULSE_ENABLED=true (predeterminado: true).
  - --presence-pulse-interval=24h controla con qué frecuencia se pulsa cada dispositivo conectado.
  - --presence-pulse-duration=5m controla cuánto tiempo permanece la cuenta en available antes de volver a unavailable.
Webhooks para mensajes recibidos y otros eventos:
- --webhook="http://yourwebhook.site/handler"
  - Forma corta: -w="http://yourwebhook.site/handler"
  - Consulta Documentación de Webhook Payload para más detalles.
Webhooks por dispositivo — Cada dispositivo puede tener su propia URL de webhook y filtros de eventos.
- Configurar vía API: PATCH /devices/:device_id/webhook con {"webhook_url": "https://device-webhook.site/handler"}.
  - Obtener vía API: GET /devices/:device_id/webhook.
  - Cuando un dispositivo tiene un webhook personalizado, los eventos de ese dispositivo se envían a la URL específica del dispositivo.
  - Cuando no se establece un webhook de dispositivo, los eventos recurren al webhook global (--webhook).
  - Establece webhook_url a una cadena vacía con PATCH para limpiarlo y usar el webhook global.
Firmas de webhook — Las solicitudes de webhook incluyen una firma HMAC-SHA-256 en el encabezado X-Hub-Signature-256, generada con la clave predeterminada secret. Cambia la clave con:
- --webhook-secret="secret"
Documentación de webhook payload — Para esquemas detallados, implementación de seguridad y ejemplos de integración, consulta Documentación de Webhook Payload.
Filtrado de eventos de webhook — Filtra qué eventos se reenvían a tu webhook con:
- --webhook-events="message,message.ack" (una lista separada por comas), o
  - WHATSAPP_WEBHOOK_EVENTS=message,message.ack. Eventos de Webhook Disponibles: | Evento | Descripción | | --- | --- | | message | Mensajes de texto, medios, contactos, ubicación | | message.reaction | Reacciones de emoji a mensajes | | message.revoked | Mensajes eliminados/revocados | | message.edited | Mensajes editados | | message.ack | Recibos de entrega y lectura | | message.deleted | Mensajes eliminados para el usuario | | chat_presence | Indicadores de escritura y grabación de contactos | | group.participants | Eventos de unión/salida/promoción/degradación de miembros del grupo | | group.joined | Fuiste agregado a un grupo | | label.edit | Metadatos de etiquetas de WhatsApp cambiados | | label.association | Etiqueta aplicada o eliminada de un chat | | newsletter.joined | Te suscribiste a un boletín/canal | | newsletter.left | Te desuscribiste de un boletín | | newsletter.message | Nuevo(s) mensaje(s) publicado(s) en un boletín | | newsletter.mute | Configuración de silencio del boletín cambiada | | call.offer | Llamada entrante recibida | Si esta configuración está vacía, se reenvían todos los eventos.
Filtrado de JID de webhook Puedes omitir eventos para chats o remitentes específicos (por ejemplo, silenciar todos los grupos) antes de que se reenvíen:
- --webhook-ignore-jids="@g.us,628123456789@s.whatsapp.net" (una lista separada por comas), o
  - WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us.
  - Soporta los comodines @g.us / @s.whatsapp.net / @lid (coinciden con un espacio de direcciones completo) y JIDs exactos.
  - Esto filtra por conversación o remitente y es independiente de --webhook-events, que filtra por tipo de evento. La integración con Chatwoot tiene una configuración separada CHATWOOT_IGNORE_JIDS.
Configuración TLS de webhook Si encuentras errores de verificación de certificados TLS al usar webhooks (por ejemplo, con túneles de Cloudflare o certificados autofirmados):
```
tls: failed to verify certificate: x509: certificate signed by unknown authority
```
Puedes desactivar la verificación de certificados TLS con:
- --webhook-insecure-skip-verify=true, o
  - WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true. Advertencia de Seguridad: Esta opción desactiva la verificación de certificados TLS y solo debe usarse en:
- Entornos de desarrollo o pruebas.
  - Túneles de Cloudflare, que proporcionan su propia capa de seguridad.
  - Redes internas con certificados autofirmados. Para entornos de producción, usa un certificado TLS válido (por ejemplo, de Let's Encrypt) en lugar de desactivar la verificación.

Configuración

La configuración se carga en este orden de prioridad:

Banderas de línea de comandos (mayor prioridad)
Variables de entorno
Archivo .env (menor prioridad)

Variables de Entorno

Para usar variables de entorno:

Desde la raíz del repositorio, copia el archivo de ejemplo: cp src/.env.example src/.env.
Actualiza los valores en src/.env según sea necesario.
Alternativamente, establece las mismas variables en el entorno del proceso.

Variables de Entorno Disponibles

Variable	Descripción	Predeterminado	Ejemplo
`APP_PORT`	Puerto de la aplicación	`3000`	`APP_PORT=8080`
`APP_HOST`	Dirección del host para vincular el servidor	`0.0.0.0`	`APP_HOST=127.0.0.1`
`APP_DEBUG`	Habilitar registro de depuración	`false`	`APP_DEBUG=true`
`APP_OS`	Nombre del sistema operativo (nombre del dispositivo en WhatsApp)	`GOWA`	`APP_OS=MyApp`
`APP_BASIC_AUTH`	Credenciales de autenticación básica	-	`APP_BASIC_AUTH=user1:pass1,user2:pass2`
`APP_BASE_PATH`	Ruta base para implementación en subruta	-	`APP_BASE_PATH=/gowa`
`APP_TRUSTED_PROXIES`	Rangos de IP de proxy de confianza para proxy inverso	-	`APP_TRUSTED_PROXIES=0.0.0.0/0`
`APP_CORS_ALLOWED_ORIGINS`	Orígenes CORS permitidos (cualquier origen cuando está vacío)	-	`APP_CORS_ALLOWED_ORIGINS=https://ui.example.com`
`APP_UI_ENABLED`	Servir el panel gowa-ui descargado	`true`	`APP_UI_ENABLED=false`
`APP_UI_AUTO_UPDATE`	Descargar y actualizar periódicamente el panel más reciente	`true`	`APP_UI_AUTO_UPDATE=false`
`APP_UI_REPO`	Repositorio de GitHub que contiene las versiones de gowa-ui	`aldinokemal/gowa-ui`	`APP_UI_REPO=my-org/gowa-ui`
`APP_UI_ASSET_NAME`	Nombre del archivo del recurso de la versión del panel	`gowa-ui.html`	`APP_UI_ASSET_NAME=gowa-ui.html`
`APP_UI_UPDATE_INTERVAL`	Intervalo entre comprobaciones de actualización del panel	`3h`	`APP_UI_UPDATE_INTERVAL=6h`
`APP_UI_GITHUB_TOKEN`	Token de GitHub opcional para un límite de API más alto	-	`APP_UI_GITHUB_TOKEN=github_pat_xxx`
`APP_UI_ASSET_SHA256`	Pin SHA-256 opcional para el recurso del panel	-	`APP_UI_ASSET_SHA256=<hex-digest>`
`MCP_ENABLED`	Servir el endpoint MCP HTTP transmisible en `/mcp`	`true`	`MCP_ENABLED=false`
`MCP_OAUTH_ENABLED`	Habilitar autenticación OAuth 2.1 para MCP	`false`	`MCP_OAUTH_ENABLED=true`
`MCP_OAUTH_ISSUER_URL`	URL pública del emisor HTTPS de OAuth	-	`MCP_OAUTH_ISSUER_URL=https://gowa.example.com`
`MCP_OAUTH_RESOURCE_URL`	URL pública canónica opcional de MCP	Derivado del emisor y la ruta base	`MCP_OAUTH_RESOURCE_URL=https://gowa.example.com/mcp`
`MCP_OAUTH_DB_URI`	URI SQLite para clientes OAuth, códigos y hashes de tokens	`file:storages/oauth.db`	`MCP_OAUTH_DB_URI=file:storages/oauth.db`
`DB_URI`	URI de conexión a la base de datos	`file:storages/whatsapp.db`	`DB_URI=postgres://user:pass@host/db`
`DB_KEYS_URI`	URI de base de datos opcional para caché de claves de cifrado/sesión. Déjelo en blanco para usar `DB_URI`; evite almacenamiento en memoria en producción porque los reinicios pueden perder el estado de la sesión de WhatsApp.	-	`DB_KEYS_URI=file:storages/whatsapp-keys.db?_foreign_keys=on`
`CHAT_STORAGE_MAX_OPEN_CONNS`	Conexiones SQLite concurrentes máximas para almacenamiento de chats	`5`	`CHAT_STORAGE_MAX_OPEN_CONNS=10`
`WHATSAPP_AUTO_REPLY`	Mensaje de respuesta automática	-	`WHATSAPP_AUTO_REPLY="Auto reply message"`
`WHATSAPP_AUTO_MARK_READ`	Marcar automáticamente los mensajes entrantes como leídos	`false`	`WHATSAPP_AUTO_MARK_READ=true`
`WHATSAPP_AUTO_DOWNLOAD_MEDIA`	Descargar automáticamente medios de mensajes entrantes	`true`	`WHATSAPP_AUTO_DOWNLOAD_MEDIA=false`
`WHATSAPP_AUTO_REJECT_CALL`	Rechazar automáticamente llamadas entrantes de WhatsApp	`false`	`WHATSAPP_AUTO_REJECT_CALL=true`
`WHATSAPP_WEBHOOK`	URL(s) de webhook para eventos (separadas por comas)	-	`WHATSAPP_WEBHOOK=https://webhook.site/xxx`
`WHATSAPP_WEBHOOK_SECRET`	Secreto del webhook para validación	`secret`	`WHATSAPP_WEBHOOK_SECRET=super-secret-key`
`WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY`	Omitir verificación TLS para webhooks (inseguro)	`false`	`WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true`
`WHATSAPP_WEBHOOK_EVENTS`	Lista blanca de eventos a reenviar (separados por comas, vacío = todos)	-	`WHATSAPP_WEBHOOK_EVENTS=message,message.ack`
`WHATSAPP_WEBHOOK_IGNORE_JIDS`	JIDs/comodines a omitir al reenviar (separados por comas)	-	`WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us`
`WHATSAPP_ACCOUNT_VALIDATION`	Habilitar validación de cuenta	`true`	`WHATSAPP_ACCOUNT_VALIDATION=false`
`WHATSAPP_PRESENCE_ON_CONNECT`	Presencia al conectar: `available`, `unavailable` o `none`	`unavailable`	`WHATSAPP_PRESENCE_ON_CONNECT=unavailable`
`WHATSAPP_PROXY`	Proxy de salida para el WebSocket de WhatsApp (SOCKS5/HTTP/HTTPS)	-	`WHATSAPP_PROXY=socks5://user:pass@host:1080`
`WHATSAPP_PRESENCE_PULSE_ENABLED`	Habilitar pulso diario de presencia disponible/no disponible	`true`	`WHATSAPP_PRESENCE_PULSE_ENABLED=false`
`WHATSAPP_PRESENCE_PULSE_INTERVAL`	Intervalo entre pulsos de presencia	`24h`	`WHATSAPP_PRESENCE_PULSE_INTERVAL=24h`
`WHATSAPP_PRESENCE_PULSE_DURATION`	Duración para permanecer disponible durante cada pulso	`5m`	`WHATSAPP_PRESENCE_PULSE_DURATION=5m`
`CHATWOOT_ENABLED`	Habilitar integración con Chatwoot	`false`	`CHATWOOT_ENABLED=true`
`CHATWOOT_URL`	URL de la instancia de Chatwoot	-	`CHATWOOT_URL=https://app.chatwoot.com`
`CHATWOOT_API_TOKEN`	Token de acceso a la API de Chatwoot	-	`CHATWOOT_API_TOKEN=your-api-token`
`CHATWOOT_ACCOUNT_ID`	ID de cuenta de Chatwoot	-	`CHATWOOT_ACCOUNT_ID=12345`
`CHATWOOT_INBOX_ID`	ID de bandeja de entrada de Chatwoot	-	`CHATWOOT_INBOX_ID=67890`
`CHATWOOT_DEVICE_ID`	ID de dispositivo de WhatsApp para Chatwoot (dispositivo único/entorno de respaldo)	-	`CHATWOOT_DEVICE_ID=628xxx@s.whatsapp.net`
`CHATWOOT_ALLOWED_HOSTS`	Lista blanca de hosts de Chatwoot para configuraciones por dispositivo (protección SSRF)	-	`CHATWOOT_ALLOWED_HOSTS=app.chatwoot.com,chat.example.com`
`CHATWOOT_IMPORT_MESSAGES`	Habilitar sincronización del historial de mensajes con Chatwoot	`false`	`CHATWOOT_IMPORT_MESSAGES=true`
`CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES`	Días de historial a importar	`3`	`CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES=7`
`CHATWOOT_IMPORT_DB_URI`	URI PostgreSQL directa de Chatwoot para sincronización de historial	-	`CHATWOOT_IMPORT_DB_URI=postgresql://user:pass@host:5432/chatwoot_production?sslmode=disable`
`CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE`	Insertar marcadores de posición de texto para filas de medios durante importación directa a BD	`true`	`CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE=true`
`CHATWOOT_IMPORT_MEDIA_WITH_REST`	Subir filas de medios de importación directa a BD mediante REST de Chatwoot	`false`	`CHATWOOT_IMPORT_MEDIA_WITH_REST=true`
`CHATWOOT_AUTO_CREATE`	Crear automáticamente o reutilizar la bandeja de entrada de la API de Chatwoot al inicio	`false`	`CHATWOOT_AUTO_CREATE=true`
`CHATWOOT_INBOX_NAME`	Nombre de bandeja de entrada usado cuando la creación automática está habilitada	`WhatsApp`	`CHATWOOT_INBOX_NAME=WhatsApp Support`
`CHATWOOT_WEBHOOK_URL`	URL pública del webhook de respuesta de GOWA Chatwoot	-	`CHATWOOT_WEBHOOK_URL=https://api.example.com/chatwoot/webhook?secret=shared`
`CHATWOOT_WEBHOOK_SECRET`	Secreto compartido requerido para webhooks entrantes de Chatwoot	-	`CHATWOOT_WEBHOOK_SECRET=shared`
`CHATWOOT_REOPEN_CONVERSATION`	Reabrir conversaciones resueltas de Chatwoot para contactos que regresan	`true`	`CHATWOOT_REOPEN_CONVERSATION=false`
`CHATWOOT_CONVERSATION_PENDING`	Crear nuevas conversaciones de Chatwoot como pendientes	`false`	`CHATWOOT_CONVERSATION_PENDING=true`
`CHATWOOT_IGNORE_JIDS`	JIDs o comodines a excluir del reenvío de Chatwoot	-	`CHATWOOT_IGNORE_JIDS=@g.us,628123@s.whatsapp.net`
`CHATWOOT_SIGN_MSG`	Prefijar respuestas de agentes de Chatwoot con el nombre del agente	`false`	`CHATWOOT_SIGN_MSG=true`
`CHATWOOT_SIGN_DELIMITER`	Delimitador entre la firma del agente de Chatwoot y el cuerpo del mensaje	`\n\n`	`CHATWOOT_SIGN_DELIMITER=" - "`
`CHATWOOT_FORWARD_EDITS`	Reflejar ediciones de WhatsApp en notas con hilo de Chatwoot	`true`	`CHATWOOT_FORWARD_EDITS=false`
`CHATWOOT_FORWARD_DELETES`	Reflejar eventos de eliminación para todos de WhatsApp en notas de Chatwoot	`true`	`CHATWOOT_FORWARD_DELETES=false`
`CHATWOOT_MESSAGE_READ`	Sincronizar estado de lectura para mensajes vinculados de WhatsApp/Chatwoot	`false`	`CHATWOOT_MESSAGE_READ=true`
`CHATWOOT_MESSAGE_DELETE`	Eliminar mensajes vinculados del lado opuesto cuando se reporta eliminación	`false`	`CHATWOOT_MESSAGE_DELETE=true`

Documentación:

Para esquemas detallados de cargas útiles de webhook, implementación de seguridad y ejemplos de integración, consulte Documentación de cargas útiles de webhook.
Para la guía completa de integración con Chatwoot, consulte Documentación de integración con Chatwoot.
Para detalles de implementación y seguridad de OAuth, consulte MCP OAuth.

Ejecute ./whatsapp --help para ver todas las banderas de línea de comandos.

Requisitos

Requisitos del sistema

Go 1.26.0 o posterior (al compilar desde el código fuente)
FFmpeg (para procesamiento de medios)

Plataformas compatibles

Linux (x86_64, ARM64)
macOS (Intel, Apple Silicon)
Windows (x86_64; se recomienda WSL)

Dependencias (sin Docker)

macOS:
- brew install ffmpeg webp
  - export CGO_CFLAGS_ALLOW="-Xpreprocessor"
Linux:
- sudo apt update
  - sudo apt install ffmpeg webp
Windows (se recomienda WSL; consulte Instalar WSL):
- Instale FFmpeg.
  - Instale libwebp, luego extráigalo y agregue su directorio bin a PATH.

Nota: El paquete webp proporciona las herramientas cwebp (codificador), dwebp (decodificador) y webpmux (extractor de fotogramas). FFmpeg es necesario para el procesamiento de medios. Las herramientas libwebp (webpmux + dwebp) se usan para soporte de stickers WebP animados.

Cómo usar

Básico

Clone el repositorio: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.
Abra el directorio clonado en una terminal.
Ejecute cd src.
Ejecute go run . rest.
Abra http://localhost:3000.

Docker

Docker evita la necesidad de instalar Go, FFmpeg y libwebp directamente en el host.

Clone el repositorio: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.
Abra el directorio clonado en una terminal.
Copie el archivo de entorno: cp src/.env.example src/.env.
Ejecute docker compose up -d --build.
Abra http://localhost:3000.

Compile su propio binario

Clone el repositorio: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.
Abra el directorio clonado en una terminal.
Ejecute cd src.
Compile el binario:
- Linux y macOS: go build -o whatsapp
  - Windows (Símbolo del sistema o PowerShell): go build -o whatsapp.exe
Inicie el servidor:
- Linux y macOS: ./whatsapp rest
  - Windows: .\whatsapp.exe rest
Abra http://localhost:3000 en un navegador.

Ejecute ./whatsapp --help (o .\whatsapp.exe --help en Windows) para ver todas las banderas.

Compilación cruzada para Raspberry Pi (ARM)

Para compilar para una Raspberry Pi u otro dispositivo ARM sin un conjunto de herramientas C (CGO), use la etiqueta de compilación purego. Esto selecciona una implementación SQLite pura en Go.

Clone el repositorio: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.
Abra el directorio clonado en una terminal.
Ejecute cd src.

Compile para Raspberry Pi Zero / 1 (ARMv6):

CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -tags purego -o whatsapp-armv6

Compile para Raspberry Pi 2 / 3 / 4 (ARMv7 de 32 bits):

CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -tags purego -o whatsapp-armv7

Transfiera el binario a su Pi, otórguele permiso de ejecución (chmod +x) y ejecútelo:
- Si compiló ARMv6: ./whatsapp-armv6 rest
  - Si compiló ARMv7: ./whatsapp-armv7 rest

Servidor MCP (Protocolo de Contexto de Modelo)

MCP no es un modo o proceso separado: lo sirve el propio servidor REST. Siempre que ./whatsapp rest esté en ejecución, el endpoint MCP está disponible en http://<host>:<port><base-path>/mcp (predeterminado http://localhost:3000/mcp) usando el transporte HTTP transmisible. Desactívelo con MCP_ENABLED=false o --mcp-enabled=false (predeterminado: habilitado).

Herramientas MCP disponibles

Hay cinco herramientas consolidadas; los agentes eligen el comportamiento mediante un argumento type / action en lugar de una herramienta por operación:

Herramienta	Valores de `type` / `action`
`whatsapp_send`	`text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward`
`whatsapp_message`	`react`, `edit`, `revoke`, `delete`, `mark_read`, `mark_played`, `star`, `unstar`, `download_media`
`whatsapp_chat`	`list_chats`, `list_contacts`, `get_messages`, `archive`
`whatsapp_group`	`create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests`
`whatsapp_app`	`status`, `login_qr`, `login_code`, `logout`, `reconnect`

Selección de dispositivo

Para implementaciones de múltiples dispositivos, el encabezado X-Device-Id en la conexión del cliente MCP selecciona el dispositivo usado por cada llamada de herramienta en esa conexión. Si se omite, se recurre al dispositivo predeterminado, igual que con REST. Cualquier llamada individual puede anularlo con un argumento opcional device_id.

Configuración de MCP

Apunte su cliente MCP al endpoint /mcp. Hereda la autenticación básica del servidor REST, así que incluya el mismo encabezado Authorization que usan sus llamadas REST:

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic dXNlcjpzZWNyZXQ=",
        "X-Device-Id": "628123456789"
      }
    }
  }
}

headers es opcional: incluya Authorization solo cuando la autenticación básica esté configurada, y X-Device-Id solo para configuraciones de múltiples dispositivos.

OAuth para clientes MCP remotos

OAuth 2.1 está disponible para clientes remotos que no pueden adjuntar un encabezado de autenticación básica. Está deshabilitado por predeterminado. Una configuración mínima es:

APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com

Cuando OAuth está habilitado, /mcp acepta un token Bearer o las credenciales Basic Auth configuradas. OAuth no autentica rutas REST ni de interfaz de usuario. Consulta MCP OAuth para la configuración del cliente, requisitos de proxy inverso, comportamiento de subrutas y el modelo de seguridad.

Migración desde el modo MCP independiente

./whatsapp mcp → ./whatsapp rest (MCP ahora se incluye automáticamente).
http://localhost:8080/sse → http://localhost:3000/mcp.
40 herramientas granulares → 5 herramientas consolidadas (los agentes eligen acciones mediante el campo type / action).

Servidor REST de producción (Docker)

Usando Docker Hub:

docker volume create whatsapp-storages
docker volume create whatsapp-statics
docker run --detach \
  --publish 3000:3000 \
  --name whatsapp \
  --restart always \
  --volume whatsapp-storages:/app/storages \
  --volume whatsapp-statics:/app/statics \
  aldinokemal2104/go-whatsapp-web-multidevice \
  rest --autoreply="Don't reply to this message, please"

Usando GitHub Container Registry:

docker volume create whatsapp-storages
docker volume create whatsapp-statics
docker run --detach \
  --publish 3000:3000 \
  --name whatsapp \
  --restart always \
  --volume whatsapp-storages:/app/storages \
  --volume whatsapp-statics:/app/statics \
  ghcr.io/aldinokemal/go-whatsapp-web-multidevice \
  rest --autoreply="Don't reply to this message, please"

Servidor REST de producción (Docker Compose)

Crea un archivo docker-compose.yml con una de las siguientes configuraciones.

Usando Docker Hub:

services:
  whatsapp:
    image: aldinokemal2104/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Usando GitHub Container Registry:

services:
  whatsapp:
    image: ghcr.io/aldinokemal/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Usando variables de entorno con Docker Hub:

services:
  whatsapp:
    image: aldinokemal2104/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - WHATSAPP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Usando variables de entorno con GitHub Container Registry:

services:
  whatsapp:
    image: ghcr.io/aldinokemal/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - WHATSAPP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Inicia la pila seleccionada con docker compose up -d.

Servidor de producción (Binario)

Descarga un binario desde la página de versiones y luego ejecútalo con el subcomando rest.

También puedes bifurcar o modificar el código fuente.

API actual

API MCP (Model Context Protocol)

Se sirve en /mcp por el servidor REST usando HTTP transmisible cuando MCP_ENABLED es verdadero. Con APP_BASE_PATH configurado, la ruta es <base-path>/mcp.
Las herramientas disponibles se enumeran en la sección "Herramientas MCP disponibles" anterior.
Compatible con herramientas y agentes de IA habilitados para MCP.

API REST HTTP

Consulta docs/openapi.yaml para especificaciones detalladas de la API.
Usa Swagger Editor para visualizar la API.
Genera clientes HTTP usando openapi-generator.

Estado	Operación	Método	URL
✅	Verificación de salud	GET	/health
✅	Listar dispositivos	GET	/devices
✅	Agregar dispositivo	POST	/devices
✅	Obtener información del dispositivo	GET	/devices/:device_id
✅	Eliminar dispositivo	DELETE	/devices/:device_id
✅	Iniciar sesión del dispositivo (QR)	GET	/devices/:device_id/login
✅	Iniciar sesión del dispositivo (Código)	POST	/devices/:device_id/login/code
✅	Cerrar sesión del dispositivo	POST	/devices/:device_id/logout
✅	Reconectar dispositivo	POST	/devices/:device_id/reconnect
✅	Obtener estado del dispositivo	GET	/devices/:device_id/status
✅	Obtener webhook del dispositivo	GET	/devices/:device_id/webhook
✅	Configurar webhook del dispositivo	PATCH	/devices/:device_id/webhook
✅	Iniciar sesión con código QR	GET	/app/login
✅	Iniciar sesión con código de emparejamiento	GET	/app/login-with-code
✅	Estado de emparejamiento Passkey	GET	/app/passkey
✅	Respuesta de emparejamiento Passkey	POST	/app/passkey/response
✅	Confirmar emparejamiento Passkey	POST	/app/passkey/confirm
✅	Cerrar sesión	GET	/app/logout
✅	Reconectar	GET	/app/reconnect
✅	Dispositivos	GET	/app/devices
✅	Estado de conexión	GET	/app/status
✅	Información de la aplicación (versión, límites)	GET	/app/info
✅	Información del usuario	GET	/user/info
✅	Avatar del usuario	GET	/user/avatar
✅	Cambiar avatar del usuario	POST	/user/avatar
✅	Cambiar nombre de push del usuario	POST	/user/pushname
✅	Listar mis grupos*	GET	/user/my/groups
✅	Listar mis newsletters	GET	/user/my/newsletters
✅	Obtener mi configuración de privacidad	GET	/user/my/privacy
✅	Listar mis contactos	GET	/user/my/contacts
✅	Verificar usuario de WhatsApp	GET	/user/check
✅	Obtener perfil de negocio	GET	/user/business-profile
✅	Enviar mensaje	POST	/send/message
✅	Enviar imagen	POST	/send/image
✅	Enviar audio	POST	/send/audio
✅	Enviar archivo	POST	/send/file
✅	Enviar video	POST	/send/video
✅	Enviar sticker	POST	/send/sticker
✅	Enviar contacto	POST	/send/contact
✅	Enviar enlace	POST	/send/link
✅	Enviar ubicación	POST	/send/location
✅	Enviar encuesta / voto	POST	/send/poll
✅	Enviar presencia	POST	/send/presence
✅	Enviar presencia de chat (indicador de escritura)	POST	/send/chat-presence
✅	Revocar mensaje	POST	/message/:message_id/revoke
✅	Reaccionar a mensaje	POST	/message/:message_id/reaction
✅	Eliminar mensaje	POST	/message/:message_id/delete
✅	Editar mensaje	POST	/message/:message_id/update
✅	Marcar mensaje como leído	POST	/message/:message_id/read
✅	Marcar mensaje de audio como reproducido	POST	/message/:message_id/played
✅	Destacar mensaje	POST	/message/:message_id/star
✅	Quitar destacado de mensaje	POST	/message/:message_id/unstar
✅	Reenviar mensaje	POST	/message/:message_id/forward
✅	Descargar medios del mensaje	GET	/message/:message_id/download
✅	Rechazar llamada	POST	/call/reject
✅	Unirse a grupo con enlace	POST	/group/join-with-link
✅	Obtener información del grupo desde enlace	GET	/group/info-from-link
✅	Obtener información del grupo	GET	/group/info
✅	Salir del grupo	POST	/group/leave
✅	Crear grupo	POST	/group
✅	Listar participantes del grupo	GET	/group/participants
✅	Agregar participantes al grupo	POST	/group/participants
✅	Eliminar participantes del grupo	POST	/group/participants/remove
✅	Ascender participantes del grupo	POST	/group/participants/promote
✅	Descender participantes del grupo	POST	/group/participants/demote
✅	Exportar participantes del grupo (CSV)	GET	/group/participants/export
✅	Listar solicitudes de unión al grupo	GET	/group/participant-requests
✅	Aprobar solicitudes de unión al grupo	POST	/group/participant-requests/approve
✅	Rechazar solicitudes de unión al grupo	POST	/group/participant-requests/reject
✅	Configurar foto del grupo	POST	/group/photo
✅	Configurar nombre del grupo	POST	/group/name
✅	Bloquear o desbloquear configuración del grupo	POST	/group/locked
✅	Configurar modo de anuncios del grupo	POST	/group/announce
✅	Configurar tema del grupo	POST	/group/topic
✅	Obtener enlace de invitación del grupo	GET	/group/invite-link
✅	Dejar de seguir newsletter	POST	/newsletter/unfollow
✅	Obtener mensajes del newsletter	GET	/newsletter/messages
✅	Obtener lista de chats	GET	/chats
✅	Obtener mensajes del chat	GET	/chat/:chat_jid/messages
✅	Fijar chat	POST	/chat/:chat_jid/pin
✅	Archivar chat	POST	/chat/:chat_jid/archive
✅	Configurar mensajes temporales	POST	/chat/:chat_jid/disappearing
✅	Sincronizar historial de Chatwoot	POST	/chatwoot/sync
✅	Estado de sincronización de Chatwoot	GET	/chatwoot/sync/status
✅	Listar configuraciones de Chatwoot	GET	/chatwoot/configs
✅	Obtener configuración de Chatwoot del dispositivo	GET	/devices/:device_id/chatwoot/config
✅	Configurar Chatwoot del dispositivo	PUT	/devices/:device_id/chatwoot/config
✅	Eliminar configuración de Chatwoot del dispositivo	DELETE	/devices/:device_id/chatwoot/config
✅	Webhook de respuesta de Chatwoot	POST	/chatwoot/webhook
✅	Webhook de respuesta de Chatwoot del dispositivo	POST	/chatwoot/webhook/:device_id

✅ = disponible. * = tiene limitaciones conocidas; consulta las notas a continuación.

Notas:

*List My Groups: Devuelve un máximo de 500 grupos debido a una limitación del protocolo de WhatsApp. Los servidores de WhatsApp, no esta API, imponen el límite. Consulta el código fuente de whatsmeow para más detalles.
/health es público y siempre se registra en la ruta raíz, incluso cuando APP_BASE_PATH está configurado.
Las rutas de Chatwoot se registran solo cuando CHATWOOT_ENABLED=true.

Interfaz de usuario

Interfaz MCP

Configurar MCP (probado en Cursor)
Probar MCP
Configuración MCP exitosa

Panel web (gowa-ui)

El panel vive en su propio repositorio: aldinokemal/gowa-ui. Cada versión de gowa-ui publica un único gowa-ui.html autocontenido; el servidor descarga la última versión al inicio (y cada APP_UI_UPDATE_INTERVAL, que por defecto es 3h), verifica su digesto SHA-256, lo almacena en caché bajo storages/ui/, y lo sirve en / detrás de Basic Auth.

Configuración	Predeterminado	Propósito
`APP_UI_ENABLED`	`true`	Servir el panel en `/`; `false` devuelve un banner JSON (solo API)
`APP_UI_AUTO_UPDATE`	`true`	Descargar/actualizar desde GitHub; deshabilitar para implementaciones aisladas
`APP_UI_REPO`	`aldinokemal/gowa-ui`	Repositorio que sigue el actualizador—siempre su última versión, no un pin de versión
`APP_UI_ASSET_NAME`	`gowa-ui.html`	Nombre del archivo de la versión a descargar
`APP_UI_UPDATE_INTERVAL`	`3h`	Con qué frecuencia verificar `releases/latest`
`APP_UI_GITHUB_TOKEN`	(vacío)	Token opcional para aumentar el límite de tasa de la API de GitHub
`APP_UI_ASSET_SHA256`	(vacío)	Pin de cadena de suministro: rechazar cualquier panel cuyo SHA-256 difiera

Modelo de confianza: el digesto de la versión prueba que la descarga coincide con lo que GitHub anuncia, no quién lo publicó. Los operadores que auditan una compilación específica pueden fijarla con APP_UI_ASSET_SHA256 (cada versión incluye un activo .sha256—esta es la única configuración que fija una compilación exacta), apuntar APP_UI_REPO a un fork que controlen (el actualizador aún sigue la última versión de ese repositorio), o precargar la caché y deshabilitar la actualización automática por completo.

Servidores aislados: coloca un gowa-ui.html descargado en storages/ui/index.html y configura APP_UI_AUTO_UPDATE=false. El panel también puede autoalojarse en cualquier lugar estático y apuntarse a la URL de este servidor (consulta el README de gowa-ui).

Nota para macOS

Si ves invalid flag in pkg-config --cflags: -Xpreprocessor, ejecuta:

export CGO_CFLAGS_ALLOW="-Xpreprocessor"

Importante

Este proyecto no es oficial y no está afiliado a WhatsApp.
Usa la Plataforma de Negocios oficial de WhatsApp cuando necesites una integración compatible y de grado de producción.