Media Handling

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=628987654321@s.whatsapp.net"

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.

Getting Started

Core Concepts

Usage Examples

Integrations

Advanced

Limits

Two ways to provide media

Processing

Incoming media

Disk usage

Troubleshooting

​Limits

​Two ways to provide media

​Processing

​Incoming media

​Disk usage

​Troubleshooting

Limits

Two ways to provide media

Processing

Incoming media

Disk usage

Troubleshooting