WhatsApp Platform API

Integrate WhatsApp into this project using the WASync WhatsApp Platform API.

Docs & contract
- OpenAPI 3 spec (generate the client from this): https://developers.wasync.app/openapi.json
- REST base URL: https://developers.wasync.app/api/v1
- The older host https://cloudapi.wasync.app/api/v1 is a PERMANENT ALIAS and still works — if this
  project already calls it, leave it alone. Either host is correct.
- The OAuth endpoints, the /.well-known/ documents and the MCP server URL below deliberately use
  cloudapi.wasync.app: they are registered protocol identifiers and must match byte-for-byte.
  Use them EXACTLY as written — do not rewrite their host.
- Full docs (one file, read this): https://developers.wasync.app/llms-full.txt

AUTH — USE AN API KEY (the default; do not build an OAuth flow unless told to)
- Create one at https://developers.wasync.app/keys. Shown once, stored as a hash. Put it in an env var:
    WASYNC_API_KEY=wsk_live_…
- Send it on EVERY request:  Authorization: Bearer $WASYNC_API_KEY
- No expiry, no refresh, no redirect URI, no PKCE, no consent screen. Never put it in a query string,
  in client-side code, or in source control.
- Scopes are per key: whatsapp.read (list + read), whatsapp.send (send + read receipts),
  whatsapp.events (webhooks + webhook config), whatsapp.manage (create/inspect/restart/logout/delete).
  Scopes and the reachable connection list are resolved LIVE per request — revocation is immediate and
  a connection you just created is visible on the next call.
- Errors (branch on the CODE, not the status):
    401 invalid_key         unknown/revoked key — create a new one; retrying will never help
    403 ip_not_allowed      the key has an optional IP allowlist and this address is not on it.
                            The key is FINE — add the address at developers.wasync.app/keys. Do not rotate.
    403 insufficient_scope  the key lacks the scope this endpoint needs

PROVISIONING FROM ZERO
- POST /connections works on an EMPTY workspace when you authenticate with a key — it creates the first
  connection too. There is NO manual portal step: create account → create key → POST /connections → QR.
- POST /connections is standalone-workspace only: a Bitrix24 portal gets 403 forbidden_portal_kind.
- MAKE THE CREATE IDEMPOTENT. A create provisions a WhatsApp session and consumes a PAID SLOT, so a
  timed-out request that you retry without an idempotency key produces a SECOND connection and the
  partner pays for two slots for one customer. Send the optional Idempotency-Key header on
  POST /connections (that endpoint ONLY — no other endpoint supports it; omit it and behaviour is
  exactly as before). Generate ONE key per customer-onboarding ATTEMPT: a fresh UUID
  (crypto.randomUUID()) minted right before the call and reused ONLY by that call's retries.
  Do NOT use one key per process, per API key, per day, or a constant — a key that coarse means the
  SECOND customer you onboard is handed the FIRST customer's connection back instead of his own.

Endpoints
- GET  /connections
- POST /connections            body { label? } → 201 { connection: { id, status: "connecting", qr } }
  "qr" is a data-URI PNG. Render it, then poll GET /connections/{id} every 3-5s and RE-RENDER the qr from
  EVERY poll until status === "connected". WhatsApp rotates the pairing code ~every 20s, so the qr in the
  create response is stale within seconds — a stale QR never scans and shows the user no error at all.
  Never cache it or leave a single code on screen. Creates QR/WAPP numbers only (provider "qr").
  Optional header: Idempotency-Key (opaque string ≤ 255 chars, namespaced per workspace, TTL 24h from
  first use). Handle all four cases:
    new key                    → provisioned as normal, 201
    same key + same body       → 200 + response header "Idempotency-Replayed: true", the SAME
                                 connection, nothing provisioned again. The qr is re-fetched FRESH
                                 (pairing codes rotate ~every 20s; a stale replayed QR will not scan).
                                 Treat 200 as success, not as an error.
    same key + different body  → 400 { "error": "idempotency_key_reuse" }
    first call still in flight → 409 { "error": "idempotency_in_progress" } + Retry-After: 1 —
                                 honour it and retry with the SAME key.
  Body comparison is a hash of the CANONICAL body, so JSON key order does not matter. A key over 255
  chars is rejected with 400 { "error": "idempotency_key_invalid" } (never truncated); a blank or
  whitespace-only header counts as absent. Response body shape is unchanged in all cases.
- GET  /connections/{id} · POST /connections/{id}/restart · POST /connections/{id}/logout · DELETE /connections/{id}
- GET  /account                slots + connection health — check slots.available before provisioning
- GET  /messages?connectionId=&limit=&cursor=
- POST /messages   text send: body { connectionId, to, text, idempotencyKey }
  "to" = international digits only, e.g. 40700000000;  "text" <= 4096 chars.
  media send: body { connectionId, to, media: { filename, mimetype, data (base64, ≤16 MB), caption? } }
  Supply exactly one of "text" or "media". Voice notes: mimetype=audio/ogg, filename=voice-*.ogg.
  CRITICAL: set HTTP timeout >= 180s. QR/WAPP sends take 1-7s normally (up to ~20s for long texts);
  self-heal up to ~2.5 min. WABA ~1s. A slow send is NOT a failure — never treat it as one.
  Always send idempotencyKey (UUID per logical send). On ANY error or timeout retry with the SAME key —
  a new key = a second real WhatsApp message. On 409 in_progress: poll with SAME key
  (honor Retry-After when present, else back off ~5s).
