# WA Hub — quickstart for an AI agent

Human? Use the guided setup instead: open this admin's UI and click Wizard mode.

This server runs one WhatsApp "bridge" process per phone number ("instance").
Everything below is copy-pasteable.

Two auth schemes: x-api-key header for everything under /i/<instance>/... (sending
and receiving); Authorization: Bearer <api key> for /mcp. Never the admin key for either.

## Concepts
- instance: lowercase id for one WhatsApp number, e.g. "senai". One pm2 process.
- bridge: the Node/Baileys process for one instance, listens on its own port.
- admin: this server (port 8800) — creates/edits/deletes instances, proxies to
  each bridge, issues API keys, runs health checks.
- consumer: an app that receives inbound WhatsApp events from one instance,
  either "core" (a local process), "webhook" (your own URL), or filtered to
  specific groups only.

## 1. Create a number
  POST /api/numbers
  headers: x-admin-key: <ADMIN_KEY>  (or a logged-in session cookie)
  body: {"instance":"myapp","nickname":"My App","phone":"+60123456789","telco":"Maxis"}
  -> {"number": {...}, "qrUrl": "/api/numbers/myapp/qr", "output": "<script log>"}
  "port" and "profile" are optional; port picks the next free one >= 8789.

## 2. Pair the phone
  GET /api/numbers/myapp/qr  -> redirects to a scannable QR page.
  On the phone: WhatsApp -> Linked devices -> Link a device -> scan.
  Poll GET /api/numbers/myapp until .live.state === "open".

## 3. Get an API key to SEND
  POST /api/keys
  body: {"name":"myapp-sender","number_ids":["myapp"]}   (or ["*"] for all)
  -> {"key":"be_myapp_sender_xxxxxxxxxxxxxxxx"}   (shown once — store it)

## 4. Send a message
  POST https://wahub.wenjyue.com/i/myapp/send
  headers: x-api-key: <the be_... key from step 3>
  body: {"op":"send_text","phone":"60123456789","text":"hi"}

## 5. Register your app to RECEIVE inbound messages
  POST /api/numbers/myapp/consumers
  body: {"name":"myapp","url":"https://myapp.example.com/inbound","filter":"all"}
        filter is "all" | "dm" | "group"; if "group", add "groups":["<jid>",...]
  -> {"ok":true,"key":"ck_myapp_xxxxxxxxxxxxxxxx","restartRequired":true}
  Then: POST /api/numbers/myapp/restart   (registering only edits the run
  script; the bridge must restart to pick up the new subscriber list)

  Your webhook will then receive:
  POST <your url>
  headers: x-api-key: <the ck_... key from this step>
  body: {"instance":"myapp","from":"60...@c.us","text":"...","ts":"...", ...}

## 6. Remove a consumer
  DELETE /api/numbers/myapp/consumers/<consumer id>
  Then POST /api/numbers/myapp/restart to apply.

## Other endpoints
  GET    /api/numbers                     list all, with live state + churn
  GET    /api/numbers/:id                 one number
  PUT    /api/numbers/:id                 edit metadata (nickname, telco, ...)
  DELETE /api/numbers/:id                 body {"confirm":"<id>"} — removes the
                                           pm2 process and DB row; auth/media
                                           dirs are MOVED to a backup dir, never deleted
  POST   /api/numbers/:id/restart         pm2 restart; response may include
                                           churnWarning if it reconnected 3+ times in 24h
  POST   /api/numbers/:id/logout          unlink the phone (needs a new QR after)
  GET    /api/health                      fleet health snapshot
  POST   /api/health/run                  force a health check now

## MCP (for claude.ai / any MCP client)
  URL: https://wahub.wenjyue.com/mcp   (Streamable HTTP, JSON-RPC 2.0)
  Auth: Authorization: Bearer <api key>  (a be_... key from step 3, or x-api-key)
  Tools: list_numbers, health, send_text, check_send, groups

This server also proxies a Rainbow AI core at http://127.0.0.1:3003 for some instances.

## Auth summary
  Admin API (everything under /api except /api/auth/*): x-admin-key header,
  or a session cookie from POST /api/auth/login.
  Sending/receiving through a number: x-api-key header with a be_... (admin-
  issued, scoped to instances) or ck_... (consumer-issued, scoped to inbound
  events only) key — never the admin key.