Kurtiu WhatsApp QR Service

Node.js microservice for WhatsApp Web integration using QR code authentication (Baileys).

This service is designed for fast backend integration:

• One WhatsApp session per userId
• HTTP endpoints to generate QR, check session status, and send messages
• Inbound and outbound status webhooks to your backend API

Quick Start (5 minutes)

1) Prerequisites

• Node.js 18+ (recommended 20+)
• npm

2) Install

npm install

3) Configure environment

cp .env.example .env

Set at least:

• SERVICE_API_KEY
• INTERNAL_API_KEY
• BACKEND_WEBHOOK_URL

Optional but recommended:

• BACKEND_STATUS_WEBHOOK_URL
• SESSIONS_DIR
• OUTBOUND_ACK_TIMEOUT_MS

4) Run locally

npm run dev

Service starts on http://localhost:3001 by default.

Quick Integration Flow

1. Health check:

curl -X GET "http://localhost:3001/health"

2. Request QR for a user session:

curl -X GET "http://localhost:3001/qr?userId=00000000-0000-0000-0000-000000000000" \
  -H "X-Internal-Api-Key: change-me"

3. Scan the QR in WhatsApp mobile app.
4. Confirm session is connected:

curl -X GET "http://localhost:3001/status?userId=00000000-0000-0000-0000-000000000000" \
  -H "X-Internal-Api-Key: change-me"

5. Send a message:

curl -X POST "http://localhost:3001/send" \
  -H "Content-Type: application/json" \
  -H "X-Internal-Api-Key: change-me" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000000",
    "number": "5511999999999",
    "message": "Hello from Kurtiu"
  }'

Endpoints

• GET /health
• GET /qr?userId=<id>
• GET /status?userId=<id>
• POST /send

Auth header required for all endpoints except /health:

• X-Internal-Api-Key: <SERVICE_API_KEY>

Environment Variables

Copy .env.example to .env and adjust values:

• PORT (default 3001)
• BACKEND_WEBHOOK_URL
• BACKEND_STATUS_WEBHOOK_URL (optional, auto-derived if empty)
• INTERNAL_API_KEY
• SERVICE_API_KEY
• SESSIONS_DIR (default ./sessions)
• REQUEST_TIMEOUT_MS (default 10000)
• OUTBOUND_ACK_TIMEOUT_MS (default 8000)
• MAX_SEND_RETRIES (default 3)

Scripts

• npm run dev - development mode with watch
• npm run build - TypeScript compile to dist/
• npm start - run dist/index.js

Session Model

Session statuses:

• initializing
• connecting
• awaiting_qr
• connected
• unhealthy
• disconnected

Each session is isolated by userId and persisted at sessions/<userId>/ by default.

Documentation

Detailed docs are in ./docs:

• docs/README.md
• docs/API.md
• docs/ARCHITECTURE.md
• docs/WEBHOOKS.md
• docs/TROUBLESHOOTING.md
• docs/DEPLOYMENT.md
• docs/CONTRIBUTING.md
• docs/examples/

Contributing

Contributions are welcome.

Start with docs/CONTRIBUTING.md for setup, scope, and PR guidelines.