Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sessions): say an unreachable proxy only times out on wwebjs

Yudhi Armyndharis609484e02ac8
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 94a90e1a1..0e944ea87 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -400,9 +400,9 @@ Update per-session proxy settings. No restart is required or performed — chang
**Request body** — `UpdateSessionProxyDto` (any subset; each key also accepts `null`)
-| Field | Type | Constraints | Description |
-| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `proxyUrl` | string | `@IsOptional`; `@IsString`; max 255; `@IsUrl` (protocols `http`/`https`/`socks4`/`socks5`, `require_protocol`, `require_tld:false`, `allow_underscores`) | Per-session proxy egress; credentialed `http://user:pass@host` and single-label hosts allowed. Send `null` to clear. ⚠ **Must be a real, reachable proxy** when set — an unreachable value blocks the WhatsApp WebSocket on start (~30s timeout). |
+| Field | Type | Constraints | Description |
+| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `proxyUrl` | string | `@IsOptional`; `@IsString`; max 255; `@IsUrl` (protocols `http`/`https`/`socks4`/`socks5`, `require_protocol`, `require_tld:false`, `allow_underscores`) | Per-session proxy egress; credentialed `http://user:pass@host` and single-label hosts allowed. Send `null` to clear. ⚠ **Must be a real, reachable proxy** when set — an unreachable value blocks the WhatsApp WebSocket on start: on whatsapp-web.js the start times out (~30s, 504); on Baileys the start succeeds and the session keeps retrying. |
```json
{ "proxyUrl": "http://user:[email protected]:8080" }
@@ -546,12 +546,12 @@ Create a new WhatsApp session.
**Request body** — `CreateSessionDto`
-| Field | Type | Required | Constraints | Description |
-| ----------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name` | string | Yes | `@IsString`; length 3–50; `@Matches(/^[a-zA-Z0-9-]+$/)` (letters, numbers, hyphens only) | Unique session name; duplicate → `409` |
-| `config` | object | No | `@IsOptional`; `@IsObject` (keys not validated) | Session settings. Only `autoRejectCalls` (boolean, Baileys only), `maxReconnectAttempts` (clamped to 0-20, default unlimited) and `reconnectBaseDelay` (ms, clamped to 1000-300000, default 5000) are read; other keys are stored but ignored. Change them later with `PATCH /api/sessions/:sessionId/config`. Defaults to `{}`; never returned in responses |
-| `proxyUrl` | string | No | `@IsOptional`; `@IsString`; max 255; `@IsUrl` (protocols `http`/`https`/`socks4`/`socks5`, `require_protocol`, `require_tld:false`, `allow_underscores`) | Per-session proxy egress; credentialed `http://user:pass@host` and single-label hosts allowed; trusted egress, not SSRF-blocked; setting it requires an ADMIN key (`403` otherwise). ⚠ **Must be a real, reachable proxy** — an unreachable value silently blocks the WhatsApp WebSocket (no QR, start → `504`); leave unset unless you need it. See "Per-session egress proxy" below. |
-| `proxyType` | `http` \| `https` \| `socks4` \| `socks5` | No | `@IsOptional`; `@IsIn([...])` | Deprecated and ignored: the `proxyUrl` scheme selects the proxy protocol |
+| Field | Type | Required | Constraints | Description |
+| ----------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name` | string | Yes | `@IsString`; length 3–50; `@Matches(/^[a-zA-Z0-9-]+$/)` (letters, numbers, hyphens only) | Unique session name; duplicate → `409` |
+| `config` | object | No | `@IsOptional`; `@IsObject` (keys not validated) | Session settings. Only `autoRejectCalls` (boolean, Baileys only), `maxReconnectAttempts` (clamped to 0-20, default unlimited) and `reconnectBaseDelay` (ms, clamped to 1000-300000, default 5000) are read; other keys are stored but ignored. Change them later with `PATCH /api/sessions/:sessionId/config`. Defaults to `{}`; never returned in responses |
+| `proxyUrl` | string | No | `@IsOptional`; `@IsString`; max 255; `@IsUrl` (protocols `http`/`https`/`socks4`/`socks5`, `require_protocol`, `require_tld:false`, `allow_underscores`) | Per-session proxy egress; credentialed `http://user:pass@host` and single-label hosts allowed; trusted egress, not SSRF-blocked; setting it requires an ADMIN key (`403` otherwise). ⚠ **Must be a real, reachable proxy** — an unreachable value silently blocks the WhatsApp WebSocket (no QR; on whatsapp-web.js the start answers `504`, on Baileys it succeeds and the session keeps retrying); leave unset unless you need it. See "Per-session egress proxy" below. |
+| `proxyType` | `http` \| `https` \| `socks4` \| `socks5` | No | `@IsOptional`; `@IsIn([...])` | Deprecated and ignored: the `proxyUrl` scheme selects the proxy protocol |
```json
{
@@ -575,7 +575,8 @@ network cannot reach WhatsApp directly. Set `proxyUrl` on the same request:
> ⚠ `proxyUrl` **must point at a real, reachable proxy server.** A placeholder or unreachable value
> (e.g. `http://proxy.example.com:8080`) launches the engine pinned to a dead proxy, so the WhatsApp
> WebSocket never connects, **no QR code is ever delivered**, and `POST /api/sessions/:sessionId/start`
-> returns `504 Gateway Timeout` after ~30s. Leave `proxyUrl` unset unless you genuinely need a proxy.
+> returns `504 Gateway Timeout` after ~30s on whatsapp-web.js; on Baileys it succeeds and the session
+> keeps retrying the connection. Leave `proxyUrl` unset unless you genuinely need a proxy.
On the Baileys engine the proxy carries everything the engine fetches over HTTP, on all four schemes: inbound
media, the WhatsApp Web version lookup, the history-sync and app-state payloads of the initial sync, and a
@@ -662,7 +663,7 @@ Returned via `transformSession`. Status typically transitions to `initializing`
A session stopped with `POST /stop` or `POST /force-kill` is marked to run again only once the start gets past the `400` and `409` refusals below; a refused start leaves the stop in place.
-**Errors:** `400` session already started / already starting · `401` · `403` · `404` not found · `409` credential teardown for the same session name still in flight (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`; no destructive side effect runs before the refusal — a retry after cleanup settles proceeds), or, with no `code`, a `POST /stop` or `POST /force-kill` of this session that finished while the start was waiting (the stop stands; a new `POST /start` clears it and starts the session) · `504` the engine did not finish starting within its timeout (WhatsApp Web or the network unreachable, a stalled browser or resource limit, or an unreachable `proxyUrl`); the engine is torn down, so the start can be retried once the cause is addressed
+**Errors:** `400` session already started / already starting · `401` · `403` · `404` not found · `409` credential teardown for the same session name still in flight (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`; no destructive side effect runs before the refusal — a retry after cleanup settles proceeds), or, with no `code`, a `POST /stop` or `POST /force-kill` of this session that finished while the start was waiting (the stop stands; a new `POST /start` clears it and starts the session) · `504` the engine did not finish starting within its timeout (WhatsApp Web or the network unreachable, a stalled browser or resource limit, or, on whatsapp-web.js, an unreachable `proxyUrl`); the engine is torn down, so the start can be retried once the cause is addressed
#### POST /api/sessions/:sessionId/stop