Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: correct SDK tables, media and search notes, upgrade notes

Yudhi Armyndharisb62ba172f8d7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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 migrations
first ([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`, …) are
documented inline in [values.yaml](values.yaml). The chart does NOT bundle
PostgreSQL/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.md
index 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, because
stored inline: base64 API sends persist it on the send path, and media composed on a linked phone is
downloaded 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.md
index 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.
```bash
curl "$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.md
index 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 mounts
diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.md
index 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 ./backups
docker 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 version
docker 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.md
index 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` are
Two 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.json
index 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.ts
index 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,