01 Qué es OpenWA y cuándo tiene sentido
OpenWA es una pasarela de WhatsApp con licencia MIT. Se ejecuta en tu máquina y expone tu cuenta como una API: puedes enviar y recibir mensajes, gestionar grupos y etiquetas, varias sesiones a la vez y webhooks con firma HMAC. Incluye un panel web para gestionar sesiones y claves, documentación Swagger y un servidor MCP opcional para que agentes como Claude trabajen con WhatsApp directamente.
Encaja en proyectos internos, prototipos, avisos a tu propio equipo o pruebas de concepto antes de invertir en la API oficial.
02 Instalación con Docker
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
docker compose -f docker-compose.dev.yml up -d
# Clave de administración generada en el primer arranque
docker exec openwa-api cat /app/data/.api-key
# Panel: http://localhost:2785
# API: http://localhost:2785/api
# Swagger: http://localhost:2785/api/docsLa clave solo se imprime completa la primera vez; guárdala en tu gestor de contraseñas. Sin Docker puedes usar npm ci y npm run dev, con el panel en el puerto 2886. Para producción existe docker-compose.yml con perfiles opcionales para PostgreSQL, Redis y almacenamiento S3.
| Motor (ENGINE_TYPE) | Riesgo de bloqueo | Memoria por sesión |
|---|---|---|
| whatsapp-web.js (por defecto) | Menor: usa un Chromium real que se parece al tráfico de WhatsApp Web. | 300-500 MB |
| baileys | Mayor: habla el protocolo directamente y es más fácil de detectar. | 30-80 MB |
03 Conectar un número
-
1
Crea la sesión
Desde el panel o con POST /api/sessions indicando un nombre, usando la cabecera X-API-Key.
-
2
Arráncala y pide el QR
POST /api/sessions/{id}/start y después GET /api/sessions/{id}/qr. En el panel lo verás directamente.
-
3
Escanéalo desde el móvil
En WhatsApp, Dispositivos vinculados > Vincular un dispositivo. Algunas cuentas piden crear una passkey en este paso; ningún motor lo soporta todavía y la sesión se queda esperando.
-
4
Calienta el número
Si es nuevo, úsalo unos días como una persona: foto de perfil, algunos mensajes con contactos guardados. No envíes en masa el primer día.
curl -X POST http://localhost:2785/api/sessions/{sessionId}/messages/send-text \
-H "Content-Type: application/json" \
-H "X-API-Key: TU_CLAVE" \
-d '{"chatId": "34600000000@c.us", "text": "Prueba desde OpenWA"}'04 Dos formas de conectar Claude
MCP: Claude consulta y actúa cuando tú se lo pides
Activa MCP_ENABLED=true y OpenWA monta un servidor MCP en /mcp. Por defecto ofrece 25 herramientas de solo lectura; con MCP_READONLY=false añade envíos y operaciones de grupo hasta 51. Ideal para resumir chats o redactar respuestas desde Claude Code.
Webhook: respuestas automáticas
Registras un webhook para el evento message.received con un secreto HMAC. Un pequeño servicio tuyo verifica la firma, envía el mensaje a Claude con tus instrucciones y devuelve la respuesta por send-text.
{
"mcpServers": {
"openwa": {
"type": "http",
"url": "http://localhost:2785/mcp",
"headers": { "Authorization": "Bearer ${OPENWA_API_KEY}" }
}
}
}Crea en esta carpeta un servicio pequeño en Node.js que reciba el webhook message.received de OpenWA. Requisitos: verificar la firma HMAC con el secreto de la variable OPENWA_WEBHOOK_SECRET antes de procesar nada; ignorar mensajes propios y de grupos; llamar a la API de Claude con ANTHROPIC_API_KEY y estas instrucciones: [personalidad, horario, qué puede y no puede prometer]; responder por /messages/send-text; derivar a una persona si el cliente lo pide o si el tema es [lista]; limitar a 20 respuestas por hora y registrar cada conversación en un archivo. Sin claves en el código. Enséñame el plan antes de escribirlo.05 Reglas para no perder el número
- ✓Nunca conectes tu número personal ni el principal de la empresa; usa uno dedicado.
- ✓Escribe solo a quien te ha escrito antes o ha aceptado recibir mensajes; los envíos en frío a desconocidos son la vía más rápida al bloqueo.
- ✓Activa SEND_PACING_ENABLED=true para limitar envíos diarios y conversaciones nuevas según la antigüedad de la sesión.
- ✓Mantén unos pocos mensajes por minuto por sesión, no miles por hora.
- ✓Evita IP de centros de datos baratas; se marcan antes que las residenciales.
- ✓Para inicios de sesión, cobros u otros procesos críticos, ten siempre una alternativa por SMS, correo o la API oficial.
- ✓Revisa que la IA no prometa precios, plazos o condiciones que no puede garantizar.
Preguntas frecuentes
El software es libre, pero automatizar una cuenta con clientes no oficiales va contra las condiciones de WhatsApp y puede suponer el bloqueo del número. Si tratas datos de clientes en la UE, además necesitas base legal, información al usuario y garantías del RGPD; en ese caso usa la API oficial.
Para un servicio que responde solo las 24 horas, lo adecuado es la API de Claude con una clave de Console y pago por uso, con límites de gasto configurados. La suscripción está pensada para tu uso interactivo.
Sí. OpenWA gestiona varias sesiones en la misma instancia y permite claves restringidas a una sesión concreta.
Sí. Hay nodos comunitarios para n8n y plugins oficiales para Chatwoot y Typebot, además de la API REST y los webhooks para cualquier otra herramienta.
Es una política de WhatsApp, no un fallo de OpenWA: la API devuelve éxito pero el servidor de WhatsApp puede descartar el primer mensaje a contactos que nunca te han escrito.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.