Delete a session
Permanently deletes a session and its stored data. Requires the `manage` capability. **Destructive and irreversible.** This removes the session row for good. If a WhatsApp number is still attached, log it out first (`POST /sessions/{session}:logout`) to unlink the device cleanly; deleting does not guarantee the device is unlinked on WhatsApp's side. **Idempotency.** Deleting a session that does not exist (or belongs to another org) returns `not_found` (404). **Errors.** `not_found` (404) — no such session in your organization. `unauthorized` (401) / `forbidden` (403) — credential / capability failures. Returns **204 No Content** on success.
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
curl -X DELETE "https://example.com/api/v1/sessions/sess_01HZX8K3M9"{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}Get a session GET
Returns one session by id, including its current status and — once paired — the attached WhatsApp number and the gateway that holds it. Requires the `manage` capability. **Org isolation.** A session that belongs to another organization is reported as `not_found` (404), **not** `forbidden`, so a caller cannot probe for the existence of other orgs' sessions. **Errors.** `not_found` (404) — no such session in your organization. `unauthorized` (401) / `forbidden` (403) — credential / capability failures.
Get the connected account's own identity GET
Returns the WhatsApp identity of the number attached to this session — its JID, linked-device id, push name, and phone number. Requires the `manage` capability. **Precondition.** The session must be paired; if no number is attached yet, this returns `not_found` (404). On builds where this is not yet wired, it may return `not_implemented` (501). **Errors.** `not_found` (404) — session unknown or not yet paired. `not_implemented` (501) — the feature is stubbed in this build. `unauthorized` (401) / `forbidden` (403) — credential / capability failures.