Get one group
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.
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 that the group belongs to.
The group's JID (Jabber ID) — WhatsApp's address for the group, always ending in @g.us. Percent-encode the @ as %40 in the URL path; the gateway URL-decodes it.
Response Body
application/json
application/json
curl -X GET "https://example.com/api/v1/sessions/01HZ0SESSION0000000000000/groups/120363041234567890@g.us"{ "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}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}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.
Update group settings PATCH
Changes the group's settings — **subject**, **description**, whether only admins can post (**announce**), and whether only admins can edit group info (**locked**). **Partial update:** send only the fields you want to change; omitted fields are left untouched. Each field maps to a separate WhatsApp operation, applied in order. **Capability:** requires `send`. **Precondition (live action):** the session must be **connected** and (for most settings) its account must be a group **admin**. If the session is not connected the gateway responds **501 `not_implemented`**. **Success:** **204 No Content**. **Errors:** - **400 `validation_error`** — malformed body. - **404 `not_found`** — the session or group does not exist (or is not yours). - **403 `forbidden`** — the session's account lacks the rights to change this setting. - **501 `not_implemented`** — the session is not connected.