Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

feat(chat-media): archive verified media atomically

Yudhi Armyndharis9ee4db47f38c
diff --git a/.env.example b/.env.example
index 19b856b7a..928b53595 100644
--- a/.env.example
+++ b/.env.example
@@ -655,6 +655,14 @@ WEBHOOK_SSRF_PROTECT=true
# media columns; the message row itself is never deleted by this. A negative or malformed value
# fails the boot.
# CHAT_MEDIA_ARCHIVE_TTL_DAYS=0 # default 0 (keep forever)
+# What happens to a message row's inline base64 once its media is archived. "inline" (default)
+# keeps it, so archived media is stored twice. "archive" replaces it with the omitted marker
+# ({ mimetype, filename?, omitted: true, sizeBytes, archived: true }) after the file is written and
+# read back intact, so each file is stored once and served by the media route above. Anything that
+# goes wrong keeps the inline copy. Needs CHAT_MEDIA_ARCHIVE_ENABLED=true (boot fails otherwise);
+# media over CHAT_MEDIA_ARCHIVE_MAX_BYTES is not archived and stays inline; with a TTL above, an
+# expired file takes the only copy with it. Rows stored before the switch keep their inline copy.
+# MESSAGE_INLINE_MEDIA=inline # default inline
# Orphaned chat-media reconciliation: how often the sweep re-lists chat-media files to find ones no
# row references (crash leftovers), and how long a file must be seen unreferenced before deletion.
# Unset takes the default; a value that is not a positive integer fails the boot, and so does a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d87c16358..9f9db9eb5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Expose caller-supplied send idempotency keys in all five SDKs.
- Add optional 24-hour idempotency keys to twelve single-recipient send routes.
+- Add opt-in archive-only chat media with dashboard previews.
+
### Fixed
- Preserve webhook outbox payloads until delivery or durable failure storage succeeds.
diff --git a/dashboard/src/components/chats/ArchivedMediaPreview.test.ts b/dashboard/src/components/chats/ArchivedMediaPreview.test.ts
new file mode 100644
index 000000000..509705b66
--- /dev/null
+++ b/dashboard/src/components/chats/ArchivedMediaPreview.test.ts
@@ -0,0 +1,106 @@
+// Render test for the archive-only media preview: an `{ omitted: true, archived: true }` marker must
+// still show its image/video/audio inline (fetched from the media route), release the object URL it
+// made, and fall back to the download button when the bytes cannot be fetched.
+import '../../test-helpers/register-hooks.ts';
+import { test, before, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createElement } from 'react';
+
+type RTL = typeof import('@testing-library/react');
+
+let rtl: RTL;
+let ArchivedMediaPreview: typeof import('./ArchivedMediaPreview.tsx').default;
+
+const created: string[] = [];
+const revoked: string[] = [];
+
+before(async () => {
+ const { installJsdomGlobals } = await import('../../test-helpers/jsdom.ts');
+ await installJsdomGlobals();
+ rtl = await import('@testing-library/react');
+ ({ default: ArchivedMediaPreview } = await import('./ArchivedMediaPreview.tsx'));
+ // jsdom implements neither.
+ URL.createObjectURL = (): string => {
+ const url = `blob:mock-${created.length}`;
+ created.push(url);
+ return url;
+ };
+ URL.revokeObjectURL = (url: string): void => void revoked.push(url);
+});
+
+afterEach(() => {
+ rtl.cleanup();
+ created.length = 0;
+ revoked.length = 0;
+});
+
+const fallback = createElement('button', { type: 'button', className: 'message-media-omitted' }, 'Media');
+
+test('an archived image loads once from the media route and renders from an object URL', async () => {
+ let calls = 0;
+ const { container, unmount } = rtl.render(
+ createElement(ArchivedMediaPreview, {
+ kind: 'image',
+ alt: 'photo.jpg',
+ fallback,
+ load: async () => {
+ calls += 1;
+ return new Blob(['x'], { type: 'image/jpeg' });
+ },
+ }),
+ );
+ const img = await rtl.waitFor(() => {
+ const found = container.querySelector('img.chat-image-media');
+ assert.ok(found, 'the archived image did not render');
+ return found as HTMLImageElement;
+ });
+ assert.equal(img.getAttribute('src'), 'blob:mock-0');
+ assert.equal(calls, 1, 'the bytes are fetched exactly once');
+ assert.deepEqual(revoked, [], 'the URL stays valid while the image is on screen');
+ unmount();
+ assert.deepEqual(revoked, ['blob:mock-0'], 'unmounting releases the object URL');
+});
+
+test('video and audio render their own elements', async () => {
+ for (const [kind, selector] of [
+ ['video', 'video.chat-video-media'],
+ ['audio', 'audio.chat-audio-media'],
+ ] as const) {
+ const { container } = rtl.render(
+ createElement(ArchivedMediaPreview, { kind, fallback, load: async () => new Blob(['x']) }),
+ );
+ await rtl.waitFor(() => assert.ok(container.querySelector(selector), `${kind} did not render`));
+ rtl.cleanup();
+ }
+});
+
+test('a failed fetch falls back to the download button instead of a broken preview', async () => {
+ const { container } = rtl.render(
+ createElement(ArchivedMediaPreview, {
+ kind: 'image',
+ fallback,
+ load: async () => {
+ throw new Error('404');
+ },
+ }),
+ );
+ await rtl.waitFor(() => assert.ok(container.querySelector('button.message-media-omitted')));
+ assert.equal(container.querySelector('img'), null);
+ assert.deepEqual(created, [], 'no object URL is made for a failed fetch');
+});
+
+test('a response landing after unmount makes no object URL', async () => {
+ let resolve!: (blob: Blob) => void;
+ const { unmount } = rtl.render(
+ createElement(ArchivedMediaPreview, {
+ kind: 'image',
+ fallback,
+ load: () => new Promise<Blob>(r => (resolve = r)),
+ }),
+ );
+ await rtl.waitFor(() => assert.ok(resolve, 'the fetch did not start'));
+ unmount();
+ resolve(new Blob(['x']));
+ await new Promise(r => setTimeout(r, 0));
+ assert.deepEqual(created, [], 'a late response must not leak a URL nothing will revoke');
+});
diff --git a/dashboard/src/components/chats/ArchivedMediaPreview.tsx b/dashboard/src/components/chats/ArchivedMediaPreview.tsx
new file mode 100644
index 000000000..3960bc609
--- /dev/null
+++ b/dashboard/src/components/chats/ArchivedMediaPreview.tsx
@@ -0,0 +1,125 @@
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { Loader2 } from 'lucide-react';
+
+export type ArchivedMediaKind = 'image' | 'video' | 'audio';
+
+interface ArchivedMediaPreviewProps {
+ kind: ArchivedMediaKind;
+ /** Fetches the archived bytes (the per-message media route). Called at most once per mount. */
+ load: () => Promise<Blob>;
+ alt?: string;
+ /** Rendered instead of the preview when the fetch fails , the download button, so the bytes stay reachable. */
+ fallback: ReactNode;
+ measureMedia?: (el: Element | null) => void;
+ onMediaLoad?: (event?: { currentTarget: Element | null }) => void;
+}
+
+type PreviewState = { phase: 'waiting' | 'loading' | 'failed' } | { phase: 'ready'; url: string };
+
+// An inline preview for media whose list payload is the `{ omitted: true, archived: true }` marker ,
+// what MESSAGE_INLINE_MEDIA=archive leaves once the bytes are verified on the archive store. The
+// archive is the only copy then, so without this an image would read as a bare "Media" button where
+// it used to render. A plain over-budget marker (no `archived`) keeps the click-to-download button:
+// those bytes may be multi-megabyte inline payloads, and fetching each one as it scrolls past would
+// turn browsing into bulk download.
+//
+// Fetched lazily, once the bubble nears the viewport, so opening a media-heavy chat does not fire one
+// request per archived message at once. Where IntersectionObserver is unavailable (old browsers, the
+// jsdom test runtime) it loads immediately rather than never. The object URL is revoked on unmount so
+// scrolling through a long thread does not accumulate blobs.
+function ArchivedMediaPreview({ kind, load, alt, fallback, measureMedia, onMediaLoad }: ArchivedMediaPreviewProps) {
+ const [state, setState] = useState<PreviewState>({ phase: 'waiting' });
+ const anchorRef = useRef<HTMLDivElement | null>(null);
+ // `load` is usually an inline arrow, so a fresh identity every render; holding it in a ref keeps
+ // the effects below from re-running (and re-fetching) on each parent render.
+ const loadRef = useRef(load);
+ useEffect(() => {
+ loadRef.current = load;
+ });
+ // The object URL the ready render points at. Revoked on unmount only , the phase never leaves
+ // `ready`, so the URL stays valid for as long as the element showing it exists.
+ const urlRef = useRef<string | null>(null);
+ useEffect(
+ () => () => {
+ if (urlRef.current) URL.revokeObjectURL(urlRef.current);
+ urlRef.current = null;
+ },
+ [],
+ );
+
+ // Phase 1: wait until the bubble is near the viewport.
+ useEffect(() => {
+ if (state.phase !== 'waiting') return undefined;
+ const el = anchorRef.current;
+ if (!el || typeof IntersectionObserver === 'undefined') {
+ setState({ phase: 'loading' });
+ return undefined;
+ }
+ const observer = new IntersectionObserver(
+ entries => {
+ if (entries.some(entry => entry.isIntersecting)) {
+ observer.disconnect();
+ setState({ phase: 'loading' });
+ }
+ },
+ // A screen's worth of lead so the bytes are usually there by the time the bubble scrolls in.
+ { rootMargin: '600px 0px' },
+ );
+ observer.observe(el);
+ return () => observer.disconnect();
+ }, [state.phase]);
+
+ // Phase 2: fetch once. A response landing after unmount is dropped rather than turned into a URL
+ // nothing would ever revoke.
+ useEffect(() => {
+ if (state.phase !== 'loading') return undefined;
+ let cancelled = false;
+ loadRef
+ .current()
+ .then(blob => {
+ if (cancelled) return;
+ const url = URL.createObjectURL(blob);
+ urlRef.current = url;
+ setState({ phase: 'ready', url });
+ })
+ .catch(() => {
+ if (!cancelled) setState({ phase: 'failed' });
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [state.phase]);
+
+ if (state.phase === 'failed') return <>{fallback}</>;
+
+ if (state.phase !== 'ready') {
+ return (
+ <div ref={anchorRef} className="message-media-omitted message-media-archived-loading" aria-busy="true">
+ <Loader2 size={14} className="animate-spin" />
+ </div>
+ );
+ }
+
+ switch (kind) {
+ case 'image':
+ return (
+ <div className="message-media-image">
+ <img src={state.url} alt={alt ?? ''} className="chat-image-media" ref={measureMedia} onLoad={onMediaLoad} />
+ </div>
+ );
+ case 'video':
+ return (
+ <div className="message-media-video">
+ <video ref={measureMedia} src={state.url} controls className="chat-video-media" onLoadedData={onMediaLoad} />
+ </div>
+ );
+ case 'audio':
+ return (
+ <div className="message-media-audio">
+ <audio src={state.url} controls className="chat-audio-media" />
+ </div>
+ );
+ }
+}
+
+export default ArchivedMediaPreview;
diff --git a/dashboard/src/components/chats/ChatThread.test.ts b/dashboard/src/components/chats/ChatThread.test.ts
index f224429d9..1f59f6b09 100644
--- a/dashboard/src/components/chats/ChatThread.test.ts
+++ b/dashboard/src/components/chats/ChatThread.test.ts
@@ -172,3 +172,48 @@ test('a document sent by URL opens in a new tab instead of navigating the dashbo
assert.equal(inline.getAttribute('target'), null);
assert.equal(inline.getAttribute('download'), 'inline.pdf');
});
+
+test('archive-only media previews inline from the media route; a plain omitted marker and a document keep the button', async () => {
+ // MESSAGE_INLINE_MEDIA=archive leaves `{ omitted, archived }` on the row: the image rendered inline
+ // before, so it must still. The over-budget marker (no `archived`) must not fetch on render, and a
+ // document has nothing to preview.
+ const media = (id: string, type: ChatMessageView['type'], archived: boolean): ChatMessageView => ({
+ ...PROMPT,
+ id,
+ waMessageId: `wamid.${id}`,
+ body: '',
+ type,
+ metadata: { media: { mimetype: 'image/jpeg', filename: `${id}.jpg`, omitted: true, sizeBytes: 10, archived } },
+ });
+ const fetched: string[] = [];
+ const fetchOriginal = globalThis.fetch;
+ const createOriginal = URL.createObjectURL;
+ const revokeOriginal = URL.revokeObjectURL;
+ globalThis.fetch = (async (input: RequestInfo | URL) => {
+ fetched.push(String(input));
+ return new Response(new Blob(['x'], { type: 'image/jpeg' }), { status: 200 });
+ }) as typeof fetch;
+ URL.createObjectURL = () => 'blob:archived';
+ URL.revokeObjectURL = () => {};
+ try {
+ const { container } = renderThread('viewer', [
+ media('arch', 'image', true),
+ media('plain', 'image', false),
+ media('doc', 'document', true),
+ ]);
+ const img = await rtl.waitFor(() => {
+ const found = container.querySelector('[data-wa-message-id="wamid.arch"] img.chat-image-media');
+ assert.ok(found, 'the archived image did not preview');
+ return found;
+ });
+ assert.equal(img.getAttribute('src'), 'blob:archived');
+ assert.equal(fetched.length, 1, 'only the archived image is fetched on render');
+ assert.match(fetched[0], /\/messages\/.+\/wamid\.arch\/media$/);
+ assert.ok(container.querySelector('[data-wa-message-id="wamid.plain"] button.message-media-omitted'));
+ assert.ok(container.querySelector('[data-wa-message-id="wamid.doc"] button.message-media-omitted'));
+ } finally {
+ globalThis.fetch = fetchOriginal;
+ URL.createObjectURL = createOriginal;
+ URL.revokeObjectURL = revokeOriginal;
+ }
+});
diff --git a/dashboard/src/components/chats/ChatThread.tsx b/dashboard/src/components/chats/ChatThread.tsx
index 498309b10..0aa9c0f0f 100644
--- a/dashboard/src/components/chats/ChatThread.tsx
+++ b/dashboard/src/components/chats/ChatThread.tsx
@@ -11,6 +11,7 @@ import {
type ChatMessageView,
} from '../../utils/chatMessages';
import { shouldFetchOlderMessages } from '../../utils/scrollDecision';
+import ArchivedMediaPreview, { type ArchivedMediaKind } from './ArchivedMediaPreview';
import MessageBody from './MessageBody';
// Stable per-sender colour for group message labels, like WhatsApp gives each participant a colour.
@@ -318,7 +319,7 @@ function ChatThread({
// Not a plain label: the bytes exist behind the per-message media route, so this is the
// only handle the viewer has on them.
const fetchState = msg.waMessageId ? mediaFetch[msg.waMessageId] : undefined;
- return (
+ const downloadButton = (
<button
type="button"
className="message-media-omitted"
@@ -332,6 +333,32 @@ function ChatThread({
)}
</button>
);
+ // `archived` marks a copy MESSAGE_INLINE_MEDIA=archive moved off the row once the archive
+ // store held it: the bubble rendered inline before, so it previews inline still, fetched
+ // lazily from the same route. Documents keep the button (there is nothing to preview),
+ // and so does a plain over-budget marker , see ArchivedMediaPreview for why.
+ const previewKind: ArchivedMediaKind | null =
+ msg.type === 'image' || msg.type === 'sticker'
+ ? 'image'
+ : msg.type === 'video'
+ ? 'video'
+ : msg.type === 'audio' || msg.type === 'voice'
+ ? 'audio'
+ : null;
+ const waMessageId = msg.waMessageId;
+ if (mediaInfo.archived && previewKind && sessionId && waMessageId) {
+ return (
+ <ArchivedMediaPreview
+ kind={previewKind}
+ load={() => sessionApi.getMessageMediaBlob(sessionId, activeChat.id, waMessageId)}
+ alt={mediaInfo.filename || t('chats.media.image')}
+ fallback={downloadButton}
+ measureMedia={measureMedia}
+ onMediaLoad={onMediaLoad}
+ />
+ );
+ }
+ return downloadButton;
}
const mediaSrc = getMediaSrc(mediaInfo);
if (!mediaSrc) return null;
diff --git a/dashboard/src/services/api.ts b/dashboard/src/services/api.ts
index 37362f55e..0de77199a 100644
--- a/dashboard/src/services/api.ts
+++ b/dashboard/src/services/api.ts
@@ -316,7 +316,15 @@ export interface ChatMessage {
timestamp?: number;
createdAt: string;
metadata?: {
- media?: { mimetype: string; filename?: string; data?: string; omitted?: boolean; sizeBytes?: number };
+ media?: {
+ mimetype: string;
+ filename?: string;
+ data?: string;
+ omitted?: boolean;
+ sizeBytes?: number;
+ /** With `omitted`: the inline copy was dropped because the chat-media archive holds the bytes. */
+ archived?: boolean;
+ };
quotedMessage?: { id: string; body: string };
reactions?: Record<string, string>;
call?: { video: boolean; missed: boolean };
@@ -378,6 +386,7 @@ export interface EngineHistoryMessage {
data?: string;
omitted?: boolean;
sizeBytes?: number;
+ archived?: boolean;
};
quotedMessage?: { id: string; body: string };
location?: { latitude: number; longitude: number; description?: string; address?: string; url?: string };
diff --git a/dashboard/src/utils/chatMessages.ts b/dashboard/src/utils/chatMessages.ts
index a818fbabb..588f1addf 100644
--- a/dashboard/src/utils/chatMessages.ts
+++ b/dashboard/src/utils/chatMessages.ts
@@ -216,6 +216,11 @@ export type MessageMedia = {
data?: string;
omitted?: boolean;
sizeBytes?: number;
+ /**
+ * Set alongside `omitted` when MESSAGE_INLINE_MEDIA=archive dropped the inline copy because the
+ * chat-media archive holds the bytes , the media route serves them, so the thread previews inline.
+ */
+ archived?: boolean;
};
export const getMediaSrc = (media?: MessageMedia): string => {
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index f46cb97c1..7a25810a9 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -128,6 +128,7 @@ services:
- CHAT_MEDIA_ARCHIVE_OUTBOUND=${CHAT_MEDIA_ARCHIVE_OUTBOUND:-}
- CHAT_MEDIA_ARCHIVE_MAX_BYTES=${CHAT_MEDIA_ARCHIVE_MAX_BYTES:-}
- CHAT_MEDIA_ARCHIVE_TTL_DAYS=${CHAT_MEDIA_ARCHIVE_TTL_DAYS:-}
+ - MESSAGE_INLINE_MEDIA=${MESSAGE_INLINE_MEDIA:-}
- CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS=${CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS:-}
- CHAT_MEDIA_ORPHAN_GRACE_MS=${CHAT_MEDIA_ORPHAN_GRACE_MS:-}
- SEND_PACING_ENABLED=${SEND_PACING_ENABLED:-}
diff --git a/docker-compose.yml b/docker-compose.yml
index 34b4ee732..858527745 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -201,6 +201,7 @@ services:
- CHAT_MEDIA_ARCHIVE_OUTBOUND=${CHAT_MEDIA_ARCHIVE_OUTBOUND:-}
- CHAT_MEDIA_ARCHIVE_MAX_BYTES=${CHAT_MEDIA_ARCHIVE_MAX_BYTES:-}
- CHAT_MEDIA_ARCHIVE_TTL_DAYS=${CHAT_MEDIA_ARCHIVE_TTL_DAYS:-}
+ - MESSAGE_INLINE_MEDIA=${MESSAGE_INLINE_MEDIA:-}
- CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS=${CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS:-}
- CHAT_MEDIA_ORPHAN_GRACE_MS=${CHAT_MEDIA_ORPHAN_GRACE_MS:-}
# Send pacing (opt-in anti-ban governor). Forwarded explicitly for the same reason as the
diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.md
index 58f703c54..11683c2b1 100644
--- a/docs/03-system-architecture.md
+++ b/docs/03-system-architecture.md
@@ -1312,6 +1312,8 @@ also writes status media through `putFile` (under `statuses/`) and sweeps orphan
`deleteFile`. Incoming and outgoing message media is returned inline to REST/webhook consumers and is
**not** written through `StorageService` unless `CHAT_MEDIA_ARCHIVE_ENABLED=true`, which archives a copy
under `chat-media/<sessionId>/` (media this account sent also needs `CHAT_MEDIA_ARCHIVE_OUTBOUND=true`).
+That copy is in addition to the inline one unless `MESSAGE_INLINE_MEDIA=archive`, which replaces the
+row's inline base64 with an `{ omitted: true, archived: true }` marker once the file reads back intact.
On S3 every key sits under the `S3_KEY_PREFIX` root (default `media/`).
**MinIO is not a separate type** β€” it is the `s3` backend. The S3 client is created from credentials
alone, so plain AWS S3 works with no endpoint (the SDK derives one from the region); `S3_ENDPOINT` is
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index b9e45d1c6..2433d1a07 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -855,8 +855,8 @@ flowchart LR
OpenWA runs **two separate TypeORM connections**, each with its own migrations directory and CLI DataSource:
-| Connection | DataSource | Migrations dir | Owns |
-| ---------- | --------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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 |
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index fe6b0354d..2da23139c 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -1353,7 +1353,7 @@ Get persisted message history for a session from the local DB (paginated, filter
Each `Message`: `{ id (uuid), sessionId, waMessageId (string|null), chatId, from, to, chatName (string|null; the sender's push name, or their saved contact name when no push name was reported), author (string|null; the real sender of a group, status or broadcast-list message, where from holds the group, status@broadcast or list id; on Baileys a list message the account received is filed under the sender, so from is the sender too), body (string|null), type, direction ('incoming'|'outgoing'), timestamp (number|null), metadata (object|null), mediaPath (string|null; storage key of archived media), mediaMimetype (string|null), status ('pending'|'sent'|'delivered'|'read'|'failed'), createdAt (ISO date) }`. Ordered by `createdAt` DESC, then by a dialect-dependent second key. The tiebreaker matters: `createdAt` is not unique (SQLite stores whole seconds, a PostgreSQL bulk write ties every row it inserts, and a history backfill carries WhatsApp's own second-resolution timestamp), and without a total order two pages of one walk can repeat a row and omit another. On SQLite the second key is `rowid`, the stored insertion sequence, so messages sharing a second come back in the order they arrived. PostgreSQL has no equivalent (`ctid` moves on every ack update), so it keeps `id`, a random uuid: the walk is equally correct there, but a same-second group is not in arrival order. Note that `offset` still addresses a position by count, so a list taking concurrent writes can shift under a walk: a message arriving mid-walk pushes every older row down one, and the next page re-serves a row the previous one already returned. Pass `after` instead to walk a live chat safely; it anchors on the last row you received, which an arriving message cannot move. The response is the raw service object (no envelope). Unlike the live `IncomingMessage` shape below, this persisted `Message` does **not** carry `kind` β€” re-derive the chat kind from `chatId` (see `ChatKind` / `chatKind()`) if needed. When present, `metadata` may include `media`, `quotedMessage`, `call`, `reactions`, and, for Baileys inbound business prompts, `buttons: [{ id, text }, …]` so a client (including the dashboard Chats thread) can re-render the choices after reload and tap them via [`POST .../click-button`](#post-apisessionssessionidmessagesclick-button).
-> **Inline media is carried up to a budget, then omitted.** `MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES` (8 MiB of encoded base64 by default) bounds how much inline media one response may hold across its rows. A row is not a bounded object β€” `limit` is clamped to `[1,100]` but each row can carry its base64 in `metadata.media.data`, so a page of media rows could otherwise reach hundreds of megabytes and fail the read outright. The budget is spent newest-first, matching the `createdAt` DESC order above, so a page that cannot carry everything keeps the most recent media. Past it a payload is replaced with `{ mimetype, filename?, omitted: true, sizeBytes }` β€” the same marker the engine emits for inbound media over `MEDIA_DOWNLOAD_MAX_BYTES` β€” and the bytes remain available from [`GET /messages/:chatId/:messageId/media`](#get-apisessionssessionidmessageschatidmessageidmedia). Two rules bound the edges: the newest payload is always inlined even when it alone exceeds the budget (otherwise a single large photo would be permanently unreadable through this route), and a budget of `0` means "never inline" and grants no such allowance. The knob is validated at boot β€” `8MiB` would parse to 8 bytes β€” and is forwarded by both compose files. The MCP `MessageList` tool shares this path and the same budget.
+> **Inline media is carried up to a budget, then omitted.** `MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES` (8 MiB of encoded base64 by default) bounds how much inline media one response may hold across its rows. A row is not a bounded object , `limit` is clamped to `[1,100]` but each row can carry its base64 in `metadata.media.data`, so a page of media rows could otherwise reach hundreds of megabytes and fail the read outright. The budget is spent newest-first, matching the `createdAt` DESC order above, so a page that cannot carry everything keeps the most recent media. Past it a payload is replaced with `{ mimetype, filename?, omitted: true, sizeBytes }` , the same marker the engine emits for inbound media over `MEDIA_DOWNLOAD_MAX_BYTES` , and the bytes remain available from [`GET /messages/:chatId/:messageId/media`](#get-apisessionssessionidmessageschatidmessageidmedia). Two rules bound the edges: the newest payload is always inlined even when it alone exceeds the budget (otherwise a single large photo would be permanently unreadable through this route), and a budget of `0` means "never inline" and grants no such allowance. The knob is validated at boot , `8MiB` would parse to 8 bytes , and is forwarded by both compose files. The MCP `MessageList` tool shares this path and the same budget. A row stored under `MESSAGE_INLINE_MEDIA=archive` arrives with the marker already in place, plus `archived: true` , its bytes live only in the chat-media archive, behind the same media route (see that route for the mode).
**Errors:** `400` `after` names no message in this session Β· `401` missing/invalid API key Β· `403` a key restricted to selected chats sent no `chatId`, or one outside its allowlist
@@ -1555,6 +1555,22 @@ The inline fallback also keeps an inbound message's media downloadable after
`CHAT_MEDIA_ARCHIVE_TTL_DAYS` retention purges the archived file, since retention leaves the inline
copy in place.
+**Archive-only storage (`MESSAGE_INLINE_MEDIA=archive`).** By default an archived file is a second
+copy: the row keeps its inline base64 too. Setting `MESSAGE_INLINE_MEDIA=archive` (it needs
+`CHAT_MEDIA_ARCHIVE_ENABLED=true`; the boot fails otherwise) stores each archived file once: after
+the file is written, read back byte for byte and the row points at it, the row's
+`metadata.media` is replaced with `{ mimetype, filename?, omitted: true, sizeBytes, archived: true }`,
+and this route becomes the only way to the bytes. Any failure along the way (a store that does not
+read back intact, a row revoked or re-pointed meanwhile) keeps the inline copy, so the mode can miss
+a saving but not lose media. What it does not cover: media over `CHAT_MEDIA_ARCHIVE_MAX_BYTES` is
+not archived and stays inline; outbound media is archived (and replaced) only with
+`CHAT_MEDIA_ARCHIVE_OUTBOUND=true`; rows stored before the switch keep their inline copy. Two
+consequences to weigh before enabling it: with a non-zero `CHAT_MEDIA_ARCHIVE_TTL_DAYS`, retention
+now removes the only copy, after which this route answers `404`; and a database export no longer
+carries those bytes, so back up the media store alongside the database. Webhook payloads carry the
+in-memory engine message rather than the row, so they are unaffected. The dashboard previews
+archived images, video and audio inline by fetching them from this route.
+
A revoked message (deleted for everyone, or through `POST /messages/delete`) has no media: its row is
cleared on revoke, and this route answers `404` for it.
diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.md
index a40a897b1..c9a2f24ea 100644
--- a/docs/10-devops-infrastructure.md
+++ b/docs/10-devops-infrastructure.md
@@ -383,6 +383,8 @@ LOG_FORMAT=json
# chat-media/<sessionId>/; media this account sent also needs CHAT_MEDIA_ARCHIVE_OUTBOUND=true.
# With the archive off, chat media stays inline on the message row (up to MEDIA_DOWNLOAD_MAX_BYTES),
# where GET /api/sessions/:sessionId/messages/:chatId/:messageId/media still serves it.
+# With the archive on, the row keeps its inline copy too unless MESSAGE_INLINE_MEDIA=archive, which
+# makes the store the only copy of archived media: back it up alongside the database.
# On S3 every key sits under the S3_KEY_PREFIX root (default media/, so media/chat-media/...).
# While S3 has not been reachable since boot, or its credentials are missing, files go to
# STORAGE_LOCAL_PATH instead.
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.md
index d1e5414d6..3ac62d2d0 100644
--- a/docs/11-operational-runbooks.md
+++ b/docs/11-operational-runbooks.md
@@ -994,7 +994,8 @@ find /backups -name "*.tar.gz" -mtime +30 -delete
# keeps the old environment. Sessions reconnect on their own only with AUTO_START_SESSIONS=true;
# otherwise POST /api/sessions/{sessionId}/start each one. Expiry clears the file and the row's
# media columns. Under the production compose the media lives in the openwa_openwa-data volume,
-# not in ./data in the checkout.
+# not in ./data in the checkout. With MESSAGE_INLINE_MEDIA=archive the expired file is the only
+# copy (no inline fallback), so expiry makes that media unreadable for good.
# 4. Verify
df -h
diff --git a/src/config/configuration.ts b/src/config/configuration.ts
index 8d0e3703d..ba849a4fd 100644
--- a/src/config/configuration.ts
+++ b/src/config/configuration.ts
@@ -456,6 +456,11 @@ export default () => ({
const n = parseInt(process.env.CHAT_MEDIA_ORPHAN_GRACE_MS ?? '', 10);
return Number.isFinite(n) && n > 0 ? n : 60 * 60 * 1000;
})(),
+ // What happens to a row's inline base64 once its media is archived. 'inline' (the default) keeps
+ // it, as before. 'archive' replaces it with the omitted marker after the file is stored and
+ // verified, so the bytes live once, in the file store; reads go through the media route.
+ // Validated at boot to need CHAT_MEDIA_ARCHIVE_ENABLED=true.
+ inlineMode: process.env.MESSAGE_INLINE_MEDIA === 'archive' ? ('archive' as const) : ('inline' as const),
},
// Session ownership across processes. A session's engine runs in exactly one process; these
diff --git a/src/config/env-precedence.ts b/src/config/env-precedence.ts
index 342b9f6a1..695fbe33f 100644
--- a/src/config/env-precedence.ts
+++ b/src/config/env-precedence.ts
@@ -65,6 +65,7 @@ export const BLANK_SHADOWED_ENV_KEYS: string[] = [
'CHAT_MEDIA_ARCHIVE_OUTBOUND',
'CHAT_MEDIA_ARCHIVE_MAX_BYTES',
'CHAT_MEDIA_ARCHIVE_TTL_DAYS',
+ 'MESSAGE_INLINE_MEDIA',
'CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS',
'CHAT_MEDIA_ORPHAN_GRACE_MS',
// Send pacing. Blank-forwarded by compose like the chat-media keys, so an operator who sets
diff --git a/src/config/env.validation.spec.ts b/src/config/env.validation.spec.ts
index d9e97cf34..5406c00b7 100644
--- a/src/config/env.validation.spec.ts
+++ b/src/config/env.validation.spec.ts
@@ -104,6 +104,21 @@ describe('validateEnv', () => {
expect(() => validateEnv({ STORAGE_TYPE: 's3' })).not.toThrow();
});
+ it('accepts MESSAGE_INLINE_MEDIA inline or archive, and refuses a typo', () => {
+ expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'inline' })).not.toThrow();
+ expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archive', CHAT_MEDIA_ARCHIVE_ENABLED: 'true' })).not.toThrow();
+ expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archived' })).toThrow(/MESSAGE_INLINE_MEDIA must be one of/);
+ });
+
+ it('refuses MESSAGE_INLINE_MEDIA=archive without the archiver, which would silently do nothing', () => {
+ expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archive' })).toThrow(
+ /MESSAGE_INLINE_MEDIA=archive needs CHAT_MEDIA_ARCHIVE_ENABLED=true/,
+ );
+ expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archive', CHAT_MEDIA_ARCHIVE_ENABLED: 'false' })).toThrow(
+ /needs CHAT_MEDIA_ARCHIVE_ENABLED=true/,
+ );
+ });
+
// The runtime compares these raw (`=== 'postgres'`, the engine plugin lookup, `=== 's3'`), so a
// padded value that only matches after trimming would validate here and then take the default branch.
it.each([
diff --git a/src/config/env.validation.ts b/src/config/env.validation.ts
index eeff25849..5328acd66 100644
--- a/src/config/env.validation.ts
+++ b/src/config/env.validation.ts
@@ -100,6 +100,13 @@ export function validateEnv(config: EnvConfig): EnvConfig {
};
checkEnum('ENGINE_TYPE', ['whatsapp-web.js', 'baileys']);
checkEnum('STORAGE_TYPE', ['local', 's3']);
+ checkEnum('MESSAGE_INLINE_MEDIA', ['inline', 'archive']);
+ // 'archive' drops the inline copy only after the archiver stored the file; with the archiver off
+ // nothing is ever stored, so the mode would silently do nothing. Refuse that rather than let an
+ // operator believe the inline copies are being reclaimed.
+ if (rawEnum('MESSAGE_INLINE_MEDIA') === 'archive' && config.CHAT_MEDIA_ARCHIVE_ENABLED !== 'true') {
+ errors.push('MESSAGE_INLINE_MEDIA=archive needs CHAT_MEDIA_ARCHIVE_ENABLED=true');
+ }
// The S3 key root. A prefix that is absolute, traverses, or is only slashes would put this
// deployment's objects (and its orphan sweeps' deletes) at the bucket root or outside its own root;
// one with an empty or '.' segment builds keys an S3-compatible store refuses on every write.
diff --git a/src/modules/chat-media/chat-media-archive.service.spec.ts b/src/modules/chat-media/chat-media-archive.service.spec.ts
index db6633924..792476d89 100644
--- a/src/modules/chat-media/chat-media-archive.service.spec.ts
+++ b/src/modules/chat-media/chat-media-archive.service.spec.ts
@@ -68,6 +68,7 @@ describe('ChatMediaArchiveService', () => {
});
afterEach(async () => {
+ jest.restoreAllMocks();
await repository.clear();
for await (const file of storageService.iterateFiles('')) await storageService.deleteFile(file);
});
@@ -224,6 +225,151 @@ describe('ChatMediaArchiveService', () => {
});
});
+ describe('archive with MESSAGE_INLINE_MEDIA=archive', () => {
+ const replacing = (overrides: Record<string, unknown> = {}): ChatMediaArchiveService =>
+ enabled({ 'chatMedia.inlineMode': 'archive', ...overrides });
+ const mediaOf = async (id: string) =>
+ ((await repository.findOneByOrFail({ id })).metadata as { media: Record<string, unknown> }).media;
+
+ it('replaces the inline copy with the archived marker once the file is stored', async () => {
+ const row = await saveRow({ mimetype: 'image/png', data: PNG.toString('base64'), filename: 'cat.png' });
+
+ const key = await replacing().archive(row);
+
+ expect(key).not.toBeNull();
+ expect(await mediaOf(row.id)).toEqual({
+ mimetype: 'image/png',
+ filename: 'cat.png',
+ omitted: true,
+ sizeBytes: PNG.length,
+ archived: true,
+ });
+ // The bytes now live once, in the store, and the media route reads them from there.
+ expect(await storageService.getFile(key!)).toEqual(PNG);
+ });
+
+ it('keeps the rest of the metadata the row gained since it was persisted', async () => {
+ const row = await saveRow({ mimetype: 'image/png', data: PNG.toString('base64') });
+ await repository.update(
+ { id: row.id },
+ {
+ metadata: { ...row.metadata, quotedMessage: { id: 'q1', body: 'hi' } },
+ },
+ );
+
+ await replacing().archive(row);
+
+ const reloaded = await repository.findOneByOrFail({ id: row.id });
+ expect((reloaded.metadata as { quotedMessage: unknown }).quotedMessage).toEqual({ id: 'q1', body: 'hi' });
+ expect((reloaded.metadata as { media: { data?: string } }).media.data).toBeUndefined();
+ });
+
+ it('keeps the inline copy when the stored file does not read back intact', async () => {
+ const base64 = PNG.toString('base64');
+ const row = await saveRow({ mimetype: 'image/png', data: base64 });
+ const get = jest.spyOn(storageService, 'getFile').mockResolvedValueOnce(Buffer.from('truncated'));
+
+ expect(await replacing().archive(row)).toBeNull();
+
+ expect((await mediaOf(row.id)).data).toBe(base64);
+ expect((await repository.findOneByOrFail({ id: row.id })).mediaPath).toBeNull();
+ get.mockRestore();
+ });
+
+ it('keeps the inline copy when the read-back fails', async () => {
+ const base64 = PNG.toString('base64');
+ const row = await saveRow({ mimetype: 'image/png', data: base64 });
+ const get = jest.spyOn(storageService, 'getFile').mockRejectedValueOnce(new Error('s3 down'));
+
+ await expect(replacing().archive(row)).resolves.toBeNull();
+
+ expect((await mediaOf(row.id)).data).toBe(base64);
+ expect((await repository.findOneByOrFail({ id: row.id })).mediaPath).toBeNull();
+ get.mockRestore();
+ });
+
+ it('keeps metadata changed between the inline snapshot and replacement', async () => {
+ const base64 = PNG.toString('base64');
+ const row = await saveRow({ mimetype: 'image/png', data: base64 });
+ const originalFindOne = repository.findOne.bind(repository);
+ const find = jest.spyOn(repository, 'findOne').mockImplementationOnce(async options => {
+ const snapshot = await originalFindOne(options);
+ await repository.update({ id: row.id }, { metadata: { ...row.metadata, reactions: { user: 'ok' } } });
+ return snapshot;
+ });
+
+ await replacing().archive(row);
+
+ find.mockRestore();
+ const current = await repository.findOneByOrFail({ id: row.id });
+ expect(current.metadata).toEqual({ ...row.metadata, reactions: { user: 'ok' } });
+ expect(current.mediaPath).toBeNull();
+ });
+
+ it('keeps an inline payload that changed while the archive was written', async () => {
+ const row = await saveRow({ mimetype: 'image/png', data: PNG.toString('base64') });
+ const changedMedia = { mimetype: 'image/png', data: Buffer.from('new bytes').toString('base64') };
+ const originalPut = storageService.putFile.bind(storageService);
+ const put = jest.spyOn(storageService, 'putFile').mockImplementationOnce(async (key, bytes) => {
+ await originalPut(key, bytes);
+ await repository.update({ id: row.id }, { metadata: { media: changedMedia } });
+ });
+
+ await replacing().archive(row);
+
+ put.mockRestore();
+ expect(await mediaOf(row.id)).toEqual(changedMedia);
+ expect((await repository.findOneByOrFail({ id: row.id })).mediaPath).toBeNull();
+ });
+
+ it('does not publish media revoked while the verified snapshot was read', async () => {
+ const row = await saveRow({ mimetype: 'image/png', data: PNG.toString('base64') });
+ const originalFindOne = repository.findOne.bind(repository);
+ const find = jest.spyOn(repository, 'findOne').mockImplementationOnce(async options => {
+ const snapshot = await originalFindOne(options);
+ await repository.update({ id: row.id }, { type: 'revoked', metadata: null as unknown as undefined });
+ return snapshot;
+ });
+
+ expect(await replacing().archive(row)).toBeNull();
+
+ find.mockRestore();
+ const current = await repository.findOneByOrFail({ id: row.id });
+ expect(current.type).toBe('revoked');
+ expect(current.metadata).toBeNull();
+ expect(current.mediaPath).toBeNull();
+ });
+
+ it('keeps the inline copy when the file could not be written', async () => {
+ const base64 = PNG.toString('base64');
+ const row = await saveRow({ mimetype: 'image/png', data: base64 });
+ const put = jest.spyOn(storageService, 'putFile').mockRejectedValueOnce(new Error('disk on fire'));
+
+ await replacing().archive(row);
+
+ expect((await mediaOf(row.id)).data).toBe(base64);
+ put.mockRestore();
+ });
+
+ it('keeps the inline copy of media above the archive cap, which is not archived', async () => {
+ const base64 = PNG.toString('base64');
+ const row = await saveRow({ mimetype: 'image/png', data: base64 });
+
+ expect(await replacing({ 'chatMedia.maxBytes': 4 }).archive(row)).toBeNull();
+
+ expect((await mediaOf(row.id)).data).toBe(base64);
+ });
+
+ it('leaves the inline copy alone in the default inline mode', async () => {
+ const base64 = PNG.toString('base64');
+ const row = await saveRow({ mimetype: 'image/png', data: base64 });
+
+ await enabled({ 'chatMedia.inlineMode': 'inline' }).archive(row);
+
+ expect((await mediaOf(row.id)).data).toBe(base64);
+ });
+ });
+
describe('getMedia', () => {
it('resolves an archived file by session + chat + WhatsApp message id', async () => {
const row = await saveRow({ mimetype: 'image/png', data: PNG.toString('base64') });
diff --git a/src/modules/chat-media/chat-media-archive.service.ts b/src/modules/chat-media/chat-media-archive.service.ts
index 7882a5d54..191ddd102 100644
--- a/src/modules/chat-media/chat-media-archive.service.ts
+++ b/src/modules/chat-media/chat-media-archive.service.ts
@@ -53,9 +53,12 @@ interface InlineMedia {
* Archives chat-message media to the file store so it stays retrievable after delivery, independent
* of the inline base64 copy the message row already carries.
*
- * Opt-in (`CHAT_MEDIA_ARCHIVE_ENABLED`, default off) because it doubles storage for media under the
- * cap: the inline copy is deliberately left in place, since the dashboard renders from it and
- * stripping it would break the response contract.
+ * Opt-in (`CHAT_MEDIA_ARCHIVE_ENABLED`, default off) because, by default, it doubles storage for
+ * media under the cap: the inline copy is left in place, since the dashboard renders from it.
+ * `MESSAGE_INLINE_MEDIA=archive` changes that: once a file is stored, read back intact and the row
+ * points at it, the row's inline copy is replaced with the omitted marker (`omitted: true`,
+ * `archived: true`), so the bytes are kept once and served by the media route. Any failure along
+ * the way leaves the inline copy, so the mode can lose a saving but never the media.
*
* Two recurring sweeps run regardless of that flag, which gates the writer rather than the store: a
* retention purge (when `CHAT_MEDIA_ARCHIVE_TTL_DAYS` is non-zero) that clears files past their TTL
@@ -87,6 +90,11 @@ export class ChatMediaArchiveService implements OnModuleInit, OnModuleDestroy {
return this.configService.get<boolean>('chatMedia.archiveEnabled', false);
}
+ /** MESSAGE_INLINE_MEDIA=archive: an archived file replaces the row's inline copy. */
+ get replacesInline(): boolean {
+ return this.configService.get<'inline' | 'archive'>('chatMedia.inlineMode', 'inline') === 'archive';
+ }
+
onModuleInit(): void {
const runPurge = (): void => {
if (this.purging) return;
@@ -153,8 +161,9 @@ export class ChatMediaArchiveService implements OnModuleInit, OnModuleDestroy {
// id into S3 keys. The row is read on the way out anyway, so nothing is gained by a derivable
// key. Mirrors the status store.
const key = `${CHAT_MEDIA_PREFIX}${row.sessionId}/${randomUUID()}.${extFromMimetype(media.mimetype)}`;
+ const bytes = Buffer.from(media.data, 'base64');
try {
- await this.storageService.putFile(key, Buffer.from(media.data, 'base64'));
+ await this.storageService.putFile(key, bytes);
} catch (error) {
this.logger.error(
`Failed to archive chat media for session ${row.sessionId}, message ${row.id}`,
@@ -164,14 +173,48 @@ export class ChatMediaArchiveService implements OnModuleInit, OnModuleDestroy {
}
try {
- // Conditional on the row not being revoked: a revoke that landed while the file was written
- // cleared the row, and pointing it at the file would bring the deleted media back. And on no
- // pointer yet: the other writer may have passed the snapshot guard above while this file was
- // being written, and the first pointer wins so the losing file is deleted, not stranded.
- const result = await this.repository.update(
- { id: row.id, type: Not('revoked'), mediaPath: IsNull() },
- { mediaPath: key, mediaMimetype: media.mimetype },
- );
+ let result;
+ if (this.replacesInline) {
+ const stored = await this.storageService.getFile(key);
+ if (!stored.equals(bytes)) throw new Error('Archived media did not read back intact');
+ const current = await this.repository.findOne({
+ where: { id: row.id, mediaPath: IsNull(), type: Not('revoked') },
+ select: { id: true, metadata: true },
+ });
+ const metadata = current?.metadata;
+ const currentMedia = (metadata as { media?: InlineMedia } | null | undefined)?.media;
+ if (!currentMedia?.data || currentMedia.data !== media.data) {
+ await this.storageService.deleteFile(key).catch(() => undefined);
+ return null;
+ }
+ const { data: _data, ...rest } = currentMedia;
+ void _data;
+ // Publish the verified pointer and remove only the exact metadata snapshot we read.
+ // A concurrent reaction, edit or revoke wins instead of being overwritten.
+ result = await this.repository
+ .createQueryBuilder()
+ .update()
+ .set({
+ mediaPath: key,
+ mediaMimetype: media.mimetype,
+ metadata: {
+ ...metadata,
+ media: { ...rest, omitted: true, sizeBytes: bytes.length, archived: true },
+ },
+ })
+ .where({ id: row.id, type: Not('revoked'), mediaPath: IsNull() })
+ .andWhere('"metadata" = :snapshot', { snapshot: JSON.stringify(metadata) })
+ .execute();
+ } else {
+ // Conditional on the row not being revoked: a revoke that landed while the file was written
+ // cleared the row, and pointing it at the file would bring the deleted media back. And on no
+ // pointer yet: the other writer may have passed the snapshot guard above while this file was
+ // being written, and the first pointer wins so the losing file is deleted, not stranded.
+ result = await this.repository.update(
+ { id: row.id, type: Not('revoked'), mediaPath: IsNull() },
+ { mediaPath: key, mediaMimetype: media.mimetype },
+ );
+ }
if (result.affected === 0) {
await this.storageService.deleteFile(key).catch(() => undefined); // else the orphan sweep reaps it
return null;
@@ -179,9 +222,12 @@ export class ChatMediaArchiveService implements OnModuleInit, OnModuleDestroy {
} catch (error) {
// The file exists but no row references it β€” an orphan the sweep reaps after its grace
// window. The row itself stays consistent (mediaPath still null), so nothing else to undo.
- this.logger.warn(`Chat media ${key} written but the row update failed; leaving it for the orphan sweep`, {
- error: String(error),
- });
+ this.logger.warn(
+ `Chat media ${key} written but not published; keeping inline media and leaving the file for the orphan sweep`,
+ {
+ error: String(error),
+ },
+ );
return null;
}
return key;