Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

feat(message): add safe send idempotency

Yudhi Armyndharisecc568568572
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 859fa835b..67d319a12 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Add bounded webhook failure redrive with optional payload retention.
- Expose caller-supplied send idempotency keys in all five SDKs.
+- Add optional 24-hour idempotency keys to twelve single-recipient send routes.
### Fixed
@@ -18,6 +19,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Enforce webhook replay retention and keep later eligible failures moving through batches.
- Keep one terminal webhook failure per receiver idempotency key.
+### Fixed
+
+- Idempotent sends retain their key after an engine-stage failure, including HTTP 409, so a same-key retry cannot send another copy.
+
## [0.24.0] - 2026-10-03
### Added
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 33ea1b0c8..b9e45d1c6 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -54,6 +54,7 @@ OpenWA v0.2+ implements a **dual-database architecture** that separates boot con
│ │ • status_updates │
│ │ • webhook_delivery_failures │
│ │ • webhook_outbox_events │
+│ │ • send_idempotency_keys │
│ │ • plugin_instances │
│ │ • ingress_events │
│ │ • conversation_mappings │
@@ -709,6 +710,7 @@ The data connection also owns:
- **`status_updates`** — inbound status/story broadcasts with a 24-hour TTL (`src/modules/status-store/entities/status-update.entity.ts`); unique on `(sessionId, waStatusId)`. Attached media is stored via `StorageService`, not in the row.
- **`webhook_delivery_failures`** — durable record of a webhook delivery that exhausted its retries, or was not sent (attempts 0) (`src/modules/webhook/entities/webhook-delivery-failure.entity.ts`), surfaced via the ADMIN `GET /webhooks/delivery-failures`. A shed or shutdown-refused delivery is replayed by the outbox until its replay budget runs out; an oversize payload or a preflight failure on first dispatch is not replayed. A later successful delivery removes the row. While `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0 (default 0), a terminal row (attempts > 0) also keeps the pre-hook event data in `payload` (never selected by the listing, which reports `replayable` instead) so ADMIN `POST /webhooks/delivery-failures/redrive` can replay it with the stored idempotency key; the payload is cleared once that window passes and the row stays.
- **`webhook_outbox_events`**: the outbound webhook delivery record (`src/modules/webhook/entities/webhook-outbox-event.entity.ts`): a row is written `pending` before the delivery attempt, so a delivery lost to a crash is replayed by the reconciler. It settles as `dispatched` once a durable owner (the BullMQ queue, or the inline POST in direct mode) holds it, or as `failed` when the replays run out or the reconciler finds the webhook removed, disabled or unsubscribed from the event (no failure row is written then). Settled rows drop their payload and are pruned on age (§5.7).
+- **`send_idempotency_keys`**: one claimed `Idempotency-Key` per `(sessionId, idempotencyKey)` (unique) from the opt-in header on the message send routes (`src/modules/message/entities/send-idempotency-key.entity.ts`). The insert that wins the unique key runs the send; the row then holds `state` (`pending`, `completed` with the `responseBody` replayed to retries, or `failed` when the outcome is unknown), the `route` and a SHA-256 `requestHash` of route and body. Rows expire 24 hours after the claim (`expiresAt`) and are pruned hourly (§5.7). Not exported by `GET /infra/export-data`.
- **`plugin_instances`** — one configured instance of an adapter plugin, keyed `${pluginId}:${instanceId}` (`src/modules/integration/entities/plugin-instance.entity.ts`); holds the host-minted ingress HMAC secret, masked on API reads.
- **`ingress_events`** — persist-before-ack durable row and inbound dedup oracle, unique on `(pluginId, instanceId, providerDeliveryId)` (`src/modules/integration/entities/ingress-event.entity.ts`). The full payload is retired to `NULL` once dispatch is settled, leaving a slim dedup marker.
- **`conversation_mappings`** — bidirectional WA-chat ↔ provider-conversation mapping plus handover state (`src/modules/integration/entities/conversation-mapping.entity.ts`).
@@ -853,10 +855,10 @@ flowchart LR
OpenWA runs **two separate TypeORM connections**, each with its own migrations directory and CLI DataSource:
-| Connection | DataSource | Migrations dir | Owns |
-| ---------- | --------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **main** | `data-source-main.ts` | `src/database/migrations-main/` | `api_keys`, `audit_logs` — always SQLite (`./data/main.sqlite` by default) |
-| **data** | `data-source.ts` | `src/database/migrations/` | `sessions`, `webhooks`, `messages`, `message_batches`, `templates`, `status_updates`, `automation_rules`, `webhook_delivery_failures`, `webhook_outbox_events`, the integration tables (`plugin_instances`, `ingress_events`, `conversation_mappings`, `integration_delivery_failures`), engine tables — SQLite **or** PostgreSQL |
+| Connection | DataSource | Migrations dir | Owns |
+| ---------- | --------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **main** | `data-source-main.ts` | `src/database/migrations-main/` | `api_keys`, `audit_logs`, always SQLite (`./data/main.sqlite` by default) |
+| **data** | `data-source.ts` | `src/database/migrations/` | `sessions`, `webhooks`, `messages`, `message_batches`, `templates`, `status_updates`, `automation_rules`, `webhook_delivery_failures`, `webhook_outbox_events`, `send_idempotency_keys`, the integration tables (`plugin_instances`, `ingress_events`, `conversation_mappings`, `integration_delivery_failures`), engine tables, SQLite **or** PostgreSQL |
Migrations are hand-authored and idempotent (`IF NOT EXISTS`) so they are safe to adopt on a database originally created by `synchronize`. The two connections differ in how schema is managed:
@@ -911,7 +913,9 @@ src/database/migrations/ # data connection (pluggable)
├── 1786800000000-AddBaileysStoredMessagesSessionCreatedIdIndex.ts # (sessionId, createdAt, id) index for the Baileys store cap trim
├── 1786900000000-ScrubRevokedMessageContent.ts # clears content kept on rows revoked by earlier releases
├── 1786950000000-ScrubNonPhoneLidMappings.ts # drops lid_mappings rows where earlier releases stored a broadcast id as the phone
-└── 1787000000000-AddWebhookDeliveryFailurePayload.ts # webhook_delivery_failures.payload (replay copy for the redrive route)
+├── 1787000000000-AddWebhookDeliveryFailurePayload.ts # webhook_delivery_failures.payload (optional replay copy)
+├── 1787100000000-AddSendIdempotencyKeys.ts # send_idempotency_keys (opt-in send retry guard)
+└── 1787200000000-DeduplicateTerminalWebhookFailures.ts # one terminal record per webhook and idempotency key
```
> [!NOTE]
@@ -946,7 +950,7 @@ export class AddMessagesWaMessageIdUnique1781300000000 implements MigrationInter
### Retention Policies
-Six tables have an automated _time-based_ retention job, across five services: **`audit_logs`**, **`status_updates`**, **`webhook_delivery_failures`**, **`webhook_outbox_events`** (settled rows only), **`ingress_events`** and **`integration_delivery_failures`**. Separately, **`baileys_stored_messages`** is capped per session rather than by age: each write keeps the newest `BAILEYS_MESSAGE_STORE_LIMIT` rows (default 5000) for that session and deletes the rest. Everything else is kept indefinitely (api keys, sessions, webhooks, pending and processing batches, templates, conversation mappings, plugin instances, lid mappings, chat states, automation rules) and is removed only by user action (e.g. deleting a session) or operational backup/restore. Two more, `messages` and finished `message_batches`, have an opt-in time-based job (`MESSAGE_RETENTION_DAYS`, off by default); until it is set they are kept indefinitely too.
+Seven tables have an automated _time-based_ retention job, across six services: **`audit_logs`**, **`status_updates`**, **`webhook_delivery_failures`**, **`webhook_outbox_events`** (settled rows only), **`ingress_events`**, **`integration_delivery_failures`** and **`send_idempotency_keys`**. Separately, **`baileys_stored_messages`** is capped per session rather than by age: each write keeps the newest `BAILEYS_MESSAGE_STORE_LIMIT` rows (default 5000) for that session and deletes the rest. Everything else is kept indefinitely (api keys, sessions, webhooks, pending and processing batches, templates, conversation mappings, plugin instances, lid mappings, chat states, automation rules) and is removed only by user action (e.g. deleting a session) or operational backup/restore. Two more, `messages` and finished `message_batches`, have an opt-in time-based job (`MESSAGE_RETENTION_DAYS`, off by default); until it is set they are kept indefinitely too.
| Data Type | Default Retention | Configurable |
| ----------------------------- | ----------------- | --------------------------------------------------------------- |
@@ -958,6 +962,7 @@ Six tables have an automated _time-based_ retention job, across five services: *
| Webhook outbox (settled rows) | 7 days | Yes, `WEBHOOK_OUTBOX_RETENTION_DAYS` (≤ 0 does **not** disable) |
| Ingress events (dedup rows) | 7 days | Yes — `INGRESS_DEDUP_RETENTION_DAYS` (≤ 0 does **not** disable) |
| Integration delivery failures | 90 days | Yes — `INGRESS_RETENTION_DAYS` (≤ 0 disables this prune only) |
+| Send idempotency keys | 24 hours | No (fixed: the window a key guards a retry) |
### Audit-Log Cleanup Job
@@ -992,6 +997,7 @@ The other interval-based prunes are the same shape: one prune at startup, then a
- **`webhook_outbox_events`**: `WebhookOutboxService.onModuleInit()` (`src/modules/webhook/webhook-outbox.service.ts`), window `WEBHOOK_OUTBOX_RETENTION_DAYS` (default 7). Only settled rows are deleted; a `pending` row is a delivery that can still be replayed and is never pruned on age. A non-positive value does **not** disable the prune: a settled row carries no payload, so the service warns and falls back to 7 days.
- **`ingress_events`** and **`integration_delivery_failures`** — `IntegrationRetentionService` (`src/modules/integration/integration-retention.service.ts`) prunes both in one timer on two independent windows. `INGRESS_DEDUP_RETENTION_DAYS` (default 7) bounds the dedup rows; a non-positive value does **not** disable it — an unpruned dedup table grows without bound for no functional gain, so the service warns and falls back to the 7-day default. `INGRESS_RETENTION_DAYS` (default 90) bounds the DLQ rows, where long retention can be a deliberate operator choice, so ≤ 0 disables that prune (and only that prune).
- **`messages`** and finished **`message_batches`**: `MessageRetentionService` (`src/modules/message/message-retention.service.ts`), window `MESSAGE_RETENTION_DAYS` (default 0, which keeps everything; boot rejects a value above 36500). Messages are deleted by `createdAt` in batches of 500 ids, at most 200 batches per run, so a run deletes at most 100,000 messages; a run that hits that limit logs a warning and is followed by another a minute later until the backlog is cleared. Pending and processing batches are never pruned. Once enabled, send pacing treats a contact silent for longer than the window as a new (cold) contact again, stats totals and search results shrink, archived media files are reclaimed by the chat-media orphan sweep, and a history sync does not write back messages older than the window. Search plugins get no `message:deleted` for pruned rows, so an external index keeps its copies.
+- **`send_idempotency_keys`**: `SendIdempotencyService` (`src/modules/message/idempotency/send-idempotency.service.ts`) deletes rows past `expiresAt` (24 hours after the claim) on an hourly `setInterval`, with no startup run: a claim that collides with an expired row deletes it and claims the key itself, so a late prune never blocks a send.
### Status-Update TTL Sweep
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 6b2d31eed..eadd32158 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -1283,6 +1283,22 @@ The delete removes, in one transaction, the session's messages, message batches,
All routes are mounted under `/api/sessions/:sessionId/messages`. Reads (`GET` history, batch status, reactions) accept any valid API key (including VIEWER). All write/send routes require **API key (OPERATOR)** or higher. Single-recipient send routes return `MessageResponseDto { messageId, timestamp }` (`timestamp` is an epoch **number** in seconds; there is no `status` field); `POST send-bulk` instead returns `202` with `BulkMessageResponseDto`. The global ValidationPipe runs `whitelist` + `forbidNonWhitelisted`, so any body field not listed below is rejected with `400`.
+#### Idempotent sends
+
+The single-recipient send routes (`send-text`, `send-template`, `send-image`, `send-video`, `send-audio`, `send-document`, `send-location`, `send-contact`, `send-sticker`, `send-poll`, `reply`, `forward`) accept an optional `Idempotency-Key` request header, so a client can retry after a timeout or a dropped connection without sending the message twice. Without the header nothing changes.
+
+The key is 1-255 visible ASCII characters (a UUID works), unique per session, and is held for **24 hours** from the first request. Within that window:
+
+| Retry with the same key | Answer |
+| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| first request succeeded, same route and body | the first response again, with `Idempotent-Replayed: true`; nothing is sent |
+| first request still running | `409` `IDEMPOTENCY_KEY_IN_PROGRESS`; retry after it finishes |
+| first request failed during an engine send (including `4xx` or `501`), with another server error, or a timeout | `409` `IDEMPOTENCY_OUTCOME_UNKNOWN`: the message may have gone out; check the chat, then use a **new** key |
+| first request was refused with `4xx` or `501` before calling the engine | the key was freed, so the retry runs as a new request |
+| different route or body (key order in the JSON does not matter) | `422` `IDEMPOTENCY_KEY_REUSED` |
+
+A malformed key, or the header sent twice, gets `400` `IDEMPOTENCY_KEY_INVALID`. A request still pending ten minutes after it was claimed (its node most likely stopped) also reads as `IDEMPOTENCY_OUTCOME_UNKNOWN`. HTTP status alone does not prove that nothing was sent: an engine can report `409` after attempting delivery, so engine-stage failures retain the key conservatively. Keys are stored in the data database (`send_idempotency_keys`); concurrent processes using that database share the claim, and the session-owner proxy forwards the header. This does not change the deployment support limits in [Horizontal scaling](./13-horizontal-scaling.md). `send-bulk` does not take the header: retrying its request can create another batch. A call that outlives the 24-hour key window is outside the retry guarantee.
+
#### GET /api/sessions/:sessionId/messages
Get persisted message history for a session from the local DB (paginated, filterable). Reads the DB only — does not hit WhatsApp.
@@ -1739,7 +1755,7 @@ rejected with `400` rather than guessing which half was meant.
`messageId` is the WhatsApp message id from the engine. By default (`SIMULATE_TYPING`; set it to `false` to disable) a typing indicator and a humanising pause run before the send: 500 ms plus 45 ms per character, capped at `SIMULATE_TYPING_MAX_MS` (default 5000 ms), with +/-15% jitter.
-**Errors:** `400` unknown body field, validation failure, or session not active / blocked by a plugin hook · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine
+**Errors:** `400` unknown body field, validation failure, or session not active / blocked by a plugin hook · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
##### Quoted sends
@@ -1828,7 +1844,7 @@ Render a stored text template (header/body/footer joined by blank lines, `{{vars
Delegates to the send-text path after rendering.
-**Errors:** `400` unknown body field, validation failure, neither `templateId` nor `templateName` given, or session not active · `401` missing/invalid API key · `403` key role below OPERATOR · `404` session or template not found · `500` engine error · `409` conflict or engine not ready (retryable)
+**Errors:** `400` unknown body field, validation failure, neither `templateId` nor `templateName` given, or session not active · `401` missing/invalid API key · `403` key role below OPERATOR · `404` session or template not found · `500` engine error · `409` conflict or engine not ready (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-image
@@ -1865,7 +1881,7 @@ Send an image (by URL or base64) with an optional caption.
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` neither `url` nor `base64`, base64 without `mimetype`, SSRF-blocked URL, a `url` that answers non-2xx, times out or cannot be reached, session not active, or unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
+**Errors:** `400` neither `url` nor `base64`, base64 without `mimetype`, SSRF-blocked URL, a `url` that answers non-2xx, times out or cannot be reached, session not active, or unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-video
@@ -1891,7 +1907,7 @@ Send a video (by URL or base64) with an optional caption. Uses the same `SendMed
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-audio
@@ -1917,7 +1933,7 @@ Send an audio message (by URL or base64). Uses `SendAudioMessageDto`. A `caption
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-document
@@ -1950,7 +1966,7 @@ Send a document/file (by URL or base64). Uses `SendMediaMessageDto`; `filename`
**Engine differences:** Baileys always sends a document as a document, while whatsapp-web.js deliberately keeps normal mimetype classification for `status@broadcast` and broadcast lists; the library returns `null` for document-mode sends to those recipients, so forcing the flag there would turn a working send into a failure. For URL-based sends without an explicit `filename`, whatsapp-web.js derives the URL basename, percent-decoded; Baileys falls back to the literal `file`.
-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-location
@@ -1991,7 +2007,7 @@ Send a location pin.
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` invalid coords / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a location to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent
+**Errors:** `400` invalid coords / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a location to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-contact
@@ -2024,7 +2040,7 @@ Send a contact card (vCard).
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a contact card to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent
+**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a contact card to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-sticker
@@ -2050,7 +2066,7 @@ Send a sticker (by URL or base64; typically webp). Reuses `SendMediaMessageDto`.
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine, or (whatsapp-web.js) a sticker to a channel, `status@broadcast` or a broadcast list · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine, or (whatsapp-web.js) a sticker to a channel, `status@broadcast` or a broadcast list · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-poll
@@ -2089,7 +2105,7 @@ Send a native WhatsApp poll.
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` validation failure (option count/length) / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a poll to a status or broadcast list (`@broadcast`), nor one with `quotedMessageId` to a channel (`<id>@newsletter`); nothing is sent
+**Errors:** `400` validation failure (option count/length) / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a poll to a status or broadcast list (`@broadcast`), nor one with `quotedMessageId` to a channel (`<id>@newsletter`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/reply
@@ -2124,7 +2140,7 @@ Reply to a message, quoting a prior message.
The quoted body is best-effort resolved from the DB for the reply preview.
-**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the quoted message is not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a reply to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent
+**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the quoted message is not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a reply to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/click-button
@@ -2201,7 +2217,7 @@ Forward a message from one chat to another.
`messageId` may be an empty string when the engine could not recover the forwarded copy's id.
-**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the message to forward is not found in `fromChatId` · `500` engine error · `409` conflict or engine not ready (retryable)
+**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the message to forward is not found in `fromChatId` · `500` engine error · `409` conflict or engine not ready (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/react
diff --git a/openapi.json b/openapi.json
index 0b51c7b0b..e1172224f 100644
--- a/openapi.json
+++ b/openapi.json
@@ -4320,6 +4320,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -4402,6 +4411,16 @@
}
}
},
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"501": {
"description": "A caller-supplied `customLinkPreview` is not supported by the whatsapp-web.js engine — only Baileys can attach one. The send itself is supported on both; omit the field, or use `linkPreview`. whatsapp-web.js also refuses a send with `quotedMessageId` to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent.",
"content": {
@@ -4431,6 +4450,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -4503,6 +4531,16 @@
}
}
}
+ },
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
}
},
"summary": "Render a stored text template and send it as a text message",
@@ -4523,6 +4561,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -4606,6 +4653,16 @@
}
}
},
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"501": {
"description": "Sending media to a channel (`<id>@newsletter`) is not supported by the whatsapp-web.js engine — the page method it needs was removed by a WhatsApp Web update. Text to a channel still works. whatsapp-web.js also refuses a send with `quotedMessageId` to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent.",
"content": {
@@ -4645,6 +4702,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -4727,6 +4793,16 @@
}
}
},
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"501": {
"description": "Sending media to a channel (`<id>@newsletter`) is not supported by the whatsapp-web.js engine — the page method it needs was removed by a WhatsApp Web update. Text to a channel still works. whatsapp-web.js also refuses a send with `quotedMessageId` to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent.",
"content": {
@@ -4766,6 +4842,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -4849,6 +4934,16 @@
}
}
},
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"501": {
"description": "Sending media to a channel (`<id>@newsletter`) is not supported by the whatsapp-web.js engine — the page method it needs was removed by a WhatsApp Web update. Text to a channel still works. whatsapp-web.js also refuses a send with `quotedMessageId` to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent.",
"content": {
@@ -4888,6 +4983,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -4971,6 +5075,16 @@
}
}
},
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"501": {
"description": "Sending media to a channel (`<id>@newsletter`) is not supported by the whatsapp-web.js engine — the page method it needs was removed by a WhatsApp Web update. Text to a channel still works. whatsapp-web.js also refuses a send with `quotedMessageId` to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent.",
"content": {
@@ -5010,6 +5124,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -5084,6 +5207,16 @@
}
}
},
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"501": {
"description": "whatsapp-web.js cannot send a location to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent.",
"content": {
@@ -5113,6 +5246,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -5186,6 +5328,16 @@
}
}
},
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"501": {
"description": "whatsapp-web.js cannot send a contact card to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent.",
"content": {
@@ -5215,6 +5367,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -5297,6 +5458,16 @@
}
}
},
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"501": {
"description": "Sending media to a channel (`<id>@newsletter`) is not supported by the whatsapp-web.js engine — the page method it needs was removed by a WhatsApp Web update. Text to a channel still works. whatsapp-web.js cannot send a sticker to a status or broadcast list (`@broadcast`) either; nothing is sent.",
"content": {
@@ -5336,6 +5507,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -5412,6 +5592,16 @@
}
}
},
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"501": {
"description": "whatsapp-web.js cannot send a poll to a status or broadcast list (`@broadcast`), nor one with `quotedMessageId` to a channel (`<id>@newsletter`); nothing is sent.",
"content": {
@@ -5441,6 +5631,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -5514,6 +5713,16 @@
}
}
},
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"501": {
"description": "whatsapp-web.js cannot send a reply to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent.",
"content": {
@@ -5646,6 +5855,15 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "description": "Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ASCII characters, unique per session. While the first request runs a retry gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. Errors from an engine send keep it taken regardless of HTTP status, including 409.",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
}
],
"requestBody": {
@@ -5718,6 +5936,16 @@
}
}
}
+ },
+ "422": {
+ "description": "`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
}
},
"summary": "Forward a message to another chat",
diff --git a/src/common/errors/engine-send-failure.ts b/src/common/errors/engine-send-failure.ts
new file mode 100644
index 000000000..54f9cba2b
--- /dev/null
+++ b/src/common/errors/engine-send-failure.ts
@@ -0,0 +1,11 @@
+/** Errors escaping an engine send, including its failure bookkeeping, have an uncertain outcome. */
+const attemptedSendFailures = new WeakSet<object>();
+
+export function markEngineSendFailure<T>(error: T): T {
+ if (error !== null && typeof error === 'object') attemptedSendFailures.add(error);
+ return error;
+}
+
+export function isEngineSendFailure(error: unknown): boolean {
+ return error !== null && typeof error === 'object' && attemptedSendFailures.has(error);
+}
diff --git a/src/configure-app.ts b/src/configure-app.ts
index 2d65f69dd..4ede4f53a 100644
--- a/src/configure-app.ts
+++ b/src/configure-app.ts
@@ -168,7 +168,8 @@ export function configureApp(app: INestApplication, options: ConfigureAppOptions
},
credentials: corsPolicy.credentials,
methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
- allowedHeaders: ['Content-Type', 'X-API-Key', 'Authorization', 'X-Request-ID'],
+ // Idempotency-Key is the opt-in retry guard on the send routes (SendIdempotencyInterceptor).
+ allowedHeaders: ['Content-Type', 'X-API-Key', 'Authorization', 'X-Request-ID', 'Idempotency-Key'],
// The throttlers are named (short/medium/long, plus ingress-ip on ingress), so @nestjs/throttler
// suffixes every rate-limit header with the throttler name; IngressService emits the per-instance
// bucket's headers under the same `-instance` suffix. Expose the suffixed names so browser clients
@@ -196,6 +197,8 @@ export function configureApp(app: INestApplication, options: ConfigureAppOptions
'Retry-After-long',
'Retry-After-instance',
'Retry-After-ingress-ip',
+ // Marks a send answered from a stored Idempotency-Key response rather than sent again.
+ 'Idempotent-Replayed',
],
maxAge: 86400, // 24 hours
});
diff --git a/src/database/migrations/1787100000000-AddSendIdempotencyKeys.ts b/src/database/migrations/1787100000000-AddSendIdempotencyKeys.ts
new file mode 100644
index 000000000..6089c51b4
--- /dev/null
+++ b/src/database/migrations/1787100000000-AddSendIdempotencyKeys.ts
@@ -0,0 +1,48 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Creates `send_idempotency_keys`, the claims behind the opt-in `Idempotency-Key` header on the send
+ * routes (SendIdempotencyInterceptor). UNIQUE(sessionId, idempotencyKey) is the claim itself: the
+ * insert that wins it runs the send, so the guarantee holds across nodes sharing the database.
+ *
+ * Hand-authored because `synchronize` is off on the `data` connection for Postgres; the `hasTable`
+ * guard keeps it idempotent on a database where synchronize already created the table. The DDL
+ * matches what synchronize emits from the entity, so the migration-drift gate sees no difference:
+ * `responseBody` is `text` on both dialects (jsonColumnType() is 'simple-json'), `expiresAt` is
+ * dateColumnType() ('text' on SQLite) and `createdAt` a plain @CreateDateColumn ('datetime' there).
+ */
+export class AddSendIdempotencyKeys1787100000000 implements MigrationInterface {
+ name = 'AddSendIdempotencyKeys1787100000000';
+
+ public async up(queryRunner: QueryRunner): Promise<void> {
+ if (await queryRunner.hasTable('send_idempotency_keys')) return;
+ const isPostgres = queryRunner.connection.options.type === 'postgres';
+ const id = isPostgres
+ ? `"id" varchar PRIMARY KEY NOT NULL DEFAULT gen_random_uuid()::varchar`
+ : `"id" varchar PRIMARY KEY NOT NULL`;
+ const expiresTs = isPostgres ? 'timestamp' : 'text';
+ const createdTs = isPostgres ? 'timestamp' : 'datetime';
+ const now = isPostgres ? 'NOW()' : `(datetime('now'))`;
+
+ await queryRunner.query(
+ `CREATE TABLE "send_idempotency_keys" (${id}, "sessionId" varchar NOT NULL, ` +
+ `"idempotencyKey" varchar NOT NULL, "route" varchar NOT NULL, "requestHash" varchar NOT NULL, ` +
+ `"state" varchar NOT NULL, "responseBody" text, "expiresAt" ${expiresTs} NOT NULL, ` +
+ `"createdAt" ${createdTs} NOT NULL DEFAULT ${now})`,
+ );
+ await queryRunner.query(
+ `CREATE UNIQUE INDEX "UQ_send_idempotency_keys_session_key" ON "send_idempotency_keys" ("sessionId", "idempotencyKey")`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX "IDX_send_idempotency_keys_expiresAt" ON "send_idempotency_keys" ("expiresAt")`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise<void> {
+ // IF EXISTS so revert is idempotent on a synchronize-bootstrapped DB, where up() took the
+ // hasTable early return and the named indexes were never created.
+ await queryRunner.query(`DROP INDEX IF EXISTS "IDX_send_idempotency_keys_expiresAt"`);
+ await queryRunner.query(`DROP INDEX IF EXISTS "UQ_send_idempotency_keys_session_key"`);
+ await queryRunner.query(`DROP TABLE IF EXISTS "send_idempotency_keys"`);
+ }
+}
diff --git a/src/database/migrations/__tests__/1787100000000-AddSendIdempotencyKeys.spec.ts b/src/database/migrations/__tests__/1787100000000-AddSendIdempotencyKeys.spec.ts
new file mode 100644
index 000000000..ec9073551
--- /dev/null
+++ b/src/database/migrations/__tests__/1787100000000-AddSendIdempotencyKeys.spec.ts
@@ -0,0 +1,64 @@
+import { DataSource } from 'typeorm';
+import { AddSendIdempotencyKeys1787100000000 } from '../1787100000000-AddSendIdempotencyKeys';
+
+describe('AddSendIdempotencyKeys migration', () => {
+ let ds: DataSource;
+ const migration = new AddSendIdempotencyKeys1787100000000();
+
+ beforeEach(async () => {
+ ds = new DataSource({ type: 'better-sqlite3', database: ':memory:' });
+ await ds.initialize();
+ });
+
+ afterEach(async () => {
+ if (ds.isInitialized) await ds.destroy();
+ });
+
+ it('creates the table with both indexes', async () => {
+ await migration.up(ds.createQueryRunner());
+
+ const cols: { name: string }[] = await ds.query(`PRAGMA table_info("send_idempotency_keys")`);
+ expect(cols.map(c => c.name).sort()).toEqual(
+ [
+ 'createdAt',
+ 'expiresAt',
+ 'id',
+ 'idempotencyKey',
+ 'requestHash',
+ 'responseBody',
+ 'route',
+ 'sessionId',
+ 'state',
+ ].sort(),
+ );
+ const indexes: { name: string }[] = await ds.query(`PRAGMA index_list("send_idempotency_keys")`);
+ expect(indexes.map(i => i.name)).toContain('UQ_send_idempotency_keys_session_key');
+ expect(indexes.map(i => i.name)).toContain('IDX_send_idempotency_keys_expiresAt');
+ });
+
+ it('refuses a second row for the same session and key, and allows it in another session', async () => {
+ await migration.up(ds.createQueryRunner());
+ const insert = (id: string, sessionId: string): Promise<unknown> =>
+ ds.query(
+ `INSERT INTO "send_idempotency_keys" ("id","sessionId","idempotencyKey","route","requestHash","state","expiresAt") ` +
+ `VALUES ('${id}','${sessionId}','key-1','sendText','h','pending','2099-01-01T00:00:00.000Z')`,
+ );
+
+ await insert('row-1', 'sess-1');
+ // The unique key IS the claim: a second insert must fail so only one request sends.
+ await expect(insert('row-2', 'sess-1')).rejects.toThrow();
+ await expect(insert('row-3', 'sess-2')).resolves.toBeDefined();
+ });
+
+ it('is a no-op when the table already exists, and reverts idempotently', async () => {
+ await migration.up(ds.createQueryRunner());
+ await expect(migration.up(ds.createQueryRunner())).resolves.toBeUndefined();
+
+ await migration.down(ds.createQueryRunner());
+ const tables: unknown[] = await ds.query(
+ `SELECT name FROM sqlite_master WHERE type='table' AND name='send_idempotency_keys'`,
+ );
+ expect(tables).toHaveLength(0);
+ await expect(migration.down(ds.createQueryRunner())).resolves.toBeUndefined();
+ });
+});
diff --git a/src/modules/infra/export-tables.ts b/src/modules/infra/export-tables.ts
index 81196ef6b..e861a54bf 100644
--- a/src/modules/infra/export-tables.ts
+++ b/src/modules/infra/export-tables.ts
@@ -329,5 +329,6 @@ export const EXPORT_TABLES: AnyExportTable[] = [
* entity metadata does not report it.
*/
export const EXPORT_TABLE_EXCLUSIONS: Readonly<Record<string, string>> = {
- // (empty today: every data-connection entity table is exported)
+ // Claims expire within 24 hours; a restored key would only block or replay a send it never saw.
+ send_idempotency_keys: 'short-lived Idempotency-Key claims (24 h TTL), meaningless after a restore',
};
diff --git a/src/modules/message/entities/send-idempotency-key.entity.ts b/src/modules/message/entities/send-idempotency-key.entity.ts
new file mode 100644
index 000000000..f2f53ecee
--- /dev/null
+++ b/src/modules/message/entities/send-idempotency-key.entity.ts
@@ -0,0 +1,63 @@
+import { Column, CreateDateColumn, Entity, Index, PrimaryGeneratedColumn } from 'typeorm';
+import { dateColumnType, jsonColumnType } from '../../../common/utils/column-types';
+import { DateTransformer } from '../../../common/transformers/date.transformer';
+
+/**
+ * The lifecycle of one `Idempotency-Key` claim on a send route:
+ * - 'pending' - the request holding the key is running (or the node died while it ran).
+ * - 'completed' - the send succeeded; `responseBody` is replayed to every retry with the same key.
+ * - 'failed' - the send failed in a way that does not say whether WhatsApp got the message (an
+ * engine error or timeout). The key stays taken so a retry cannot send it twice.
+ * A refusal before the engine call deletes the row, so the client may retry with the same key.
+ * Engine-stage failures keep it taken regardless of HTTP status, including a disconnected socket's 409.
+ */
+export type SendIdempotencyState = 'pending' | 'completed' | 'failed';
+
+/**
+ * One `Idempotency-Key` a client sent on a send route, kept for SEND_IDEMPOTENCY_TTL (24 h) so a
+ * retry after a timeout or a dropped connection replays the first answer instead of sending the
+ * message again. Opt-in per request: a send without the header never touches this table.
+ *
+ * UNIQUE(sessionId, idempotencyKey) is the claim: the insert that wins it runs the send, every other
+ * request with the pair reads the row. It holds across nodes sharing one database, because the claim
+ * is the insert itself rather than a read followed by a write.
+ *
+ * Lives on the `data` connection (auto-loaded by the message entity glob). Not exported by
+ * `GET /infra/export-data`: a key outlives its purpose within a day.
+ */
+@Entity('send_idempotency_keys')
+@Index('UQ_send_idempotency_keys_session_key', ['sessionId', 'idempotencyKey'], { unique: true })
+@Index('IDX_send_idempotency_keys_expiresAt', ['expiresAt'])
+export class SendIdempotencyKey {
+ @PrimaryGeneratedColumn('uuid')
+ id!: string;
+
+ @Column()
+ sessionId!: string;
+
+ /** The client's `Idempotency-Key` header value, verbatim (1-255 visible ASCII characters). */
+ @Column()
+ idempotencyKey!: string;
+
+ /** The send route the key was first used on (`send-text`, `reply`, ...). */
+ @Column()
+ route!: string;
+
+ /** SHA-256 of the route and the request body; a retry whose hash differs is refused with 422. */
+ @Column()
+ requestHash!: string;
+
+ @Column({ type: 'varchar' })
+ state!: SendIdempotencyState;
+
+ /** The response body of a completed send, replayed verbatim. NULL while pending or after a failure. */
+ @Column({ type: jsonColumnType(), nullable: true })
+ responseBody!: Record<string, unknown> | null;
+
+ /** When the key may be reused for a new send; the hourly sweep deletes rows past it. */
+ @Column({ type: dateColumnType(), transformer: DateTransformer })
+ expiresAt!: Date;
+
+ @CreateDateColumn()
+ createdAt!: Date;
+}
diff --git a/src/modules/message/idempotency/idempotent-send.decorator.ts b/src/modules/message/idempotency/idempotent-send.decorator.ts
new file mode 100644
index 000000000..c78606dec
--- /dev/null
+++ b/src/modules/message/idempotency/idempotent-send.decorator.ts
@@ -0,0 +1,26 @@
+import { applyDecorators, UseInterceptors } from '@nestjs/common';
+import { ApiHeader, ApiResponse } from '@nestjs/swagger';
+import { SendIdempotencyInterceptor } from './send-idempotency.interceptor';
+
+export const IDEMPOTENCY_KEY_HEADER_DESCRIPTION =
+ 'Optional. Makes the send safe to retry: within 24 hours, a retry with the same key and body replays ' +
+ 'the first response (marked `Idempotent-Replayed: true`) instead of sending again. 1-255 visible ' +
+ 'ASCII characters, unique per session. While the first request runs a retry gets 409 ' +
+ '`IDEMPOTENCY_KEY_IN_PROGRESS`; after a failure that may have sent the message it gets 409 ' +
+ '`IDEMPOTENCY_OUTCOME_UNKNOWN`. A 4xx or 501 refusal before the engine call frees the key. ' +
+ 'Errors from an engine send keep it taken regardless of HTTP status, including 409.';
+
+/**
+ * Marks a send route as accepting the opt-in `Idempotency-Key` header: wires the interceptor and
+ * documents the header and the 422 it can add. The 409 codes share the route's existing 409 entry,
+ * since the contract keeps one entry per status.
+ */
+export const IdempotentSend = (): MethodDecorator =>
+ applyDecorators(
+ UseInterceptors(SendIdempotencyInterceptor),
+ ApiHeader({ name: 'Idempotency-Key', required: false, description: IDEMPOTENCY_KEY_HEADER_DESCRIPTION }),
+ ApiResponse({
+ status: 422,
+ description: '`IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different route or body.',
+ }),
+ );
diff --git a/src/modules/message/idempotency/send-idempotency.interceptor.spec.ts b/src/modules/message/idempotency/send-idempotency.interceptor.spec.ts
new file mode 100644
index 000000000..e757d00ad
--- /dev/null
+++ b/src/modules/message/idempotency/send-idempotency.interceptor.spec.ts
@@ -0,0 +1,153 @@
+import {
+ BadRequestException,
+ ConflictException,
+ ExecutionContext,
+ HttpStatus,
+ InternalServerErrorException,
+ NotImplementedException,
+ ServiceUnavailableException,
+ UnprocessableEntityException,
+} from '@nestjs/common';
+import { lastValueFrom, of, throwError } from 'rxjs';
+import { EngineNotReadyError } from '../../../common/errors/engine-not-ready.error';
+import { markEngineSendFailure } from '../../../common/errors/engine-send-failure';
+import { SendIdempotencyInterceptor, sendFailureProvesNothingSent } from './send-idempotency.interceptor';
+import { hashSendRequest, SendIdempotencyService } from './send-idempotency.service';
+
+describe('SendIdempotencyInterceptor', () => {
+ let store: jest.Mocked<Pick<SendIdempotencyService, 'claim' | 'complete' | 'release' | 'markFailed'>>;
+ let interceptor: SendIdempotencyInterceptor;
+ let setHeader: jest.Mock;
+
+ const contextFor = (headers: Record<string, string | string[]>, body: unknown = { chatId: 'c', text: 't' }) => {
+ setHeader = jest.fn();
+ return {
+ getType: () => 'http',
+ getHandler: () => ({ name: 'sendText' }),
+ switchToHttp: () => ({
+ getRequest: () => ({ headers, params: { sessionId: 's1' }, body }),
+ getResponse: () => ({ setHeader }),
+ }),
+ } as unknown as ExecutionContext;
+ };
+
+ beforeEach(() => {
+ store = {
+ claim: jest.fn().mockResolvedValue({ kind: 'claimed', id: 'row-1' }),
+ complete: jest.fn().mockResolvedValue(undefined),
+ release: jest.fn().mockResolvedValue(undefined),
+ markFailed: jest.fn().mockResolvedValue(undefined),
+ };
+ interceptor = new SendIdempotencyInterceptor(store as unknown as SendIdempotencyService);
+ });
+
+ const run = async (ctx: ExecutionContext, handler: () => unknown) =>
+ lastValueFrom(await interceptor.intercept(ctx, { handle: () => handler() as never }));
+
+ it('passes a request without the header straight through, touching no storage', async () => {
+ const out = await run(contextFor({}), () => of({ messageId: 'm1' }));
+
+ expect(out).toEqual({ messageId: 'm1' });
+ expect(store.claim).not.toHaveBeenCalled();
+ });
+
+ it('claims (session, key) with the route and body hash, and stores the response on success', async () => {
+ const body = { chatId: 'c', text: 't' };
+ const out = await run(contextFor({ 'idempotency-key': 'k-1' }, body), () => of({ messageId: 'm1' }));
+
+ expect(out).toEqual({ messageId: 'm1' });
+ expect(store.claim).toHaveBeenCalledWith({
+ sessionId: 's1',
+ key: 'k-1',
+ route: 'sendText',
+ requestHash: hashSendRequest('sendText', body),
+ });
+ expect(store.complete).toHaveBeenCalledWith('row-1', { messageId: 'm1' });
+ });
+
+ it('replays a completed key without running the send, marking the response', async () => {
+ store.claim.mockResolvedValue({ kind: 'replay', body: { messageId: 'm1' } });
+ const handler = jest.fn(() => of({ messageId: 'NEW' }));
+
+ const out = await run(contextFor({ 'idempotency-key': 'k-1' }), handler);
+
+ expect(out).toEqual({ messageId: 'm1' });
+ expect(handler).not.toHaveBeenCalled();
+ expect(setHeader).toHaveBeenCalledWith('idempotent-replayed', 'true');
+ });
+
+ it.each([
+ ['mismatch', UnprocessableEntityException, 'IDEMPOTENCY_KEY_REUSED'],
+ ['in_progress', ConflictException, 'IDEMPOTENCY_KEY_IN_PROGRESS'],
+ ['outcome_unknown', ConflictException, 'IDEMPOTENCY_OUTCOME_UNKNOWN'],
+ ] as const)('answers a %s claim with %p (%s) and never sends', async (kind, Exc, code) => {
+ store.claim.mockResolvedValue({ kind });
+ const handler = jest.fn(() => of({}));
+
+ const error = await run(contextFor({ 'idempotency-key': 'k-1' }), handler).catch((e: unknown) => e);
+
+ expect(error).toBeInstanceOf(Exc);
+ expect((error as ConflictException).getResponse()).toEqual(expect.objectContaining({ code }));
+ expect(handler).not.toHaveBeenCalled();
+ });
+
+ it.each([[''], ['has space'], [['a', 'b']]])('refuses a malformed key %p with 400 before claiming', async key => {
+ const error = await run(contextFor({ 'idempotency-key': key }), () => of({})).catch((e: unknown) => e);
+
+ expect(error).toBeInstanceOf(BadRequestException);
+ expect((error as BadRequestException).getResponse()).toEqual(
+ expect.objectContaining({ code: 'IDEMPOTENCY_KEY_INVALID' }),
+ );
+ expect(store.claim).not.toHaveBeenCalled();
+ });
+
+ it('frees the key when the send was refused before reaching WhatsApp', async () => {
+ const refusal = new EngineNotReadyError();
+ await expect(run(contextFor({ 'idempotency-key': 'k-1' }), () => throwError(() => refusal))).rejects.toBe(refusal);
+
+ expect(store.release).toHaveBeenCalledWith('row-1');
+ expect(store.markFailed).not.toHaveBeenCalled();
+ });
+
+ it('keeps the key taken when the send failed ambiguously', async () => {
+ const boom = new Error('Evaluation failed');
+ await expect(run(contextFor({ 'idempotency-key': 'k-1' }), () => throwError(() => boom))).rejects.toBe(boom);
+
+ expect(store.markFailed).toHaveBeenCalledWith('row-1');
+ expect(store.release).not.toHaveBeenCalled();
+ });
+
+ it('still answers the send when recording its outcome fails', async () => {
+ store.complete.mockRejectedValue(new Error('db down'));
+
+ await expect(run(contextFor({ 'idempotency-key': 'k-1' }), () => of({ messageId: 'm1' }))).resolves.toEqual({
+ messageId: 'm1',
+ });
+ });
+});
+
+describe('sendFailureProvesNothingSent', () => {
+ it.each([new BadRequestException(), new EngineNotReadyError(), new NotImplementedException()])(
+ 'keeps an engine-stage %p uncertain regardless of HTTP status',
+ error => {
+ expect(sendFailureProvesNothingSent(markEngineSendFailure(error))).toBe(false);
+ },
+ );
+
+ it.each([
+ [new BadRequestException(), true],
+ [new ConflictException(), true],
+ [new UnprocessableEntityException(), true],
+ [new NotImplementedException(), true],
+ [new InternalServerErrorException(), false],
+ [new ServiceUnavailableException(), false],
+ [new Error('timeout'), false],
+ ['string', false],
+ ])('%p -> %p', (error, expected) => {
+ expect(sendFailureProvesNothingSent(error)).toBe(expected);
+ });
+
+ it('treats 501 as a refusal', () => {
+ expect(HttpStatus.NOT_IMPLEMENTED).toBe(501);
+ });
+});
diff --git a/src/modules/message/idempotency/send-idempotency.interceptor.ts b/src/modules/message/idempotency/send-idempotency.interceptor.ts
new file mode 100644
index 000000000..5c78ad1a2
--- /dev/null
+++ b/src/modules/message/idempotency/send-idempotency.interceptor.ts
@@ -0,0 +1,148 @@
+import {
+ BadRequestException,
+ CallHandler,
+ ConflictException,
+ ExecutionContext,
+ HttpException,
+ HttpStatus,
+ Injectable,
+ NestInterceptor,
+ UnprocessableEntityException,
+} from '@nestjs/common';
+import type { Request, Response } from 'express';
+import { from, lastValueFrom, Observable, of } from 'rxjs';
+import { createLogger } from '../../../common/services/logger.service';
+import { isEngineSendFailure } from '../../../common/errors/engine-send-failure';
+import { hashSendRequest, isValidIdempotencyKey, SendIdempotencyService } from './send-idempotency.service';
+
+/** Request header a client sets to make a send safe to retry. */
+export const IDEMPOTENCY_KEY_HEADER = 'idempotency-key';
+/** Response header set on an answer replayed from an earlier request with the same key. */
+export const IDEMPOTENT_REPLAYED_HEADER = 'idempotent-replayed';
+
+/**
+ * Whether a failed send proves nothing reached WhatsApp, so the key can be freed for a retry.
+ *
+ * A 4xx or 501 before the engine call is a refusal. Errors escaping the shared engine-send failure
+ * boundary stay uncertain regardless of status: a disconnected socket can report 409 after
+ * WhatsApp accepted the message. Other server errors/timeouts also keep the key taken.
+ */
+export function sendFailureProvesNothingSent(error: unknown): boolean {
+ if (isEngineSendFailure(error) || !(error instanceof HttpException)) return false;
+ const status: number = error.getStatus();
+ const notImplemented: number = HttpStatus.NOT_IMPLEMENTED;
+ return status < 500 || status === notImplemented;
+}
+
+/**
+ * Opt-in `Idempotency-Key` support for the message send routes.
+ *
+ * Without the header the request runs exactly as before; nothing is read or written. With it, the
+ * key is claimed for (session, key) before the send runs, and:
+ * - a retry of a send that succeeded gets the stored response again, marked `Idempotent-Replayed:
+ * true`, and nothing is sent;
+ * - a retry while the first request still runs gets 409 `IDEMPOTENCY_KEY_IN_PROGRESS`;
+ * - a retry after a failure that may have sent the message gets 409 `IDEMPOTENCY_OUTCOME_UNKNOWN`
+ * (check the chat, then send again with a NEW key if it did not arrive);
+ * - the same key with a different route or body gets 422 `IDEMPOTENCY_KEY_REUSED`.
+ * A failure that proves nothing was sent frees the key, so a corrected retry may reuse it.
+ *
+ * Route-scoped (applied with `@UseInterceptors` on each send route) rather than global, so it runs
+ * after the guards and after SessionProxyInterceptor: a request forwarded to the owning node is
+ * claimed there, once, not on the hop.
+ */
+@Injectable()
+export class SendIdempotencyInterceptor implements NestInterceptor {
+ private readonly logger = createLogger('SendIdempotency');
+
+ constructor(private readonly store: SendIdempotencyService) {}
+
+ async intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<unknown>> {
+ if (context.getType() !== 'http') return next.handle();
+ const request = context.switchToHttp().getRequest<Request>();
+ const raw = request.headers[IDEMPOTENCY_KEY_HEADER];
+ if (raw === undefined) return next.handle();
+
+ const key = Array.isArray(raw) ? undefined : raw;
+ if (key === undefined || !isValidIdempotencyKey(key)) {
+ throw new BadRequestException({
+ statusCode: 400,
+ error: 'Bad Request',
+ message: 'Idempotency-Key must be one value of 1-255 visible ASCII characters.',
+ code: 'IDEMPOTENCY_KEY_INVALID',
+ });
+ }
+
+ const sessionId = String((request.params as Record<string, string | undefined>).sessionId ?? '');
+ const route = context.getHandler().name;
+ const claim = await this.store.claim({
+ sessionId,
+ key,
+ route,
+ requestHash: hashSendRequest(route, request.body),
+ });
+
+ switch (claim.kind) {
+ case 'replay':
+ context.switchToHttp().getResponse<Response>().setHeader(IDEMPOTENT_REPLAYED_HEADER, 'true');
+ return of(claim.body);
+ case 'mismatch':
+ throw new UnprocessableEntityException({
+ statusCode: 422,
+ error: 'Unprocessable Entity',
+ message: 'This Idempotency-Key was already used for a different request. Use a new key.',
+ code: 'IDEMPOTENCY_KEY_REUSED',
+ });
+ case 'in_progress':
+ throw new ConflictException({
+ statusCode: 409,
+ error: 'Conflict',
+ message: 'A request with this Idempotency-Key is still running. Retry after it finishes.',
+ code: 'IDEMPOTENCY_KEY_IN_PROGRESS',
+ });
+ case 'outcome_unknown':
+ throw new ConflictException({
+ statusCode: 409,
+ error: 'Conflict',
+ message:
+ 'An earlier request with this Idempotency-Key failed and the message may have been sent. ' +
+ 'Check the chat; to send again, use a new key.',
+ code: 'IDEMPOTENCY_OUTCOME_UNKNOWN',
+ });
+ case 'claimed':
+ return from(this.runClaimed(claim.id, next));
+ }
+ }
+
+ private async runClaimed(id: string, next: CallHandler): Promise<unknown> {
+ let body: unknown;
+ try {
+ body = await lastValueFrom(next.handle());
+ } catch (error) {
+ await this.settle(id, sendFailureProvesNothingSent(error) ? 'release' : 'fail');
+ throw error;
+ }
+ await this.settle(id, 'complete', body);
+ return body;
+ }
+
+ /**
+ * Record the outcome. Best-effort: the send already happened (or was refused), and failing the
+ * request over bookkeeping would make the client retry a send that went through. A row left
+ * 'pending' reads as in-progress, then outcome-unknown, so a retry still cannot double-send.
+ */
+ private async settle(id: string, outcome: 'complete' | 'release' | 'fail', body?: unknown): Promise<void> {
+ try {
+ if (outcome === 'complete') await this.store.complete(id, body);
+ else if (outcome === 'release') await this.store.release(id);
+ else await this.store.markFailed(id);
+ } catch (error) {
+ this.logger.warn('Could not record the outcome of an idempotent send', {
+ claimId: id,
+ outcome,
+ error: error instanceof Error ? error.message : String(error),
+ action: 'send_idempotency_settle_failed',
+ });
+ }
+ }
+}
diff --git a/src/modules/message/idempotency/send-idempotency.service.spec.ts b/src/modules/message/idempotency/send-idempotency.service.spec.ts
new file mode 100644
index 000000000..b4f99c597
--- /dev/null
+++ b/src/modules/message/idempotency/send-idempotency.service.spec.ts
@@ -0,0 +1,144 @@
+import { DataSource, Repository } from 'typeorm';
+import { SendIdempotencyKey } from '../entities/send-idempotency-key.entity';
+import {
+ hashSendRequest,
+ isValidIdempotencyKey,
+ SEND_IDEMPOTENCY_STALE_PENDING_MS,
+ SEND_IDEMPOTENCY_TTL_MS,
+ SendIdempotencyService,
+} from './send-idempotency.service';
+
+describe('SendIdempotencyService (sqlite)', () => {
+ let ds: DataSource;
+ let repo: Repository<SendIdempotencyKey>;
+ let service: SendIdempotencyService;
+ const input = { sessionId: 's1', key: 'k-1', route: 'sendText', requestHash: 'h1' };
+
+ beforeEach(async () => {
+ ds = new DataSource({
+ type: 'better-sqlite3',
+ database: ':memory:',
+ entities: [SendIdempotencyKey],
+ synchronize: true,
+ });
+ await ds.initialize();
+ repo = ds.getRepository(SendIdempotencyKey);
+ service = new SendIdempotencyService(repo);
+ });
+
+ afterEach(async () => {
+ service.onModuleDestroy();
+ await ds.destroy();
+ });
+
+ it('claims a fresh key, and a second claim of the same key while it runs is in progress', async () => {
+ const first = await service.claim(input);
+ expect(first.kind).toBe('claimed');
+
+ expect(await service.claim(input)).toEqual({ kind: 'in_progress' });
+ expect(await repo.count()).toBe(1);
+ });
+
+ it('lets only one of two concurrent claims win', async () => {
+ const results = await Promise.all([service.claim(input), service.claim(input)]);
+ expect(results.filter(r => r.kind === 'claimed')).toHaveLength(1);
+ expect(results.filter(r => r.kind === 'in_progress')).toHaveLength(1);
+ });
+
+ it('scopes keys per session', async () => {
+ expect((await service.claim(input)).kind).toBe('claimed');
+ expect((await service.claim({ ...input, sessionId: 's2' })).kind).toBe('claimed');
+ });
+
+ it('replays the stored body once the send completed', async () => {
+ const claim = await service.claim(input);
+ if (claim.kind !== 'claimed') throw new Error('expected a claim');
+ await service.complete(claim.id, { messageId: 'm1', timestamp: 1 });
+
+ expect(await service.claim(input)).toEqual({ kind: 'replay', body: { messageId: 'm1', timestamp: 1 } });
+ });
+
+ it('refuses the key for a different body or route', async () => {
+ await service.claim(input);
+ expect(await service.claim({ ...input, requestHash: 'h2' })).toEqual({ kind: 'mismatch' });
+ });
+
+ it('frees a released key for a new claim', async () => {
+ const claim = await service.claim(input);
+ if (claim.kind !== 'claimed') throw new Error('expected a claim');
+ await service.release(claim.id);
+
+ expect((await service.claim({ ...input, requestHash: 'h2' })).kind).toBe('claimed');
+ });
+
+ it('keeps a failed key taken and reports the outcome as unknown', async () => {
+ const claim = await service.claim(input);
+ if (claim.kind !== 'claimed') throw new Error('expected a claim');
+ await service.markFailed(claim.id);
+
+ expect(await service.claim(input)).toEqual({ kind: 'outcome_unknown' });
+ });
+
+ it('reports a pending claim past the stale window as outcome unknown, not in progress', async () => {
+ const claim = await service.claim(input);
+ if (claim.kind !== 'claimed') throw new Error('expected a claim');
+ const claimedLongAgo = Date.now() - SEND_IDEMPOTENCY_STALE_PENDING_MS - 1000;
+ await repo.update({ id: claim.id }, { expiresAt: new Date(claimedLongAgo + SEND_IDEMPOTENCY_TTL_MS) });
+
+ expect(await service.claim(input)).toEqual({ kind: 'outcome_unknown' });
+ });
+
+ it('reclaims an expired key, even one that completed', async () => {
+ const claim = await service.claim(input);
+ if (claim.kind !== 'claimed') throw new Error('expected a claim');
+ await service.complete(claim.id, { messageId: 'm1' });
+ await repo.update({ id: claim.id }, { expiresAt: new Date(Date.now() - 1000) });
+
+ const again = await service.claim({ ...input, requestHash: 'h2' });
+ expect(again.kind).toBe('claimed');
+ expect(await repo.count()).toBe(1);
+ });
+
+ it('prunes only expired keys', async () => {
+ await service.claim(input);
+ const old = await service.claim({ ...input, key: 'k-old' });
+ if (old.kind !== 'claimed') throw new Error('expected a claim');
+ await repo.update({ id: old.id }, { expiresAt: new Date(Date.now() - 1000) });
+
+ expect(await service.pruneExpired()).toBe(1);
+ expect((await repo.find()).map(r => r.idempotencyKey)).toEqual(['k-1']);
+ });
+
+ it('rethrows a storage error that is not a duplicate key', async () => {
+ await ds.query('DROP TABLE "send_idempotency_keys"');
+ await expect(service.claim(input)).rejects.toThrow(/no such table/);
+ });
+});
+
+describe('isValidIdempotencyKey', () => {
+ it.each(['a', 'order-123:retry', 'x'.repeat(255), '550e8400-e29b-41d4-a716-446655440000'])('accepts %p', key =>
+ expect(isValidIdempotencyKey(key)).toBe(true),
+ );
+
+ it.each(['', ' ', 'has space', 'x'.repeat(256), 'tab\there', 'ünï'])('rejects %p', key =>
+ expect(isValidIdempotencyKey(key)).toBe(false),
+ );
+});
+
+describe('hashSendRequest', () => {
+ it('ignores object key order but not array order, values or route', () => {
+ const base = hashSendRequest('sendText', { chatId: 'c', text: 't', opts: { a: 1, b: 2 } });
+ expect(hashSendRequest('sendText', { opts: { b: 2, a: 1 }, text: 't', chatId: 'c' })).toBe(base);
+ expect(hashSendRequest('sendText', { chatId: 'c', text: 'u', opts: { a: 1, b: 2 } })).not.toBe(base);
+ expect(hashSendRequest('reply', { chatId: 'c', text: 't', opts: { a: 1, b: 2 } })).not.toBe(base);
+ expect(hashSendRequest('sendPoll', { options: ['a', 'b'] })).not.toBe(
+ hashSendRequest('sendPoll', { options: ['b', 'a'] }),
+ );
+ });
+
+ it('treats an absent field like an undefined one', () => {
+ expect(hashSendRequest('sendText', { chatId: 'c', text: undefined })).toBe(
+ hashSendRequest('sendText', { chatId: 'c' }),
+ );
+ });
+});
diff --git a/src/modules/message/idempotency/send-idempotency.service.ts b/src/modules/message/idempotency/send-idempotency.service.ts
new file mode 100644
index 000000000..95d2b052a
--- /dev/null
+++ b/src/modules/message/idempotency/send-idempotency.service.ts
@@ -0,0 +1,180 @@
+import { Injectable, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { createHash } from 'crypto';
+import { LessThan, Repository } from 'typeorm';
+import { SendIdempotencyKey } from '../entities/send-idempotency-key.entity';
+import { isUniqueViolation } from '../../../common/utils/db-errors';
+import { createLogger } from '../../../common/services/logger.service';
+
+/** How long a key stays bound to its first send. Matches the window most HTTP clients retry within. */
+export const SEND_IDEMPOTENCY_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * A 'pending' row older than this is reported as outcome-unknown rather than in-progress: the request
+ * that claimed it has almost certainly died with its node. Both answers are 409 and neither sends, so
+ * the threshold only changes the code a client sees. Generous, because send pacing can hold a send.
+ */
+export const SEND_IDEMPOTENCY_STALE_PENDING_MS = 10 * 60 * 1000;
+
+const PRUNE_INTERVAL_MS = 60 * 60 * 1000;
+
+/** RFC-draft key syntax, kept strict so a key is safe to log and store verbatim: 1-255 visible ASCII. */
+const KEY_PATTERN = /^[\x21-\x7E]{1,255}$/;
+
+export function isValidIdempotencyKey(key: string): boolean {
+ return KEY_PATTERN.test(key);
+}
+
+/**
+ * Canonical JSON: object keys sorted at every depth, so `{a,b}` and `{b,a}` hash the same. Arrays keep
+ * their order, which is meaningful (poll options, contact lists).
+ */
+function canonicalJson(value: unknown): string {
+ if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+ if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+ const entries = Object.keys(value as Record<string, unknown>)
+ .sort()
+ .filter(k => (value as Record<string, unknown>)[k] !== undefined)
+ .map(k => `${JSON.stringify(k)}:${canonicalJson((value as Record<string, unknown>)[k])}`);
+ return `{${entries.join(',')}}`;
+}
+
+/** Fingerprint of one send request: the route plus its canonical body. */
+export function hashSendRequest(route: string, body: unknown): string {
+ return createHash('sha256')
+ .update(route)
+ .update('\n')
+ .update(canonicalJson(body ?? null))
+ .digest('hex');
+}
+
+export type SendIdempotencyClaim =
+ /** This request owns the key and runs the send. */
+ | { kind: 'claimed'; id: string }
+ /** The key already completed this exact request; answer with the stored body, send nothing. */
+ | { kind: 'replay'; body: unknown }
+ /** The key is bound to a different route or body. */
+ | { kind: 'mismatch' }
+ /** Another request holding the key is still running. */
+ | { kind: 'in_progress' }
+ /** An earlier attempt with the key ended without saying whether the message went out. */
+ | { kind: 'outcome_unknown' };
+
+/**
+ * Storage side of the opt-in `Idempotency-Key` header on the send routes (see
+ * SendIdempotencyInterceptor). The claim is a plain INSERT against UNIQUE(sessionId, idempotencyKey),
+ * so two concurrent requests with one key, on one node or several sharing the database, cannot both
+ * run the send.
+ */
+@Injectable()
+export class SendIdempotencyService implements OnModuleInit, OnModuleDestroy {
+ private readonly logger = createLogger('SendIdempotency');
+ private pruneTimer: NodeJS.Timeout | null = null;
+
+ constructor(
+ @InjectRepository(SendIdempotencyKey, 'data')
+ private readonly keys: Repository<SendIdempotencyKey>,
+ ) {}
+
+ onModuleInit(): void {
+ this.pruneTimer = setInterval(() => void this.pruneExpired(), PRUNE_INTERVAL_MS);
+ this.pruneTimer.unref?.();
+ }
+
+ onModuleDestroy(): void {
+ if (this.pruneTimer) clearInterval(this.pruneTimer);
+ this.pruneTimer = null;
+ }
+
+ async claim(input: {
+ sessionId: string;
+ key: string;
+ route: string;
+ requestHash: string;
+ }): Promise<SendIdempotencyClaim> {
+ // Two rounds at most: the second only runs after this call removed an expired row, and a request
+ // that wins the freed key in between is then simply the holder.
+ for (let round = 0; round < 2; round++) {
+ const now = new Date();
+ try {
+ // A bare INSERT, not save(): save() would wrap it in a transaction and, on Postgres, a failed
+ // statement inside one poisons it; the unique violation is the expected answer here.
+ const result = await this.keys.insert({
+ sessionId: input.sessionId,
+ idempotencyKey: input.key,
+ route: input.route,
+ requestHash: input.requestHash,
+ state: 'pending',
+ expiresAt: new Date(now.getTime() + SEND_IDEMPOTENCY_TTL_MS),
+ });
+ return { kind: 'claimed', id: (result.identifiers[0] as { id: string }).id };
+ } catch (error) {
+ if (!isUniqueViolation(error)) throw error;
+ }
+
+ const existing = await this.keys.findOne({
+ where: { sessionId: input.sessionId, idempotencyKey: input.key },
+ });
+ // Released between our insert and this read: take another round at the insert.
+ if (!existing) continue;
+ if (existing.expiresAt.getTime() <= now.getTime()) {
+ await this.keys.delete({ id: existing.id, expiresAt: LessThan(now) });
+ continue;
+ }
+ return this.classify(existing, input.requestHash, now);
+ }
+ return { kind: 'in_progress' };
+ }
+
+ private classify(row: SendIdempotencyKey, requestHash: string, now: Date): SendIdempotencyClaim {
+ if (row.requestHash !== requestHash) return { kind: 'mismatch' };
+ if (row.state === 'completed') return { kind: 'replay', body: row.responseBody };
+ if (row.state === 'failed') return { kind: 'outcome_unknown' };
+ // The claim time is read back from expiresAt, which this service wrote through its own
+ // transformer, rather than from the driver-hydrated createdAt.
+ const claimedAt = row.expiresAt.getTime() - SEND_IDEMPOTENCY_TTL_MS;
+ return now.getTime() - claimedAt > SEND_IDEMPOTENCY_STALE_PENDING_MS
+ ? { kind: 'outcome_unknown' }
+ : { kind: 'in_progress' };
+ }
+
+ /** The send succeeded: store its answer for replay. */
+ async complete(id: string, responseBody: unknown): Promise<void> {
+ await this.keys.update(
+ { id },
+ {
+ state: 'completed',
+ responseBody: responseBody ?? null,
+ },
+ );
+ }
+
+ /** The send was refused before anything reached WhatsApp: free the key for a corrected retry. */
+ async release(id: string): Promise<void> {
+ await this.keys.delete({ id, state: 'pending' });
+ }
+
+ /** The send failed without saying whether the message went out: keep the key taken. */
+ async markFailed(id: string): Promise<void> {
+ await this.keys.update({ id }, { state: 'failed' });
+ }
+
+ /** Delete keys past their window. Runs hourly; a claim also clears an expired row it collides with. */
+ async pruneExpired(now = new Date()): Promise<number> {
+ try {
+ const { affected } = await this.keys.delete({ expiresAt: LessThan(now) });
+ if (affected) {
+ this.logger.debug(`Pruned ${affected} expired send idempotency key(s)`, {
+ action: 'send_idempotency_prune',
+ });
+ }
+ return affected ?? 0;
+ } catch (error) {
+ this.logger.warn('Send idempotency key prune failed', {
+ error: error instanceof Error ? error.message : String(error),
+ action: 'send_idempotency_prune_failed',
+ });
+ return 0;
+ }
+ }
+}
diff --git a/src/modules/message/message-send.service.spec.ts b/src/modules/message/message-send.service.spec.ts
index 8d175b9d4..4c384eadf 100644
--- a/src/modules/message/message-send.service.spec.ts
+++ b/src/modules/message/message-send.service.spec.ts
@@ -1,9 +1,10 @@
import { Test, TestingModule } from '@nestjs/testing';
import { getRepositoryToken } from '@nestjs/typeorm';
-import { FindOperator, In, Repository } from 'typeorm';
+import { DataSource, FindOperator, In, Repository } from 'typeorm';
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import type { LidMapping } from '../../engine/identity/lid-mapping.entity';
-import { BadRequestException, NotFoundException, PayloadTooLargeException } from '@nestjs/common';
+import { BadRequestException, ExecutionContext, NotFoundException, PayloadTooLargeException } from '@nestjs/common';
+import { from, lastValueFrom } from 'rxjs';
import { MessageSendService } from './message-send.service';
import { Message, MessageDirection, MessageStatus } from './entities/message.entity';
import { SessionService } from '../session/session.service';
@@ -16,6 +17,10 @@ import { SsrfBlockedError } from '../../common/security/ssrf-guard';
import { SendPacingService } from './send-pacing.service';
import { EnginePageError } from '../../common/errors/engine-page.error';
import type { MessageProjector } from '../session/message-projector.service';
+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
+import { SendIdempotencyKey } from './entities/send-idempotency-key.entity';
+import { SendIdempotencyService } from './idempotency/send-idempotency.service';
+import { SendIdempotencyInterceptor } from './idempotency/send-idempotency.interceptor';
/** Pacing is off by default in these tests; the governor's own spec covers its behaviour. */
const inertPacing = (): SendPacingService =>
@@ -116,6 +121,51 @@ describe('MessageSendService', () => {
service = module.get<MessageSendService>(MessageSendService);
});
+ it.each(['engine', 'failure bookkeeping'])('prevents a same-key retry after a dispatched %s error', async stage => {
+ const ds = new DataSource({
+ type: 'better-sqlite3',
+ database: ':memory:',
+ entities: [SendIdempotencyKey],
+ synchronize: true,
+ });
+ await ds.initialize();
+ try {
+ const store = new SendIdempotencyService(ds.getRepository(SendIdempotencyKey));
+ const interceptor = new SendIdempotencyInterceptor(store);
+ const body = { chatId: '[email protected]', text: 'Hello' };
+ const context = {
+ getType: () => 'http',
+ getHandler: () => ({ name: 'sendText' }),
+ switchToHttp: () => ({
+ getRequest: () => ({ headers: { 'idempotency-key': 'order-1' }, params: { sessionId: 'sess-1' }, body }),
+ getResponse: () => ({ setHeader: jest.fn() }),
+ }),
+ } as unknown as ExecutionContext;
+ const run = async () =>
+ lastValueFrom(await interceptor.intercept(context, { handle: () => from(service.sendText('sess-1', body)) }));
+ const engineError = new EngineNotReadyError();
+ mockEngine.sendTextMessage.mockRejectedValueOnce(engineError);
+ const responseError = stage === 'engine' ? engineError : new BadRequestException('Failure hook rejected');
+ if (stage !== 'engine') {
+ (hookManager.execute as jest.Mock).mockImplementation((event: string, data: unknown) => {
+ if (event === 'message:failed') return Promise.reject(responseError);
+ return Promise.resolve({ continue: true, data });
+ });
+ }
+
+ await expect(run()).rejects.toBe(responseError);
+ await expect(run()).rejects.toMatchObject({
+ response: { code: 'IDEMPOTENCY_OUTCOME_UNKNOWN' },
+ });
+ expect(mockEngine.sendTextMessage).toHaveBeenCalledTimes(1);
+ expect((await ds.getRepository(SendIdempotencyKey).findOneByOrFail({ idempotencyKey: 'order-1' })).state).toBe(
+ 'failed',
+ );
+ } finally {
+ await ds.destroy();
+ }
+ });
+
// ── sendText ──────────────────────────────────────────────────────
describe('auto-typing before send (SIMULATE_TYPING, on by default)', () => {
diff --git a/src/modules/message/message-send.service.ts b/src/modules/message/message-send.service.ts
index ef287b2f6..3fd595dee 100644
--- a/src/modules/message/message-send.service.ts
+++ b/src/modules/message/message-send.service.ts
@@ -1,5 +1,6 @@
import { Injectable, BadRequestException, Optional } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
+import { markEngineSendFailure } from '../../common/errors/engine-send-failure';
import { InjectRepository } from '@nestjs/typeorm';
import { In, Repository, QueryDeepPartialEntity } from 'typeorm';
import { SessionService } from '../session/session.service';
@@ -207,42 +208,47 @@ export class MessageSendService {
input: unknown,
error: unknown,
): Promise<never> {
- // Only failures that say something about the account's standing feed the breaker: adapters also
- // raise client-fault and engine-state errors from inside this call (a blocked media URL, an
- // unsupported capability, a disconnected socket), and counting those let a client sending bad
- // requests trip the breaker on a healthy session.
- if (countsTowardSendBreaker(error)) {
- this.pacing.recordSendFailure(sessionId);
- // The same classification picks the failures worth a log line. Otherwise an engine-side failure
- // leaves only Nest's generic `[ExceptionsHandler]` line, with no session, chat or message type to
- // correlate it with.
- this.logger.warn(`Send failed in the engine (${type})`, {
- sessionId,
- chatId: message.chatId,
- messageId: message.id,
- error: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
- // An EnginePageError keeps the full in-page summary (stack, own properties) here only.
- ...(error instanceof Error && error.cause instanceof Error ? { cause: error.cause.message } : {}),
- });
+ try {
+ // Only failures that say something about the account's standing feed the breaker: adapters also
+ // raise client-fault and engine-state errors from inside this call (a blocked media URL, an
+ // unsupported capability, a disconnected socket), and counting those let a client sending bad
+ // requests trip the breaker on a healthy session.
+ if (countsTowardSendBreaker(error)) {
+ this.pacing.recordSendFailure(sessionId);
+ // The same classification picks the failures worth a log line. Otherwise an engine-side failure
+ // leaves only Nest's generic `[ExceptionsHandler]` line, with no session, chat or message type to
+ // correlate it with.
+ this.logger.warn(`Send failed in the engine (${type})`, {
+ sessionId,
+ chatId: message.chatId,
+ messageId: message.id,
+ error: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+ // An EnginePageError keeps the full in-page summary (stack, own properties) here only.
+ ...(error instanceof Error && error.cause instanceof Error ? { cause: error.cause.message } : {}),
+ });
+ }
+ await this.saveFailedMessage(message);
+ // Sanitize the hook payload: an SSRF block's raw .message names the resolved internal address
+ // (a recon/DNS-rebind oracle); the client-facing throw below already maps it to a generic
+ // message via toClientFacingError, and the message:failed hook must not expose more than the
+ // client sees. Now that every media/extended sender routes here, this is the chokepoint that
+ // keeps SSRF detail out of plugin hands (bulk does the same via sanitizeBatchError).
+ const hookError =
+ error instanceof SsrfBlockedError
+ ? SSRF_BLOCKED_CLIENT_MESSAGE
+ : error instanceof Error
+ ? error.message
+ : String(error);
+ await this.hookManager.execute(
+ 'message:failed',
+ { sessionId, error: hookError, input, type },
+ { sessionId, source: 'MessageService' },
+ );
+ throw this.toClientFacingError(error);
+ } catch (failure) {
+ // HTTP status alone cannot prove whether an engine accepted the message before failing.
+ throw markEngineSendFailure(failure);
}
- await this.saveFailedMessage(message);
- // Sanitize the hook payload: an SSRF block's raw .message names the resolved internal address
- // (a recon/DNS-rebind oracle) — the client-facing throw below already maps it to a generic
- // message via toClientFacingError, and the message:failed hook must not expose more than the
- // client sees. Now that every media/extended sender routes here, this is the chokepoint that
- // keeps SSRF detail out of plugin hands (bulk does the same via sanitizeBatchError).
- const hookError =
- error instanceof SsrfBlockedError
- ? SSRF_BLOCKED_CLIENT_MESSAGE
- : error instanceof Error
- ? error.message
- : String(error);
- await this.hookManager.execute(
- 'message:failed',
- { sessionId, error: hookError, input, type },
- { sessionId, source: 'MessageService' },
- );
- throw this.toClientFacingError(error);
}
/**
diff --git a/src/modules/message/message.controller.spec.ts b/src/modules/message/message.controller.spec.ts
index ce85f336f..3fd848b6d 100644
--- a/src/modules/message/message.controller.spec.ts
+++ b/src/modules/message/message.controller.spec.ts
@@ -7,6 +7,7 @@ import { MessageController } from './message.controller';
import { MessageService } from './message.service';
import { BulkMessageService } from './bulk-message.service';
import { ChatScopeService } from '../auth/chat-scope.service';
+import { SendIdempotencyService } from './idempotency/send-idempotency.service';
import { CHAT_SCOPED_KEY } from '../auth/decorators/auth.decorators';
import type { ApiKey } from '../auth/entities/api-key.entity';
import type { SendBulkMessageDto } from './dto/bulk-message.dto';
@@ -183,6 +184,8 @@ describe('MessageController - caller-supplied batch ids', () => {
{ provide: MessageService, useValue: messages },
{ provide: BulkMessageService, useValue: bulk },
ChatScopeService,
+ // The send routes carry SendIdempotencyInterceptor; this test sends no Idempotency-Key.
+ { provide: SendIdempotencyService, useValue: {} },
],
}).compile();
const app = moduleRef.createNestApplication();
diff --git a/src/modules/message/message.controller.ts b/src/modules/message/message.controller.ts
index a4a2f6782..b2c186876 100644
--- a/src/modules/message/message.controller.ts
+++ b/src/modules/message/message.controller.ts
@@ -60,6 +60,7 @@ import {
MESSAGE_NOT_FOUND_404,
RECIPIENT_UNREACHABLE_400,
} from '../../common/openapi/engine-status-responses';
+import { IdempotentSend } from './idempotency/idempotent-send.decorator';
// whatsapp-web.js drops these sends without an error, so its adapter refuses them up front
// (ensureSendable in wwebjs-messaging.ts). The contract keeps one entry per status, so on a route
@@ -159,6 +160,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('send-text')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Send a text message' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -182,6 +184,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('send-template')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Render a stored text template and send it as a text message' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -205,6 +208,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('send-image')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Send an image message' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -233,6 +237,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('send-video')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Send a video message' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -259,6 +264,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('send-audio')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Send an audio/voice message' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -285,6 +291,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('send-document')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Send a document/file' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -313,6 +320,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('send-location')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Send a location message' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -331,6 +339,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('send-contact')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Send a contact card message' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -349,6 +358,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('send-sticker')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Send a sticker message' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -375,6 +385,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('send-poll')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Send a native WhatsApp poll' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -399,6 +410,7 @@ export class MessageController {
@ChatQuotedAllowed()
@ChatScoped('fenced')
@Post('reply')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Reply to a message' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@@ -448,6 +460,7 @@ export class MessageController {
@ChatScoped('fenced')
@Post('forward')
+ @IdempotentSend()
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Forward a message to another chat' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
diff --git a/src/modules/message/message.module.ts b/src/modules/message/message.module.ts
index f4afe8145..025405f97 100644
--- a/src/modules/message/message.module.ts
+++ b/src/modules/message/message.module.ts
@@ -14,11 +14,14 @@ import { Message } from './entities/message.entity';
import { Session } from '../session/entities/session.entity';
import { SendPacingService } from './send-pacing.service';
import { MessageBatch } from './entities/message-batch.entity';
+import { SendIdempotencyKey } from './entities/send-idempotency-key.entity';
+import { SendIdempotencyService } from './idempotency/send-idempotency.service';
+import { SendIdempotencyInterceptor } from './idempotency/send-idempotency.interceptor';
import { PLUGIN_MESSAGE_PORT } from '../../core/plugins/plugin-host-ports';
@Module({
imports: [
- TypeOrmModule.forFeature([Message, MessageBatch, Session], 'data'),
+ TypeOrmModule.forFeature([Message, MessageBatch, Session, SendIdempotencyKey], 'data'),
SessionModule,
TemplateModule,
ChatMediaModule,
@@ -32,6 +35,8 @@ import { PLUGIN_MESSAGE_PORT } from '../../core/plugins/plugin-host-ports';
PendingMessageReaperService,
MessageRetentionService,
SendPacingService,
+ SendIdempotencyService,
+ SendIdempotencyInterceptor,
// Binds the core-owned plugin capability port to this module's service. The plugin runtime
// resolves the token lazily via ModuleRef (PluginHostServices), which keeps its provider cycle
// broken; this adapter is how core reaches the service without importing it.
diff --git a/src/modules/session/session-proxy.interceptor.ts b/src/modules/session/session-proxy.interceptor.ts
index e4b324a6e..8a5cb0580 100644
--- a/src/modules/session/session-proxy.interceptor.ts
+++ b/src/modules/session/session-proxy.interceptor.ts
@@ -22,14 +22,18 @@ import { normalizeIp } from '../../common/utils/ip';
/**
* The request headers a forwarded call carries over. Everything else is this hop's business.
* content-type is not among them: forward() sends every body as JSON and labels it so itself.
+ * idempotency-key travels so the OWNER claims it: the claim is part of the request's meaning, not
+ * of this hop.
*/
-const FORWARDED_REQUEST_HEADERS = ['x-api-key', 'authorization', 'accept'] as const;
+const FORWARDED_REQUEST_HEADERS = ['x-api-key', 'authorization', 'accept', 'idempotency-key'] as const;
/** The response headers relayed back. Deliberately short: hop-by-hop headers must not leak through. */
const RELAYED_RESPONSE_HEADERS = [
'content-type',
'content-disposition',
'x-content-type-options',
+ // Tells the client the owner answered from a stored Idempotency-Key response, not a new send.
+ 'idempotent-replayed',
// Throttle answers come from the OWNER's counters, so the client must be told what the owner
// said: without these a forwarded 429 arrives with no indication of when to retry.
// ProxyAwareThrottlerGuard sets the plain Retry-After that HTTP clients read; the base throttler