- Acceso API: quién puede llamar a GOWA. Esta es HTTP Basic Auth.
- Emparejamiento de WhatsApp: enlaza una cuenta de WhatsApp a una ranura de dispositivo, ya que vincularía WhatsApp Web.
Acceso API: Auth Básica
Basic Auth es el único método de autenticación de API. No hay claves API o JWTs para llamadas REST. Establece uno o más pares deuser:password, separados por comas:
APP_HOST=0.0.0.0, se niega a iniciar sin credenciales completas. Para desarrollo local sin autenticación, enlace APP_HOST=127.0.0.1.
Si un proxy inverso autentifica cada llamada, APP_ALLOW_UNAUTHENTICATED=true o --allow-unauthenticated=true explícitamente permite un oyente no-loopback sin Auth. Restringe el acceso directo a ese oyente.
Enviar credenciales en cada petición:
401 Unauthorized.
Lo que no está detrás de la autenticación básica
Todo lo demás, incluyendo el panel de control en
/, /mcp y /ws, requiere Basic Auth cuando está configurado.
WebSocket
Los navegadores no pueden establecer cabeceras en conexiones WebSocket, así que/ws toma la credencial en la cadena de consulta:
authorization es base64(user:password). Use TLS (wss://) y redacta la cadena de consulta en los registros de proxy. WebSocket comprueba el origen del navegador contra los mismos orígenes confiables utilizados para las solicitudes HTTP que cambian el estado. El hub WebSocket actual transmite eventos a todos los sockets conectados. Una consulta device_id selecciona el contexto del dispositivo para la conexión pero no aísla la entrega de eventos. Utilice los identificadores del dispositivo del evento para filtrar la vista del panel de control y permitir el acceso de la API sólo a las personas que llaman en confianza con todos los dispositivos.
Vea la referencia de WebSocket para códigos de eventos, carga útil y un ejemplo de cliente.
CORS
CORS permite cualquier origen por defecto. Restringirlo conAPP_CORS_ALLOWED_ORIGINS=https://ui.example.com (separados por comas). Los encabezados de solicitud permitidos son Origin, Content-Type, Accept, Authorization, y X-Device-Id.
Las comprobaciones CORS y el origen del navegador son separadas. Un comodín de origen CORS no autoriza peticiones cambiantes de estado o WebSockets. GOWA confía en los orígenes específicos de CORS de la solicitud, APP_TRUSTED_ORIGINS, y en los orígenes configurados para el emisor de OAuth y la URL de devolución de llamada de Chatwoot. Para un panel separado, configure su origen exacto:
403 CROSS_SITE_REQUEST_BLOCKED. Esto también cubre rutas GET que inician sesión, reconectan o restablecen un enlace de invitación. Clientes como curl que no envían cabeceras de origen del navegador siguen funcionando.
Un origen null nunca es de confianza. Serve gowa-ui.html sobre HTTP o HTTPS en lugar de abrirlo como una URL file://. Behind a reverse proxy, preserve Host, configure proxies confiables con X-Forwarded-Host, o liste el origen público en APP_TRUSTED_ORIGINS.
Vinculación de WhatsApp
Cada cuenta de WhatsApp vive en un espacio de dispositivos. Crea la ranura primero, luego empareja. Las rutas bajo/devices/{device_id} toman el dispositivo desde la ruta. Las rutas equivalentes /app/* usan la cabecera X-Device-Id.
QR code
qr_link y escanéalo desde el teléfono: Ajustes → Dispositivos enlazados → Enlazar un dispositivo. Solicitar un nuevo código después de qr_duration segundos. El panel de control de / muestra el QR directamente y actualiza directamente el WebSocket.
Pairing code
results.pair_code, un código de 8 caracteres. En el teléfono, elige Enlace con el número de teléfono en su lugar y escríbelo. phone debe ser el número de la cuenta vinculada, con el código del país.
Clave
Si el teléfono solicita la verificación de la clave de acceso durante el inicio de sesión QR, GOWA almacena un desafío WebAuthn y transmitePASSKEY_REQUEST en el WebSocket. El tablero maneja este flujo. Para manejarlo usted mismo:
GET /app/passkeydevuelve el desafío pendiente.POST /app/passkey/responseenvía la afirmación de WebAuthn (formatoPublicKeyCredential.toJSON()).- Espere a
PASSKEY_CONFIRMATION. Cuandoresult.skip_handoff_uxes verdadero, el flujo QR activo envía la confirmación automáticamente. De lo contrario, compareresult.codecon el código del teléfono, luego llame aPOST /app/passkey/confirm.
X-Device-Id en las tres llamadas.
Comprobar el resultado
results.is_connected y results.is_logged_in son true una vez que la cuenta está vinculada. Las sesiones persisten en storages/, así que los reinicios no requieren emparejamiento de nuevo.
Cerrando sesión y eliminando
Una cuenta desvinculada del teléfono (dispositivos enlazados → Cerrar sesión) se cierra de la misma manera: la ranura permanece y necesita emparejarse de nuevo.
Lista de seguridad
- Siempre establece
APP_BASIC_AUTHcon contraseñas fuertes en cualquier cosa accesible desde una red. - Terminar TLS en un proxy inverso; las credenciales Basic Auth sólo están codificadas en base64.
- Restringir
APP_CORS_ALLOWED_ORIGINScuando una interfaz de navegador llame a la API. - Genera un
WHATSAPP_WEBHOOK_SECRETestable conopenssl rand -hex 32. Los secretos de ejemplo vacíos o publicados son reemplazados por una clave aleatoria por proceso que cambia al reiniciar. - Trata a
storages/como sensible. Contiene todas las claves de sesión de la cuenta vinculadas. Nuevos archivos SQLite usan permisos de solo propietario, y los directorios creados para ellos usan0700. Proteja las copias de seguridad con el mismo cuidado.
