Stop a session
Disconnects a session from WhatsApp **without** unlinking the device. Requires the `manage` capability. The attached number stays paired, so you can `:start` it again later without re-pairing. To unlink the device entirely, use `:logout` instead. **Idempotency.** Stopping an already-stopped session is a harmless no-op. The response returns the refreshed session so you can see its new status. **Errors.** `not_found` (404) — no such session in your organization. `unauthorized` (401) / `forbidden` (403) — credential / capability failures. Returns **200** with the refreshed session.
Send Authorization: Bearer <token>. The router accepts two kinds of token and tries each in turn: a frontend-minted login JWT (verified against the frontend JWKS; the person's org + role are read from it), or an api-key for a script/service (carrying a fixed set of gateway permissions). The bearerFormat: JWT label describes the person-login case.
In: header
Path Parameters
The session id — a session is one attached (or to-be-attached) WhatsApp number, scoped to your organization. A session in another organization is reported as not_found (404), never forbidden.
Response Body
application/json
application/json
curl -X POST "https://example.com/api/v1/sessions/sess_01HZX8K3M9:stop"{ "autoRead": false, "createdAt": 1719662400000, "createdByUserId": "user_01J9DEF...", "gatewayId": "gw-sg-1", "id": "01J9ZX8K2QHV0M3T6R7P4N5W8C", "isAdminSession": false, "label": "Support line", "lastConnectedAt": 1719662400000, "organizationId": "org_01J9ABC...", "phoneNumber": "6281234567890", "presenceTyping": true, "ratePerHour": 600, "ratePerMin": 20, "status": "working", "updatedAt": 1719662400000, "waJid": "6281234567890@s.whatsapp.net", "waLid": "205227043110953@lid"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}Start a session POST
Connects an **already-paired** session to WhatsApp. Requires the `manage` capability. **Precondition.** The session must already have a number attached. To pair a *new* session instead, use the QR (`GET /sessions/{session}/qr`) or pairing-code (`POST /sessions/{session}/pairing-code`) endpoints. **Async / idempotency.** Connecting happens in the background; the response returns the refreshed session row so you can observe its new status (it may still be transitioning). Calling start on a session that is already started is a harmless no-op. **Errors.** `not_found` (404) — no such session in your organization. `unauthorized` (401) / `forbidden` (403) — credential / capability failures. Returns **200** with the refreshed session.
Create a channel (newsletter) POST
Create a WhatsApp **channel** (newsletter) owned by this session, returning its newly minted JID. **Not implemented in v1.** This endpoint is wired but the underlying WhatsApp operation is not yet built, so it **always responds `501` with `not_implemented`** — no channel is created and nothing is persisted. The request body shape below documents the eventual contract; today it is accepted but ignored. **Authorization:** requires the `send` capability; callers lacking it get `403` (`forbidden`). Requests without a valid principal get `401`. **When implemented**, this will be a write that creates a brand-new channel on the WhatsApp network; it is **not** idempotent (each successful call would create a distinct channel) and on success returns `201` with the channel's `jid`. **Errors:** `403` `forbidden` (missing `send`), `404` `not_found` (session unknown), `501` `not_implemented` (current behavior), and, once built, `400` `validation_error` for a missing/invalid `name`.