List a session's groups
Returns the groups this session belongs to. **Capability:** requires `read`. **Served from stored data:** the list comes from the gateway's stored WhatsApp data, so it works even when the session is **not connected** (no live WhatsApp round-trip). **Response:** a `List` envelope (`{ "data": [...], "nextCursor": "" }`) of group objects. The current implementation returns the full set in a single page with an empty `nextCursor`. **Errors:** - **404 `not_found`** — no session with this id is owned by your organization.
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 WhatsApp session id whose groups to list.
Response Body
application/json
application/json
curl -X GET "https://example.com/api/v1/sessions/01HZ0SESSION0000000000000/groups"{ "data": [ { "createdAtWa": 1700000000000, "description": "Coordination for Q3 launch", "firstSeenAt": 1719662400000, "groupJid": "120363021234567890@g.us", "id": 512, "isAnnounce": false, "isLocked": false, "ownerJid": "6281234567890@s.whatsapp.net", "participantCount": 42, "subject": "Project Team", "updatedAt": 1719662400000 } ], "nextCursor": "string"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}Get one contact GET
Returns everything stored for one contact, addressed by its `lid` (WhatsApp's stable per-account identifier for a person): their name, whether you have a direct chat with them, and every group you have seen them in — including their nickname and role in each group. Served entirely from **stored** data, so no live WhatsApp connection is needed. **Auth:** requires the `read` capability. **Errors:** `404` (`not_found`) if the session does not exist, is not owned by the caller's organization, or no contact with the given `lid` is stored for that session.
Create a group POST
Creates a new WhatsApp group with the given **name** (group subject) and starting **participants** (a list of user JIDs), and returns the new group's info. **Capability:** requires `send`. **Precondition (live action):** the session must be **connected**. Creating a group talks to WhatsApp in real time; if the session is not connected the gateway responds **501 `not_implemented`**. **Side effects:** the group is created on WhatsApp with this session's account as owner/first admin, the listed participants are invited, and the new group is upserted into the gateway's stored WhatsApp data so it appears in `listGroups` immediately. Not idempotent — calling twice creates two distinct groups. **Errors:** - **400 `validation_error`** — missing/empty name, no participants, or a malformed JID. - **404 `not_found`** — no session with this id is owned by your organization. - **501 `not_implemented`** — the session is not connected.