> ## 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. 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).

| 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.

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](https://gowa-docs.mintlify.site/examples/interactive-messages.md).

## 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. 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](https://gowa-docs.mintlify.site/integrations/chatwoot.md#import-history).

## 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`.

| Path | Contents |
| - | - |
| `statics/media/` | Downloaded webhook media and explicit downloads, including chat/date subdirectories. |
| `storages/<timestamp>-<uuid>[.<extension>]` | Extra copies saved by the incoming-image handler when automatic downloads are enabled. |
| `storages/scheduled/` | Attachments retained by scheduled sends. Let the scheduler manage these. |
| `storages/history-*.json` | History dumps, independent of media downloads. |

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.

```bash theme={null}
find ./statics/media -type f -mtime +30 -print
find ./storages -maxdepth 1 -type f -mtime +30 \
  -name '[0-9]*-????????-????-????-????-????????????*' -print
```

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](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/media-storage.md).

`/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

| 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. |


## Related topics

- [Sending Messages](https://gowa-docs.mintlify.site/examples/sending-messages.md)
- [Error Handling](https://gowa-docs.mintlify.site/advanced/error-handling.md)
- [Download media from message](https://gowa-docs.mintlify.site/api-reference/message/download-media-from-message.md)
- [Download media from a newsletter message](https://gowa-docs.mintlify.site/api-reference/newsletter/download-media-from-a-newsletter-message.md)
- [Errors](https://gowa-docs.mintlify.site/api-reference/errors.md)


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