Create a group
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.
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 — one attached WhatsApp number. The new group is created on this session's account, which becomes the group's first admin/owner.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
The group subject (display name) shown to all members. Required by the service; an empty name is rejected with validation_error.
Initial members to add, given as WhatsApp JIDs (user addresses ending in @s.whatsapp.net). The session's own number is implicitly the owner and need not be listed. Required by the service; numbers that cannot receive group invites may be silently skipped by WhatsApp.
Response Body
application/json
application/json
curl -X POST "https://example.com/api/v1/sessions/01HZ0SESSION0000000000000/groups" \ -H "Content-Type: application/json" \ -d '{}'{ "description": "string", "groupJid": "string", "isAnnounce": true, "isLocked": true, "ownerJid": "string", "participants": 0, "subject": "string"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}List a session's groups GET
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.
Get one group GET
Returns the stored details for one group, addressed by its group JID (`gid`): subject, description, and settings. **Capability:** requires `read`. **Served from stored data:** no live WhatsApp connection is needed. **Errors:** - **404 `not_found`** — the session does not exist (or is not yours), or no group with this `gid` is stored for it.