Limits
The HTTP request body limit equals the video limit (100 MB), so no upload can exceed it. Query the live values with
GET /app/info (max_image_size, max_file_size, max_video_size). These limits are compiled-in defaults; there is no environment variable for them.
Two ways to provide media
Every media endpoint accepts either a multipart file or a URL that GOWA fetches server-side:Processing
GOWA needs FFmpeg and libwebp on the host (both are in the Docker image)./send/file sends documents without conversion.
Image processing checks header dimensions before decoding. The longest accepted edge is 32,768 pixels. Non-JPEG images have a 40-million-pixel budget. JPEGs have an 80-million-pixel ceiling plus a 320 MiB decode-memory budget, so some large progressive or CMYK JPEGs are rejected below the pixel ceiling. Original image sends can omit thumbnails when decoding exceeds the budget. Interactive carousel images have separate, smaller limits in Interactive messages.
Incoming media
WithWHATSAPP_AUTO_DOWNLOAD_MEDIA=true (default), GOWA downloads media from incoming messages to statics/media/ and puts the relative path in the webhook payload:
http://<host>:3000/statics/media/<file>. Set WHATSAPP_IGNORE_STATUS_MEDIA=true to skip media from status updates.
With auto-download off, the payload carries a WhatsApp CDN URL instead. Download through GOWA, which decrypts the file:
main after v9.9.0, explicit downloads and forwards can ask the phone to re-upload expired media. The phone must be online and still have the file. GOWA waits up to 30 seconds for a response. This also applies to the MCP download_media and forward actions, and to Chatwoot history imports.
Storage and cleanup
Paths are relative to the process directory, normallysrc/ from source or /app in Docker. Compose mounts the repository’s storages/ and statics/ directories into /app.
There is no age-based media retention setting or cleanup endpoint. An image can have copies in both
storages/ and statics/media/. Never remove the whole storages/ directory to reclaim media space.
Pause GOWA and other writers, back up required files, then preview the files to remove. These GNU find examples run from the deployment directory and select files at least 31 full days old.
-print with -delete in the same commands. Preserve database files, SQLite -wal and -shm sidecars, scheduled attachments, and custom files. Restart GOWA afterward. Deleted paths and static URLs stop working, and removing media does not prune chat history.
WHATSAPP_AUTO_DOWNLOAD_MEDIA=false stops future automatic downloads and extra image copies. It does not remove old files or prevent explicit REST or MCP downloads. See the full media storage and cleanup guide.
/statics remains public. Stored HTML, SVG, scripts, and other documents are served as attachments with application/octet-stream and nosniff. Supported image bytes under image-preview paths can render inline. These content protections do not restrict who can download a file. Protect sensitive media at the reverse proxy.
