Join a group by invite
Joins the group named by the **invite** code (the code from a WhatsApp group invite link) and returns the joined group's JID in the shape `{ "groupJid": "...@g.us" }`. **Capability:** requires `send`. **Precondition (live action):** the session must be **connected**. If it is not the gateway responds **501 `not_implemented`**. **Success:** **200 OK** with the group's JID. Use that JID with the other group endpoints (e.g. `getGroup`, `listGroupMembers`). Joining a group the account already belongs to still returns the group's JID. **Errors:** - **400 `validation_error`** — missing or unparseable invite code/link, or the invite is invalid/expired. - **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 whose account will join the group; must be connected for this live action.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
The group invite code. Accept either the bare code or the full https://chat.whatsapp.com/ link. Required by the service. Joining a group that the account is already a member of is effectively a no-op that still returns the group's JID.
Response Body
application/json
application/json
curl -X POST "https://example.com/api/v1/sessions/01HZ0SESSION0000000000000/groups:join" \ -H "Content-Type: application/json" \ -d '{}'{ "groupJid": "string"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}Leave a group POST
Removes the session's **own** account from the group. **Capability:** requires `send`. **Precondition (live action):** the session must be **connected**. If it is not the gateway responds **501 `not_implemented`**. **Success:** **204 No Content**. After leaving, this session can no longer act on the group; reading still works only on whatever stored data remains. **Errors:** - **404 `not_found`** — the session or group does not exist (or is not yours). - **501 `not_implemented`** — the session is not connected.
Send a message POST
Sends one message from the given session. There is a **single** send endpoint for every kind of message; the discriminated `type` field in the request body chooses which one. **Supported in v1:** `text`, `poll`, `location`, and `contact`. **Not implemented yet:** the media types `image`, `video`, `audio`, `document`, and `sticker` return **501 `not_implemented`** before any WhatsApp call is made. ### Delivery mode (`?async`) - **Synchronous (default, `?async=false`):** the call blocks until WhatsApp acknowledges the send and returns **200** with the final `SendResult`. - **Asynchronous (`?async=true`):** the gateway persists the send to a queue and returns **202** immediately with a queued `SendResult`. The final delivery status arrives later as a `message.status` event on the event stream. ### Idempotency (`Idempotency-Key` header) Supply a stable key to make retries safe: replaying a send with a key already seen for your organization returns the **original** result and does not dispatch a second WhatsApp message. ### Preconditions & errors - Requires the **`send`** capability. - The session must exist, be owned by your organization, and be connected. - **400 `validation_error`** — malformed body or an unsupported/invalid field for the chosen `type`. - **404 `not_found`** — the session does not exist or is not owned by your organization. - **429 `rate_limited`** — over the per-session send rate limit. A synchronous send is rejected with 429; an async send stays queued instead of failing. - **501 `not_implemented`** — a media `type` that is not built yet.