- POST /messages/read   body { connectionId, phone?, messageId? } — at least one of phone/messageId.
  Sends a WhatsApp READ RECEIPT (blue ticks). Scope whatsapp.send (it transmits to the customer).
  Call it whenever an operator opens a conversation in YOUR UI. Idempotent, no key, no rate limit.
- Webhook self-service (scope whatsapp.events):
    PUT  /webhook          body { url } → { url, events, secret }   ← STORE the secret, issued here only
    GET  /webhook                       → { url, events, secretSet }  (NEVER returns the secret)
    POST /webhook/rotate                → { secret }  (old secret dies immediately, no overlap window)
  URL must be HTTPS on a public host; http/localhost/private ranges are rejected (400 invalid_webhook).

Message ids — TWO ids, do not mix them up
- WASync id (cuid, e.g. cmqj3k2ab0001xyz): "messageId" on POST /messages, "id" on GET /messages,
  "message.id" in BOTH webhook payloads. This is the ONLY joinable id — store it on send and
  match message.status events against it.
- WhatsApp id (e.g. [email protected]_3EB0…): "waMessageId" (REST), "wa_id" (webhooks),
  "wa_message_id" (media send). May be null. Support/debugging only — never join or dedupe on it.
- Degraded case on POST /messages: { messageId: null, waMessageId: "…", status, persisted: false }
  (HTTP 200) means the message WAS delivered but was not persisted — do not retry it.

Multi-tenant: ONE api key + one workspace. POST /connections per tenant (including the first one),
  each with its OWN fresh Idempotency-Key (one per tenant-onboarding attempt — never one shared key).
  Route webhooks by connection_id (stable cuid). New connections usable immediately — the key's
  connection list is resolved live, nothing to refresh. Do NOT mint a key per tenant.

Prefer MCP if this agent supports it
- Remote MCP server (Streamable HTTP): https://cloudapi.wasync.app/api/mcp
- Tools: list_whatsapp_connections, send_whatsapp_message, read_whatsapp_messages

Webhooks (optional — incoming, delivery status, connection health)
- Events: message.received (inbound only) · message.status (sent/delivered/read/failed for YOUR sends) ·
  connection.disconnected (fires once per outage) · connection.connected (fires once on recovery).
- QR CONNECTIONS ONLY: webhooks fire for provider "qr". Meta/WABA (provider "cloud_api") emit NO
  webhooks today — poll GET /messages and GET /connections/{id} for those.
- Verify header X-WASync-Signature ("sha256=" + hex): HMAC-SHA256 over the string
  (X-WASync-Timestamp + "." + raw_request_body), keyed with the webhook secret.
  X-WASync-Timestamp is epoch MILLISECONDS. Reject if |now - X-WASync-Timestamp| > 5 min.
  ACK 2xx in <10s, process async.
- Dedupe on message.id — delivery is at-least-once. Never dedupe on wa_id (may be null).
- Status ladder: sent → delivered → read (terminal: failed). Apply monotonically — never regress
  (late/out-of-order deliveries are normal). Only apply an incoming status if its rank > stored rank.
- Reconciliation: webhooks are dropped after 3 failed attempts with no long queue. Poll GET /messages every
  30–60 s as a safety net. Webhooks = fast path; polling = guarantee.
- connection.disconnected body: { event, connection_id, connection: { id, phone_number, label, status,
  needs_reconnect, license_status, license_expires, reason }, timestamp }. The QR is NOT in the payload —
  fetch it from GET /connections/{id}. Drive UI off needs_reconnect.
- Latency: a disconnect is detected by a 5-minute status probe (~5 min); when the session looks
  recoverable WASync retries an automatic heal first, so that path takes ~15-20 min.

WAPP warm-up
- New QR/WAPP numbers have 72-hour warm-up hourly volume caps after first pairing.
- Exceeding the cap returns 429 warmup_limited (hourly cap — back off minutes, do not hot-loop).
- The separate abuse limiter returns 429 rate_limited. Honor Retry-After when present, but always keep a
  default back-off: the header is not guaranteed on every 409/429.

OAuth 2.0 — ONLY if this app is installed by OTHER WASync customers who consent to their own numbers
- Authorization Code + PKCE (S256 REQUIRED). Authorize: https://cloudapi.wasync.app/oauth/authorize
  Token: https://cloudapi.wasync.app/oauth/token (client_secret_post).
  Discovery: https://cloudapi.wasync.app/.well-known/oauth-authorization-server
- access_token TTL 15 min; refresh_token TTL 30 days and ROTATES on use — persist the new one atomically
  and serialize refreshes across workers. A grant is only issued over connections that ALREADY EXIST,
  so an OAuth-only integration cannot create a workspace's first connection.

Deliverable: a minimal working module that authenticates with the API key from the environment, lists
connections, and sends one text message; plus a verified webhook receiver if the key has whatsapp.events.
Do NOT implement OAuth unless this app is meant to be installed by other WASync customers.