Check whether a phone number is on WhatsApp
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.
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 used to perform the live on-WhatsApp lookup. The session must be connected.
Query Parameters
The phone number to look up, in E.164 form (digits, optionally with a leading +). WhatsApp is queried live to determine whether this number has an account.
Response Body
application/json
application/json
curl -X GET "https://example.com/api/v1/sessions/sess_01HZX/contacts/check"{ "isOnWhatsApp": true, "jid": "string", "query": "string"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}List a session's contacts (found users) GET
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.
Get a contact's about text GET
Fetches the contact's "about" text — the short status line shown on their profile — from WhatsApp. This is a **live lookup** against WhatsApp — the session must be **connected**. If the session is not connected the gateway responds `501` (`not_implemented`). The `about` field may be an empty string when the contact has none or has restricted it by privacy settings. **Auth:** requires the `read` capability. **Errors:** `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.