Media Handling

Upload and send media, understand size limits and conversions, and download media from incoming messages.

Limits

Type	Default maximum
Image	20 MB
Document (/send/file)	50 MB
Video	100 MB
Downloaded media (incoming)	500 MB

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:

# upload
curl -u admin:changeme -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 -F image=@photo.jpg

# URL
curl -u admin:changeme -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 -F image_url=https://example.com/photo.jpg

Send one or the other, not both. A URL must be reachable from the GOWA server.

Processing

GOWA needs FFmpeg and libwebp on the host (both are in the Docker image).

Option	Endpoint	Effect
compress	image (default true), video (default false)	Re-encode before sending.
hd	image, video	Send in HD without upscaling: images up to 2560 px on the long edge; video as H.264 capped at 1280×1280. Overrides compress.
view_once	image, video	Recipient can open it once.
gif_playback	video	Play as a looping GIF.
ptt	audio	Send as a voice note (push-to-talk). Converted with FFmpeg.
(automatic)	sticker	JPG, PNG, WebP or GIF converted to a 512×512 WebP sticker. Animated WebP must meet WhatsApp’s sticker limits.

/send/file sends documents without conversion.

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:

"image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"

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:

curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/message/3EB0C127D7BACC83D6A3/download?phone=[e-mail]"

WhatsApp keeps media on its servers for a limited time (roughly two weeks). Download what you need promptly.

Disk usage

statics/media/ grows without limit; GOWA does not prune it. Clean it with a scheduled job, for example:

find /app/statics/media -type f -mtime +30 -delete

Remember that /statics is served without Basic Auth.

Troubleshooting

Problem	Fix
413 or body-limit error	File exceeds 100 MB; send a link instead.
Voice note fails or plays as a file	Install FFmpeg; set ptt=true.
Sticker conversion fails	Install libwebp tools (cwebp, dwebp, webpmux).
URL media fails	The URL must be public, return the file directly (no HTML page) and fit the size limit.