Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: correct SDK tables, media and search notes, upgrade notes
Yudhi Armyndharisb62ba172f8d7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d18672191..43ec67275 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -43,7 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- The Baileys engine refuses SVG input to its image decoder, so a sticker, profile picture or group picture sent as an SVG answers `400` and an outbound image's thumbnail skips it; raster images convert as before.- The ffmpeg runs of the gateway itself (media conversion and the voice note waveform) start with only `PATH`, `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, `HOME`, `TMPDIR`, `TEMP`, `TMP`, `LANG`, `LC_ALL` and `SystemRoot` from the gateway's environment, so no secret reaches them or a wrapper script behind `FFMPEG_PATH`.- The release workflow keeps its staging image when a gate fails on a good build, so a re-run of the failed jobs finds it; an abandoned release leaves one stray tag.-- The PHP SDK release pushes its tag with git hooks disabled.+- The PHP SDK release runs its tests in a job without the mirror token, and a second job tags the mirror with git hooks disabled; the mirror workflow pushes with hooks disabled too.- The JavaScript SDK release builds, tests and packs the tarball in a job without the publish credential, and a second job publishes that tarball; the Java SDK release runs its tests in a job without the Maven Central token and the signing key.- The release workflow reads the version it extracts the release notes for from the environment instead of interpolating it into the script.- Dependabot watches the Python, Java, PHP and Go SDK manifests.@@ -54,7 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Keep the dashboard chat's scroll-to-bottom button in view while the reader is scrolled up, where it moved with the thread and was off screen.- Refuse to save a local `storage.localPath` the app cannot create or write, where the next start refused to boot and the dashboard that could undo the save was down.- Answer `400` for a send route's or a product send's `chatId`, or a bulk `batchId`, over 255 characters, where PostgreSQL answered `500` once the value passed its index entry limit.-- Answer `400` for a chat action's `chatId` over 255 characters, as the send routes do, instead of handing it to the engine.+- Answer `400` for a `chatId` over 255 characters in the request body of a chat action, as the send routes do, instead of handing it to the engine.- Use the body hash as the delivery id of an ingress request whose dedup header is longer than 255 characters, where PostgreSQL answered `500` once the value passed its index entry limit.- MCP tools refuse a `chatId`, `fromChatId` or `toChatId` over 255 characters, as the send routes do, where PostgreSQL answered an internal tool error.- A start that fails while another start of the same session is in flight leaves the claim to that start, so its engine is no longer left on a row no node holds.@@ -157,9 +157,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Parse a dashboard message made of many code spans or code blocks in linear time, so one long message no longer freezes the tab for seconds.- Render a dashboard message body over 4096 characters without links, so link detection no longer freezes the tab on a very long body.- Python SDK (next SDK release after 0.5.1): an error with an empty body names the response's status text instead of `None`.-- Python SDK (next SDK release after 0.5.1): a `timeout` of `None`, 0 or infinity means no timeout, an `httpx.Timeout` or a four-value tuple is passed through, and a negative, NaN or non-number raises `ValueError`.+- Python SDK (next SDK release after 0.5.1): a `timeout` of `None`, 0 or infinity means no timeout, an `httpx.Timeout` or a four-value tuple is passed through with a 0 or infinite element leaving that operation without a limit, and a negative, NaN or non-number raises `ValueError`.- Python SDK (next SDK release after 0.5.1): `WebhookFilterCondition` and `CustomLinkPreview` require the keys the gateway requires.-- JavaScript and PHP SDKs (next SDK release after 0.5.1): printing or dumping a client no longer shows its API key.+- JavaScript and PHP SDKs (next SDK release after 0.5.1): printing or dumping a client no longer shows its API key, and the PHP client keeps its default header values out of a dump, an export and a cast as well.+- Python and PHP SDKs (next SDK release after 0.5.1): the API key is trimmed, and one with a control or non-ASCII character is refused when the client is built, without repeating it.+- Python and PHP SDKs (next SDK release after 0.5.1): a default header value with a control or non-ASCII character is refused when the client is built, naming the header and never repeating the value.- Java SDK (next SDK release after 0.5.1): a connection failure names its exception class and keeps it as the cause instead of ending in `null`.- Java SDK (next SDK release after 0.5.1): a key or default header value with a control or non-ASCII character is refused when the client is built, naming the header and never repeating the value.- Java SDK (next SDK release after 0.5.1): a logged `HttpRequestData` shows neither the key nor the body.@@ -219,6 +221,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- ⚠️ **Breaking (API).** `vote-poll` on whatsapp-web.js answers `400` `POLL_OPTION_NOT_FOUND` when none of the option texts match, where it answered `200` and cleared the vote; an empty `options` list still clears it.- ⚠️ **Breaking (API).** Once teardown begins, every request except `/api/health`, `/api/health/*`, the dashboard's HTML pages and CORS preflights answers `503` with `Connection: close`, `GET /api/infra/health` included, while a new `/events` handshake is still admitted until the server closes; probe `/api/health/live` for a check that survives teardown.- A compose file or pod spec of your own that drops all capabilities and starts the container as root must add `KILL` to the `CHOWN`, `DAC_OVERRIDE`, `FOWNER`, `SETGID` and `SETUID` that 0.24.0 shipped, or a stop never reaches the app: it runs out the grace period and exits `137`.+- On Helm, upgrade with `--reset-then-reuse-values` (Helm 3.14 or later) or with `-f values.yaml`: plain `--reuse-values` keeps the 0.24.0 chart defaults (a 45 s grace period and no `KILL`), so every pod stop ends in `SIGKILL`.- Rolling back to 0.24.0 while webhook outbox rows are in state `queued` strands them: 0.24.0 never replays that state and prunes it after `WEBHOOK_OUTBOX_RETENTION_DAYS` (default 7). The upgrade also deletes duplicate terminal `webhook_delivery_failures` rows, which a rollback does not restore.- ⚠️ **Breaking (API).** `PUT /api/infra/config` answers `400` for a database or Redis port outside 1-65535, a negative or fractional pool size and a local storage path the app cannot create or write, which it used to store and the next boot refused.- An `FFMPEG_PATH` wrapper script that reads an environment variable outside `PATH`, `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, `HOME`, `TMPDIR`, `TEMP`, `TMP`, `LANG`, `LC_ALL` and `SystemRoot` no longer sees it; set what it needs inside the script.diff --git a/charts/openwa/README.md b/charts/openwa/README.mdindex 766b7855d..17815ef3e 100644--- a/charts/openwa/README.md+++ b/charts/openwa/README.md@@ -41,6 +41,11 @@ seconds for a boot, 295 by default. The first boot after an upgrade can build in`messages` table before the port opens: raise `startupProbe.failureThreshold`, or run the migrationsfirst ([docs/14-migration-guide.md](../../docs/14-migration-guide.md), section 14.5).+Upgrade with `helm upgrade openwa ./charts/openwa --reset-then-reuse-values` (Helm 3.14 or later), or with+`-f values.yaml`. Plain `--reuse-values` renders the new templates with the old release's defaults, which+for a release installed from 0.24.0 keeps a 45 s `terminationGracePeriodSeconds` and a capability list+without `KILL`, so every pod stop ends in `SIGKILL`.+All other values (`persistence`, `resources`, `ingress`, `serviceMonitor`, …) aredocumented inline in [values.yaml](values.yaml). The chart does NOT bundlePostgreSQL/Redis/MinIO — point `env` at your own, or stay on the SQLite default.diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 248fdb67c..261de0ad0 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -1580,7 +1580,10 @@ Media sent by this account is downloadable here regardless of that flag, becausestored inline: base64 API sends persist it on the send path, and media composed on a linked phone isdownloaded by the engine for the own-send echo. The flag buys a durable copy with its own lifecycle(S3 portability, TTL retention), not retrievability. A **URL-based send is the exception**: the-gateway fetches those bytes at send time and stores none, so there is nothing to serve or archive.+gateway fetches those bytes at send time and stores none, so on Baileys there is nothing to serve or+archive. On whatsapp-web.js the own-send echo downloads the media of every message the account+sends, a URL-based one included, and when the echo row is written first its bytes are kept, so the+route can answer `200` or `404` for the same kind of send.The inline fallback also keeps an inbound message's media downloadable after`CHAT_MEDIA_ARCHIVE_TTL_DAYS` retention purges the archived file, since retention leaves the inline@@ -6508,18 +6511,18 @@ Search messages across sessions (active search provider).**Query parameters**-| Name | Type | Required | Default | Description |-| ----------- | ------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `q` | string | **Yes** | — | Search term. Must be non-empty after trim; `400` for whitespace-only, over 1000 characters, or over 32 words (punctuation separates words, each symbol is a word, a whitespace-separated word said again counts once). Passed to the active provider's native full-text matcher. |-| `sessionId` | string | No | — | Restrict to a single session id (intersected with the key's `allowedSessions` scope). |-| `chatId` | string | No | — | Restrict to a single chat id. For a key restricted to selected chats this must name an allowed chat (`403` otherwise), and its hits are additionally narrowed to the allowlist. |-| `direction` | enum (`incoming` \| `outgoing`) | No | — | Filter by message direction. |-| `type` | string | No | — | Filter by stored message `type` (e.g. `text`, `image`, `video`). Compared against `messages.type`; not an enum validation, any string is accepted and unmatched values simply return no hits. |-| `from` | string | No | — | Filter by sender. |-| `dateFrom` | integer (epoch ms) | No | — | Inclusive lower bound on `timestamp`. A non-numeric value is rejected with `400`. |-| `dateTo` | integer (epoch ms) | No | — | Inclusive upper bound on `timestamp`. A non-numeric value is rejected with `400`. |-| `limit` | integer (≥ 1) | No | `50` | Max hits to return. Clamped to `SEARCH_LIMIT_MAX` (default `100`). A non-integer value is rejected with `400`. |-| `offset` | integer (≥ 0) | No | `0` | Pagination offset, at most `100000`. A non-integer or larger value is rejected with `400`. |+| Name | Type | Required | Default | Description |+| ----------- | ------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `q` | string | **Yes** | — | Search term. Must be non-empty after trim; `400` for whitespace-only, over 1000 characters, or over 32 words (punctuation separates words, a symbol or emoji that stands apart counts as a word, a whitespace-separated word said again counts once). Passed to the active provider's native full-text matcher. |+| `sessionId` | string | No | — | Restrict to a single session id (intersected with the key's `allowedSessions` scope). |+| `chatId` | string | No | — | Restrict to a single chat id. For a key restricted to selected chats this must name an allowed chat (`403` otherwise), and its hits are additionally narrowed to the allowlist. |+| `direction` | enum (`incoming` \| `outgoing`) | No | — | Filter by message direction. |+| `type` | string | No | — | Filter by stored message `type` (e.g. `text`, `image`, `video`). Compared against `messages.type`; not an enum validation, any string is accepted and unmatched values simply return no hits. |+| `from` | string | No | — | Filter by sender. |+| `dateFrom` | integer (epoch ms) | No | — | Inclusive lower bound on `timestamp`. A non-numeric value is rejected with `400`. |+| `dateTo` | integer (epoch ms) | No | — | Inclusive upper bound on `timestamp`. A non-numeric value is rejected with `400`. |+| `limit` | integer (≥ 1) | No | `50` | Max hits to return. Clamped to `SEARCH_LIMIT_MAX` (default `100`). A non-integer value is rejected with `400`. |+| `offset` | integer (≥ 0) | No | `0` | Pagination offset, at most `100000`. A non-integer or larger value is rejected with `400`. |**Response** `200` — `SearchResults`diff --git a/docs/07-api-collection.md b/docs/07-api-collection.mdindex 0263372d6..e10b986fe 100644--- a/docs/07-api-collection.md+++ b/docs/07-api-collection.md@@ -400,7 +400,7 @@ curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/unpin" \Download a message's stored media: the archived file when one exists (`CHAT_MEDIA_ARCHIVE_ENABLED`,plus `CHAT_MEDIA_ARCHIVE_OUTBOUND` for media this account sent), else the inline copy on the message-row — which covers media sent by this account either way, except a send made by `url`, whose bytes are not stored; `404` when neither holds bytes.+row — which covers media sent by this account either way, except a send made by `url`, whose bytes the gateway does not store (on whatsapp-web.js the own-send echo may still hold them, so that route can answer `200` or `404`); `404` when neither holds bytes.```bashcurl "$BASE/api/sessions/$SESSION_ID/messages/[email protected]/[email protected]_3EB0ABCD/media" \diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.mdindex ff00c8a4a..0d851170c 100644--- a/docs/11-operational-runbooks.md+++ b/docs/11-operational-runbooks.md@@ -786,8 +786,8 @@ OPENWA_DATA_DIR=/srv/openwa/data \> docker cp openwa-api:/app/data/backups/. ./backups/ \> && docker exec openwa-api sh -c 'rm -f /app/data/backups/openwa-backup-*.tar.gz' # do not let archives pile up on the volume> # Helm: kubectl exec <pod> -- env BACKUP_DIR=/app/data/backups ./scripts/backup.sh-> # kubectl cp <pod>:/app/data/backups ./backups-> # kubectl exec <pod> -- sh -c 'rm -f /app/data/backups/openwa-backup-*.tar.gz'+> # kubectl cp <pod>:/app/data/backups ./backups \+> # && kubectl exec <pod> -- sh -c 'rm -f /app/data/backups/openwa-backup-*.tar.gz'> ```>> The script stages a full copy of the data in `TMPDIR` before archiving it. The compose file mountsdiff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.mdindex a660557f8..d15004294 100644--- a/docs/14-migration-guide.md+++ b/docs/14-migration-guide.md@@ -827,7 +827,8 @@ set -e# this step: see Known Upgrade Hazards below.mkdir -p ./backupsdocker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh-docker cp openwa-api:/app/data/backups/. ./backups/+docker cp openwa-api:/app/data/backups/. ./backups/ \+ && docker exec openwa-api sh -c 'rm -f /app/data/backups/openwa-backup-*.tar.gz' # the copy off the volume is the backup# 2. Stop the current versiondocker compose down@@ -887,7 +888,7 @@ skips: check `pg_index.indisvalid` and drop the invalid index before building it| Release | Change | Action || -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ || `0.25.0` | Once teardown begins (SIGTERM, SIGINT, `POST /api/infra/restart`) every request except `/api/health`, `/api/health/*`, the dashboard's HTML pages and CORS preflights answers `503` with `Connection: close`, `GET /api/infra/health` included | Probe `/api/health/live` for liveness that survives teardown, and retry a `503` once the instance is up again |-| `0.25.0` | `stop_grace_period` (Docker) and `terminationGracePeriodSeconds` (Kubernetes) go from 45 to 75 s, and a stop that runs 67 s past the shutdown delay exits with status 1 instead of 137 | Raise a pinned 45 s value to at least 75 s, plus the excess of `SHUTDOWN_DELAY_MS` over 3 s and of `WEBHOOK_SHUTDOWN_DRAIN_MS` over 5 s; a container that drops all capabilities and starts as root must add `KILL` to the capabilities 0.24.0 shipped, or a stop never reaches the app; update exit-code alerts |+| `0.25.0` | `stop_grace_period` (Docker) and `terminationGracePeriodSeconds` (Kubernetes) go from 45 to 75 s, and a stop that runs 67 s past the shutdown delay exits with status 1 instead of 137 | Raise a pinned 45 s value to at least 75 s, plus the excess of `SHUTDOWN_DELAY_MS` over 3 s and of `WEBHOOK_SHUTDOWN_DRAIN_MS` over 5 s; on Helm upgrade with `--reset-then-reuse-values` (3.14 or later) or `-f values.yaml`, since plain `--reuse-values` keeps the 0.24.0 defaults; a container that drops all capabilities and starts as root must add `KILL` to the capabilities 0.24.0 shipped, or a stop never reaches the app; update exit-code alerts || `0.25.0` | `400` instead of `201` or `200` for a phone number WhatsApp reports as unregistered (Baileys; `503` when the lookup gets no answer) and for `vote-poll` with no matching option text (whatsapp-web.js) | Handle `400` (`POLL_OPTION_NOT_FOUND` carries `validOptions`) and `503` on these routes; an empty `options` list still clears a vote || `0.25.0` | `400` for an `allowedChats` list over 2000 entries and for `GET /api/search` with `q` over 1000 characters or 32 words; on Baileys also for a sticker it converts to WebP with over 500 frames, and for an `image/svg+xml` sticker, profile picture or group picture | Shorten the list or the query; on Baileys keep an animated sticker to 500 frames and convert SVG to PNG or WebP before sending || `0.25.0` | On SQLite, `GET /api/search` leaves `score` out of the hits of a key restricted to sessions or chats, because it is computed over the whole index; the hits stay in relevance order | Read `hit.score` as optional |diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex 004e16d2a..e5ff9396b 100644--- a/docs/18-sdk-design.md+++ b/docs/18-sdk-design.md@@ -392,7 +392,7 @@ try {});} catch (err) {if (err instanceof OpenWAConflictError) {- // 409: the session is not ready (start it first), or a keyed send is pending or unconfirmed.+ // 409: a conflicting state, typically a session that is not ready (start it first), or a keyed send pending or unconfirmed (see err.code).} else if (err instanceof OpenWANotFoundError) {// 404 — session/chat does not exist.} else if (err instanceof OpenWARateLimitError) {@@ -485,27 +485,27 @@ OpenWAClient(base_url: str,api_key: str,*,- timeout: float | None = 30.0,+ timeout: float | httpx.Timeout | tuple[float | None, float | None, float | None, float | None] | None = 30.0,default_headers: Mapping[str, str] | None = None,transport: httpx.BaseTransport | None = None,)```-| Parameter | Type | Default | Description |-| ----------------- | ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |-| `base_url` | `str` | _(required)_ | Gateway base URL, e.g. `http://localhost:2785`. Raises `ValueError` if empty. A trailing `/` is stripped; any path prefix is preserved. |-| `api_key` | `str` | _(required)_ | API key sent as the `X-API-Key` header. Raises `ValueError` if empty. |-| `timeout` | `float \| None` | `30.0` | Seconds per network operation, not per call; `0` or `None` turns it off. A breach raises `OpenWATimeoutError`. |-| `default_headers` | `Mapping[str, str] \| None` | `None` | Extra headers applied to every request. Applied **first**, so the SDK's `X-API-Key` and `Content-Type: application/json` always win. |-| `transport` | `httpx.BaseTransport \| None` | `None` | Optional `httpx` transport override (e.g. `httpx.MockTransport`) sharing the one connection pool. Useful for testing. |+| Parameter | Type | Default | Description |+| ----------------- | ----------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `base_url` | `str` | _(required)_ | Gateway base URL, e.g. `http://localhost:2785`. Raises `ValueError` if empty. A trailing `/` is stripped; any path prefix is preserved. |+| `api_key` | `str` | _(required)_ | API key sent as the `X-API-Key` header. Surrounding whitespace is trimmed; raises `ValueError` if empty or if it holds a control or non-ASCII character. |+| `timeout` | `float \| httpx.Timeout \| tuple \| None` | `30.0` | Seconds per network operation, not per call; `0`, `inf` or `None` turns it off. An `httpx.Timeout` or a `(connect, read, write, pool)` tuple sets the operations apart. A breach raises `OpenWATimeoutError`. |+| `default_headers` | `Mapping[str, str] \| None` | `None` | Extra headers applied to every request. Applied **first**, so the SDK's `X-API-Key` and `Content-Type: application/json` always win. |+| `transport` | `httpx.BaseTransport \| None` | `None` | Optional `httpx` transport override (e.g. `httpx.MockTransport`) sharing the one connection pool. Useful for testing. |The client also exposes a few non-resource members:-| Member | Signature | Description |-| --------- | -------------------------------------------------------- | ------------------------------------------------------------ |-| `auth` | `auth() -> AuthValidateResponse` | `POST /api/auth/validate` — validate the configured API key. |-| `request` | `request(method, path, *, query=None, body=None) -> Any` | Raw escape hatch; `path` begins with `/`. |-| `close` | `close() -> None` | Close the underlying `httpx.Client`. |+| Member | Signature | Description |+| --------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |+| `auth` | `auth() -> AuthValidateResponse` | `POST /api/auth/validate` — validate the configured API key; a key restricted to selected chats is refused with `403`. |+| `request` | `request(method, path, *, query=None, body=None) -> Any` | Raw escape hatch; `path` begins with `/`. |+| `close` | `close() -> None` | Close the underlying `httpx.Client`. |### Resources & Methods@@ -769,7 +769,7 @@ try:"text": "Hi!",})except OpenWAConflictError:- print("Session engine not ready yet — start it first.")+ print("Conflict: typically the session is not ready yet (start it first); see error.code.")except OpenWANotFoundError:print("Session does not exist.")except OpenWARateLimitError:@@ -840,10 +840,10 @@ The entry class is `OpenWA\Client`. It validates that `baseUrl` and `apiKey` areTwo escape hatches sit on the client itself:-| Method | Signature | Description |-| --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |-| `auth` | `auth(): array` | `POST /api/auth/validate` — validate the configured key and resolve its role. |-| `request` | `request(string $method, string $path, array $query = [], mixed $body = null): mixed` | Raw request against any path (advanced use); returns decoded JSON or `null` for empty/204. |+| Method | Signature | Description |+| --------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |+| `auth` | `auth(): array` | `POST /api/auth/validate` — validate the configured key and resolve its role; a key restricted to selected chats is refused with `403`. |+| `request` | `request(string $method, string $path, array $query = [], mixed $body = null): mixed` | Raw request against any path (advanced use); returns decoded JSON or `null` for empty/204. |### Client Configuration@@ -1090,11 +1090,11 @@ All payloads are associative arrays; all listed methods are synchronous and retu### Error Handling-All exceptions the SDK raises itself live in `OpenWA\Exceptions` and descend from `OpenWAException` (which extends PHP's `\Exception`). A connection failure surfaces as Guzzle's `ConnectException` and an invalid argument as `InvalidArgumentException`, so a catch-all names those as well. Any non-2xx response is raised as an `OpenWAApiException`; the static `classify()` factory picks the most specific subclass by status code. An `OpenWAApiException` carries the HTTP status (`getStatus(): int`), the parsed error body (`getBody(): mixed`), and the NestJS `error` kind when present (`getErrorKind(): ?string`), plus the body's `code` (`getErrorCode(): ?string`), the retry delay in seconds from the body's `retryAfterSeconds` or the `Retry-After` header (`getRetryAfterSeconds(): ?int`) and the response headers (`getHeaders(): array`).+All exceptions the SDK raises itself live in `OpenWA\Exceptions` and descend from `OpenWAException` (which extends PHP's `\Exception`). A transport failure that is not a timeout (a refused connection, a reset, a TLS verification failure) surfaces as one of Guzzle's own `GuzzleHttp\Exception\TransferException` subclasses (`ConnectException`, `RequestException`) and an invalid argument as `InvalidArgumentException`, so a catch-all names those as well. Any non-2xx response is raised as an `OpenWAApiException`; the static `classify()` factory picks the most specific subclass by status code. An `OpenWAApiException` carries the HTTP status (`getStatus(): int`), the parsed error body (`getBody(): mixed`), and the NestJS `error` kind when present (`getErrorKind(): ?string`), plus the body's `code` (`getErrorCode(): ?string`), the retry delay in seconds from the body's `retryAfterSeconds` or the `Retry-After` header (`getRetryAfterSeconds(): ?int`) and the response headers (`getHeaders(): array`).| Exception | Extends | Trigger || ----------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `OpenWAException` | `\Exception` | Base for the SDK's own errors (also thrown for missing `baseUrl`/`apiKey`); a transport failure other than a timeout is Guzzle's own. |+| `OpenWAException` | `\Exception` | Base for the SDK's own errors (also thrown for missing `baseUrl`/`apiKey`); a transport failure other than a timeout is Guzzle's own (`TransferException`). || `OpenWAApiException` | `OpenWAException` | Any non-2xx (including unfollowed 3xx and other 4xx/5xx). || `OpenWAAuthException` | `OpenWAApiException` | `401` — missing/invalid API key. || `OpenWAForbiddenException` | `OpenWAApiException` | `403` — the key's role or scope refuses the call (e.g. operator-only endpoint, or a session, IP or chat outside its allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). |@@ -1119,7 +1119,7 @@ try {'text' => 'Hello!',]);} catch (OpenWAConflictException $e) {- // 409: the session is not ready yet, or a keyed send is pending or unconfirmed+ // 409: a conflicting state, typically a session that is not ready yet, or a keyed send pending or unconfirmed (see getErrorCode())} catch (OpenWARateLimitException $e) {// 429 — back off and retry yourself (no auto-retry)} catch (OpenWATimeoutException $e) {diff --git a/openapi.json b/openapi.jsonindex 2fc5dbf8d..d61a878cd 100644--- a/openapi.json+++ b/openapi.json@@ -6780,7 +6780,7 @@}},"404": {- "description": "No stored media for this message — it carries no media, media download was disabled or the payload was over the cap when it was stored (size-only marker), it was a URL-based API send (those bytes are never stored), or the message is not in this gateway’s history.",+ "description": "No stored media for this message — it carries no media, media download was disabled or the payload was over the cap when it was stored (size-only marker), it was a URL-based API send (the gateway stores none of those bytes, though on whatsapp-web.js the own-send echo may), or the message is not in this gateway’s history.","content": {"application/json": {"schema": {diff --git a/src/modules/message/message.controller.ts b/src/modules/message/message.controller.tsindex 0bb5f36b7..b9cc437c0 100644--- a/src/modules/message/message.controller.ts+++ b/src/modules/message/message.controller.ts@@ -748,7 +748,8 @@ export class MessageController {description:'No stored media for this message — it carries no media, media download was disabled or the ' +'payload was over the cap when it was stored (size-only marker), it was a URL-based API send ' +- '(those bytes are never stored), or the message is not in this gateway’s history.',+ '(the gateway stores none of those bytes, though on whatsapp-web.js the own-send echo may), or ' ++ 'the message is not in this gateway’s history.',})async getChatMedia(@Param('sessionId') sessionId: string,