Skip to main content

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:
Send one or the other, not both. Remote media URLs must use HTTP or HTTPS and resolve to public addresses. GOWA blocks loopback, private, link-local, and other reserved destinations, including redirect targets. Upload local files as multipart data instead of using an internal URL.

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

With WHATSAPP_AUTO_DOWNLOAD_MEDIA=true (default), GOWA downloads media from incoming messages to statics/media/ and puts the relative path in the webhook payload:
Fetch it at 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:
WhatsApp keeps media on its servers for a limited time. Download what you need promptly. On GOWA 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, normally src/ 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.
After reviewing every path, replace -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.

Troubleshooting