List a session's contacts (found users)
Returns the people this session has seen, one page at a time. Served entirely from the gateway's **stored** WhatsApp data, so it works even when the session is currently disconnected — no live WhatsApp connection is required. **Filters** (all optional, combinable): - `source=dm` — keep only people you have a direct chat with. - `source=group` — keep only people seen in a group. - `group={jid}` — keep only members of the given group JID. - `q=` — case-insensitive substring search over each contact's name or number. **Pagination:** results are cursor-paged. Use `limit` (1–200, default 50) to size the page and pass the response's `nextCursor` back as `cursor` to fetch the next page. An empty `nextCursor` means there are no more pages. **Auth:** requires the `read` capability. **Errors:** `404` (`not_found`) if the session does not exist or is not owned by the caller's organization; `400` (`validation_error`) if a query parameter is malformed.
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 (a session is one attached WhatsApp number) whose contacts are listed.
Query Parameters
Optional source filter. dm keeps only people you have a direct chat with; group keeps only people seen in a group. Omit to return contacts from both sources.
Value in
- "dm"
- "group"
Optional group filter. Pass a group JID (e.g. "12345-67890@g.us") to keep only members of that one group. Has no effect unless the contacts were seen in that group.
Optional free-text search over each contact's name or phone number. Case-insensitive substring match.
Maximum number of contacts to return on one page. Clamped server-side to the range 1–200; values outside the range are coerced to the nearest bound. Defaults to 50 when omitted or 0.
int64Opaque pagination cursor. Pass the "nextCursor" value from the previous response to fetch the next page; omit on the first request. Treat the value as a token — do not parse, construct, or modify it. An empty "nextCursor" in the response means the last page was reached.
Response Body
application/json
application/json
curl -X GET "https://example.com/api/v1/sessions/sess_01HZX/contacts"{ "data": [ { "businessName": "Acme Corp", "lid": "205227043110953@lid", "name": "Alice", "phoneNumber": "6281234567890", "source": "dm" } ], "nextCursor": "string"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}Mark a chat as read POST
Clears the unread counter on the chat in the path (`cid`) and returns the updated chat. This updates the **gateway's own unread state** — the value the chat viewer reads — and does **not** send per-message read receipts to WhatsApp. **Idempotent:** calling it again on an already-read chat is a no-op and returns the same chat. Requires the `send` capability. **Errors** - `not_found` (404): the session does not exist, is not owned by the caller's organization, or no chat with that `cid` is stored. - `forbidden` (403): the caller lacks the `send` capability.
Check whether a phone number is on WhatsApp GET
Asks WhatsApp whether the given `phone` number has an account and, if so, returns its JID (WhatsApp's internal address). This is a **live lookup** against WhatsApp, not a read of stored data — the session must be **connected**. If the session is not connected the gateway responds `501` (`not_implemented`). The lookup is read-only and has no side effects; it neither adds the number as a contact nor notifies the other party. **Auth:** requires the `read` capability. **Errors:** `400` (`validation_error`) if `phone` is missing or malformed; `404` (`not_found`) if the session does not exist or is not owned by the caller's organization; `501` (`not_implemented`) if the session is not connected so the live lookup cannot run.