[](https://github.com/Pep3M/WACore/actions/workflows/ci.yml)
[](https://github.com/Pep3M/WACore/pkgs/container/wacore)
[](CHANGELOG.md)
[](https://bun.sh)
[](tsconfig.json)
[](LICENSE)
**API HTTP de WhatsApp autoalojada, pensada para desarrolladores.**
Escaneas un QR una vez, envías mensajes con una llamada REST y los recibes por webhook, SSE o polling.
[Empezar](#-empezar) · [Cómo funciona](#-cómo-funciona) · [API](#-la-api-de-un-vistazo) · [Docs](docs/index.md) · [English](README.md)
---
## Por qué WACore
Quieres que tu aplicación hable por WhatsApp sin depender de un SaaS, sin pagar por mensaje y sin mantener vivo un Chrome headless. WACore corre junto a tu código, se vincula a tu número igual que WhatsApp Web y te da una API HTTP pequeña y predecible.
- **Sin navegador.** Habla el protocolo de WhatsApp Web por WebSocket mediante [Baileys](https://github.com/WhiskeySockets/Baileys), sin Puppeteer ni Chromium. En reposo gasta una fracción de la memoria que necesita un navegador.
- **Cualquier lenguaje.** Si tu stack puede hacer una petición HTTP, puede enviar mensajes de WhatsApp. Los entrantes te llegan como prefieras: webhook firmado, stream SSE en vivo o polling.
- **Hecho para no caerse.** Reconexión con backoff exponencial, sesión persistente entre reinicios (File, Redis o PostgreSQL), recuperación sola tras cortes de red largos y un puerto `/health` aparte para tu orquestador.
- **Payloads predecibles.** Cada mensaje entrante se normaliza a una única forma tipada. Los LID internos de WhatsApp se resuelven a JID de teléfono, así que siempre puedes responder a `from`.
- **Contrato con tests.** Más de 770 tests, incluidos tests de contrato que fijan las rutas públicas, la autenticación y la forma de los payloads entre versiones.
## ⚡ Empezar
### 1. Arráncalo
**Con Docker** (recomendado):
```bash
docker run -d --name wacore \
-p 9877:9877 -p 9878:9878 \
-e API_KEY=cambia-esto \
-e SESSION_STORE=file \
-v wacore_data:/data \
ghcr.io/pep3m/wacore:latest
```
**O desde el código**, con [Bun](https://bun.sh) ≥ 1.4.4:
```bash
git clone https://github.com/Pep3M/WACore.git && cd WACore
bun install
cp .env.example .env # pon API_KEY=cambia-esto
bun start
```
### 2. Vincula tu número
El QR sale en los logs (`docker logs -f wacore`). En el móvil, abre **WhatsApp → Ajustes → Dispositivos vinculados → Vincular un dispositivo** y escanéalo. La sesión se guarda, así que solo lo haces una vez.
> También puedes pedir el QR como texto a `GET /api/qr` y pintarlo en tu propia interfaz.
### 3. Envía tu primer mensaje
```bash
curl -X POST http://localhost:9878/api/send \
-H "Authorization: Bearer cambia-esto" \
-H "Content-Type: application/json" \
-d '{"to":"5215512345678","text":"Hola desde WACore 👋"}'
```
```json
{ "success": true, "data": { "id": "3EB0C25E6A9F..." } }
```
### 4. Recibe mensajes
Dale a WACore la URL de tu endpoint y cada mensaje entrante te llegará como un `POST` firmado:
```bash
-e WEBHOOK_URL=https://tu-app.com/whatsapp \
-e WEBHOOK_SECRET=una-cadena-larga-y-aleatoria
```
```json
{
"event": "message",
"instanceId": "default",
"timestamp": "2026-09-27T12:00:00.000Z",
"data": {
"id": "3EB0C25E6A...",
"from": "5215512345678@s.whatsapp.net",
"phone": "5215512345678",
"pushName": "Juan",
"type": "text",
"body": "¡Hola! ¿Ya está mi pedido?",
"isGroup": false
}
}
```
Ese es el ciclo completo. El resto de la página entra en detalle.
## 🧭 Cómo funciona
