Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(storage): say which media lands in the configured store

Yudhi Armyndharisb4fb5d257783
diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.md
index 0d893ae29..d67fbae22 100644
--- a/docs/03-system-architecture.md
+++ b/docs/03-system-architecture.md
@@ -1283,7 +1283,9 @@ internally on `storageType` — there is no `I*Adapter` interface, separate adap
The main producer/consumer is the storage export/import migration and backup flow; the status store
also writes status media through `putFile` (under `statuses/`) and sweeps orphans back out with
`deleteFile`. Incoming and outgoing message media is returned inline to REST/webhook consumers and is
-**not** automatically written through `StorageService`.
+**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`).
+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
for S3-compatible stores (MinIO, R2, …), and setting it is also what enables `forcePathStyle: true`.
diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.md
index 7a489e62a..efc5514ff 100644
--- a/docs/10-devops-infrastructure.md
+++ b/docs/10-devops-infrastructure.md
@@ -378,6 +378,15 @@ LOG_FORMAT=json
# ===========================================
# MEDIA STORAGE (choose one)
# ===========================================
+# What the selected store holds: received status media, always, under statuses/<sessionId>/.
+# Chat message media is copied there only with CHAT_MEDIA_ARCHIVE_ENABLED=true, under
+# 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.
+# 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.
+# The other CHAT_MEDIA_* settings (size cap, TTL, orphan sweep) are in .env.example.
# STORAGE_TYPE accepts only `local` or `s3` — env validation rejects anything else and the app
# FAILS TO BOOT ("Invalid environment configuration"). There is no silent fallback to local disk.
# Option 1: Local filesystem (default)