> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
# 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:

```json theme={null}
"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:

```bash theme={null}
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:

```bash theme={null}
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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.