Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(api): correct the infra backup, template and error tables

Yudhi Armyndharis404bc984677a
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index f980d7b93..69d326ea1 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -106,8 +106,9 @@ Validation failures (`statusCode: 400`) return `message` as an **array** of fiel
| `429` | Too Many Requests | A rate limit was exceeded: the per-client-IP tiers, the ingress per-instance limit, or send pacing (body carries `code: 'SEND_PACING_LIMITED'` and `retryAfterSeconds`); honor `Retry-After` when present |
| `500` | Internal Server Error | Send failed at the WhatsApp engine or an unexpected server error |
| `501` | Not Implemented | The operation is not supported by the active engine (see the capability matrix, docs/29) |
-| `502` | Bad Gateway | An engine transport failure (e.g. a dead Baileys socket; retryable), or an upstream component returned something unusable (not retryable; each route section carries the exact wording) |
-| `503` | Service Unavailable | A dependency or the session is not ready (boot draining, a datastore down, the engine reconnecting); retryable |
+| `502` | Bad Gateway | An engine transport failure (e.g. a dead Baileys socket; retryable), an upstream component returned something unusable (not retryable; each route section carries the exact wording), or, on a multi-node deployment, forwarding a session-scoped request to its owner node failed after the request may already have been sent, so a non-idempotent call must not be replayed blindly (see docs/13) |
+| `503` | Service Unavailable | A dependency or the session is not ready (boot draining, a datastore down, the engine reconnecting); retryable. On a multi-node deployment a forwarded request answers `503` only when the owner node was never reached, so the request was not carried out (see docs/13) |
+| `504` | Gateway Timeout | An upstream the gateway waits on did not answer in time: on a multi-node deployment, the owner node did not answer a forwarded session-scoped request within `SESSION_PROXY_TIMEOUT_MS`; on `POST /sessions/{sessionId}/start`, a session pinned to an unreachable `proxyUrl` never connected (see §6.4.1). On the forwarding path the request may still have been carried out on the owner node, so a non-idempotent call must not be replayed blindly (see docs/13) |
### Timestamp Conventions
@@ -3372,12 +3373,12 @@ Update a template's name/body/header/footer (partial; only provided fields chang
**Request body** — `UpdateTemplateDto`
-| Field | Type | Required | Constraints | Description |
-| ------ | ------ | -------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| name | string | no | if present: non-empty, max 100 chars | Applied only when not `undefined`; explicit `null` → `400`. Duplicate name → `409`. |
-| body | string | no | if present: non-empty, max 4096 chars | Applied only when not `undefined`; explicit `null` → `400`. |
-| header | string | no | max 1024 chars | Applied only when not `undefined`. The update path does **not** coerce to `null`, so passing explicit `null` fails `@IsString`; omit the key to leave it unchanged. |
-| footer | string | no | max 1024 chars | Applied only when not `undefined`. |
+| Field | Type | Required | Constraints | Description |
+| ------ | ------ | -------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| name | string | no | if present: non-empty, max 100 chars | Applied only when not `undefined`; explicit `null` → `400`. Duplicate name → `409`. |
+| body | string | no | if present: non-empty, max 4096 chars | Applied only when not `undefined`; explicit `null` → `400`. |
+| header | string | no | if present: max 1024 chars | Applied only when not `undefined`. Explicit `null` is accepted and **clears** the stored header (`200`); omit the key to leave it unchanged. |
+| footer | string | no | if present: max 1024 chars | Applied only when not `undefined`. Explicit `null` is accepted and **clears** the stored footer (`200`); omit the key to leave it unchanged. |
```json
{
@@ -5493,10 +5494,12 @@ The migration set (`MigrationTables`) is, in payload-key order: `sessions`, `web
"templates": [],
"baileysStoredMessages": [],
"lidMappings": [],
+ "chatStates": [],
"pluginInstances": [],
"conversationMappings": [],
"ingressEvents": [],
"webhookDeliveryFailures": [],
+ "webhookOutboxEvents": [],
"integrationDeliveryFailures": [],
"statusUpdates": [],
"automationRules": []
@@ -5509,10 +5512,12 @@ The migration set (`MigrationTables`) is, in payload-key order: `sessions`, `web
"templates": 0,
"baileysStoredMessages": 0,
"lidMappings": 0,
+ "chatStates": 0,
"pluginInstances": 0,
"conversationMappings": 0,
"ingressEvents": 0,
"webhookDeliveryFailures": 0,
+ "webhookOutboxEvents": 0,
"integrationDeliveryFailures": 0,
"statusUpdates": 0,
"automationRules": 0
@@ -5523,7 +5528,7 @@ The migration set (`MigrationTables`) is, in payload-key order: `sessions`, `web
Rows are raw DB column shapes (e.g. `messageBatches` rows use snake_case columns: `batch_id`, `session_id`, `current_index`, `created_at`, …). **`webhooks` rows omit `secret` and `headers`** (webhook credentials are excluded from backups; they restore as `null`/`{}`), while `pluginInstances` rows still carry integration secrets — treat the payload as a credential dump. On Postgres the generated `body_ts` FTS column is stripped from `messages` so archives stay dialect-neutral.
-`sessions`/`webhooks` are queried directly, so a hard DB error there yields `500`. The other 12 are queried tolerantly: a _genuinely missing_ table (an older DB that has not run the migration) exports as `[]` and its name is listed in `skippedTables`; any other error (lock, I/O, timeout) fails the export rather than reporting the table as empty. Check `skippedTables` before restoring — a skipped table is "not migrated yet", not "exported empty".
+`sessions`/`webhooks` are queried directly, so a hard DB error there yields `500`. The other 14 are queried tolerantly: a _genuinely missing_ table (an older DB that has not run the migration) exports as `[]` and its name is listed in `skippedTables`; any other error (lock, I/O, timeout) fails the export rather than reporting the table as empty. Check `skippedTables` before restoring — a skipped table is "not migrated yet", not "exported empty".
**Errors:** `401` · `403` · `500` DB error
@@ -5545,7 +5550,7 @@ Replace all Data DB rows with the supplied export. **Destructive and transaction
| `tables.sessions` | `SessionRow[]` | No | Inserted first; a row whose `name` is not a safe directory name is skipped with a warning (which then rolls the whole restore back). An ACTIVE status in the backup (`ready`, `initializing`, ...) describes the source host's engines: restored as `disconnected` (a notice counts them), unless the session is held by a live peer whose claim the import preserves |
| `tables.webhooks` | `WebhookRow[]` | No | Export rows omit `secret`/`headers`; an absent key restores as `null`/`{}` |
| `tables.messageBatches` | `MessageBatchRow[]` | No | snake_case columns |
-| `tables.*` (the remaining 11) | `Row[]` | No | Same keys as the export; an omitted table restores **zero** rows into an emptied table |
+| `tables.*` (the remaining 13) | `Row[]` | No | Same keys as the export; an omitted table restores **zero** rows into an emptied table |
| `stopOrphans` | boolean | No | Stop the running engines for sessions the backup does not contain, inside this request and before the replace (best-effort, time-bounded per engine). Preferred over `force` |
| `force` | boolean | No | Legacy escape hatch: proceed despite orphaned engines and leave them running until a process restart (`restartRequired: true`) |
@@ -5574,10 +5579,12 @@ Replace all Data DB rows with the supplied export. **Destructive and transaction
"templates": [],
"baileysStoredMessages": [],
"lidMappings": [],
+ "chatStates": [],
"pluginInstances": [],
"conversationMappings": [],
"ingressEvents": [],
"webhookDeliveryFailures": [],
+ "webhookOutboxEvents": [],
"integrationDeliveryFailures": [],
"statusUpdates": [],
"automationRules": []
@@ -5599,10 +5606,12 @@ Replace all Data DB rows with the supplied export. **Destructive and transaction
"templates": 0,
"baileysStoredMessages": 0,
"lidMappings": 0,
+ "chatStates": 0,
"pluginInstances": 0,
"conversationMappings": 0,
"ingressEvents": 0,
"webhookDeliveryFailures": 0,
+ "webhookOutboxEvents": 0,
"integrationDeliveryFailures": 0,
"statusUpdates": 0,
"automationRules": 0
@@ -5622,7 +5631,7 @@ Replace all Data DB rows with the supplied export. **Destructive and transaction
Because that pre-flight runs _before_ the transaction, its teardown is not covered by the rollback. A response with `imported:false` therefore still reports the engines it really stopped, and `restartRequired` on that path means only that a teardown **failed** — a cleanly stopped orphan leaves its session row intact (restart it with `POST /sessions/{sessionId}/start`), and an engine `force` left running was never orphaned after all, since the data that would have orphaned it was not replaced.
-Inside the transaction every migration table is emptied. `webhooks` and `sessions` are DELETEd directly, so a missing table there fails the restore; 11 more go through a tolerant helper where a _genuinely missing_ table is skipped; and `automation_rules` is emptied by the `DELETE FROM sessions` cascade rather than by the helper. Any other DELETE failure propagates to the rollback. Rows are then re-inserted, sessions first. JSON object/array fields are auto-stringified before insert, and the Postgres-form `$N` placeholders are rewritten for SQLite. Two guards return `imported:false` after a rollback: any `warnings`, and a payload that restores **zero** rows in total (a wrong/empty backup would otherwise commit a silent wipe — the response then carries `Backup contained no rows to restore; refused to replace existing data. Check the file.`). On commit the lid→phone mirror is reloaded from the restored rows.
+Inside the transaction every migration table is emptied. `webhooks` and `sessions` are DELETEd directly, so a missing table there fails the restore; 13 more go through a tolerant helper where a _genuinely missing_ table is skipped; and `automation_rules` is emptied by the `DELETE FROM sessions` cascade rather than by the helper. Any other DELETE failure propagates to the rollback. Rows are then re-inserted, sessions first. JSON object/array fields are auto-stringified before insert, and the Postgres-form `$N` placeholders are rewritten for SQLite. Two guards return `imported:false` after a rollback: any `warnings`, and a payload that restores **zero** rows in total (a wrong/empty backup would otherwise commit a silent wipe — the response then carries `Backup contained no rows to restore; refused to replace existing data. Check the file.`). On commit the lid→phone mirror is reloaded from the restored rows.
**Errors:** `400` `tables` absent/not an object, a table whose value is not an array of rows, a row that is not an object (`null`, a bare string, a nested array), a flag spelled as anything but a boolean or exact `true`/`false`, or a property the route does not accept — nothing is written, and field-level detail is suppressed in production unless `VALIDATION_ERROR_DETAIL=true` · `401` · `403` · `409` refused, with the reason in `code` — `IMPORT_WOULD_ORPHAN_ENGINES` (live engines exist for sessions the backup does not contain; retry with `stopOrphans` or `force`), `IMPORT_ALREADY_RUNNING` (another import is running; wait for it), `IMPORT_NESTED_TRANSACTION` (another database transaction holds the connection; retry with nothing else in flight) · `500` unrecoverable DB error
diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.md
index 6d4facc3c..0f0257e13 100644
--- a/docs/14-migration-guide.md
+++ b/docs/14-migration-guide.md
@@ -151,10 +151,12 @@ curl -X POST 'http://localhost:2785/api/infra/import-data' \
"templates": [...],
"baileysStoredMessages": [...],
"lidMappings": [...],
+ "chatStates": [...],
"pluginInstances": [...],
"conversationMappings": [...],
"ingressEvents": [...],
"webhookDeliveryFailures": [...],
+ "webhookOutboxEvents": [...],
"integrationDeliveryFailures": [...],
"statusUpdates": [...],
"automationRules": [...]
@@ -167,10 +169,12 @@ curl -X POST 'http://localhost:2785/api/infra/import-data' \
"templates": 4,
"baileysStoredMessages": 0,
"lidMappings": 87,
+ "chatStates": 24,
"pluginInstances": 2,
"conversationMappings": 31,
"ingressEvents": 12,
"webhookDeliveryFailures": 0,
+ "webhookOutboxEvents": 0,
"integrationDeliveryFailures": 0,
"statusUpdates": 19,
"automationRules": 7
diff --git a/src/modules/infra/dto/import-data.dto.spec.ts b/src/modules/infra/dto/import-data.dto.spec.ts
index 9a58a8a5f..9dd3f5243 100644
--- a/src/modules/infra/dto/import-data.dto.spec.ts
+++ b/src/modules/infra/dto/import-data.dto.spec.ts
@@ -62,6 +62,28 @@ describe('ImportDataDto', () => {
expect(description).toContain(`Every one of the ${TABLE_IMPORTERS.length} migration tables`);
});
+ /**
+ * The restore empties every migration table before repopulating, so a key missing from a
+ * documented body is a table the operator who copies that body wipes. The registry has already
+ * grown twice while the examples stayed behind, so every block a reader can copy is pinned to it.
+ */
+ it.each(['docs/06-api-specification.md', 'docs/07-api-collection.md'])(
+ 'the %s import-data example shows every table the importer restores',
+ file => {
+ const doc = readFileSync(join(__dirname, '..', '..', '..', '..', ...file.split('/')), 'utf8');
+ const heading = doc.indexOf('#### POST /api/infra/import-data');
+ const section = doc.slice(heading, doc.indexOf('\n#### ', heading + 1));
+ // Odd-indexed pieces of a fence split are the code blocks; the request body is the one that
+ // carries a `tables` container, in whichever language the page writes its examples.
+ const bodies = section.split('```').filter((piece, index) => index % 2 === 1 && piece.includes('"tables"'));
+ expect(bodies).not.toHaveLength(0);
+ for (const body of bodies) {
+ const shown = new Set([...body.matchAll(/"(\w+)":/g)].map(match => match[1]));
+ expect(TABLE_IMPORTERS.map(importer => importer.key).filter(key => !shown.has(key))).toEqual([]);
+ }
+ },
+ );
+
it('rejects a body with no tables, naming the field', async () => {
const { errors } = await run({ force: true });
// Before this DTO the inline `@Body()` type erased, so this body reached the restore and threw
diff --git a/src/modules/template/dto/template.dto.spec.ts b/src/modules/template/dto/template.dto.spec.ts
index 85769981e..a139d6a21 100644
--- a/src/modules/template/dto/template.dto.spec.ts
+++ b/src/modules/template/dto/template.dto.spec.ts
@@ -16,4 +16,11 @@ describe('UpdateTemplateDto', () => {
it.each(['name', 'body'])('rejects an explicit null %s', async field => {
await expect(through({ [field]: null })).rejects.toBeInstanceOf(BadRequestException);
});
+
+ // header and footer are nullable columns, and @IsOptional skips null as well as undefined, so an
+ // explicit null reaches update() and clears the stored value. docs/06 documents that; pin it here
+ // so the table and the behaviour cannot drift apart.
+ it.each(['header', 'footer'])('accepts an explicit null %s, which clears the stored value', async field => {
+ await expect(through({ [field]: null })).resolves.toEqual({ [field]: null });
+ });
});