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

# Penanganan Media

> Unggah dan kirim media, pahami batas ukuran dan konversi, serta unduh media dari pesan masuk.

## Batasan

| Jenis | Batas maksimum default |
| - | - |
| Gambar | 20 MB |
| Dokumen (`/send/file`) | 50 MB |
| Video | 100 MB |
| Media yang diunduh (masuk) | 500 MB |

Batas ukuran body permintaan HTTP sama dengan batas video (100 MB), sehingga tidak ada unggahan yang dapat melebihinya. Periksa nilai yang sedang berlaku dengan `GET /app/info` (`max_image_size`, `max_file_size`, `max_video_size`). Batas ini merupakan nilai default yang ditetapkan saat kompilasi; tidak ada variabel lingkungan untuk mengaturnya.

## Dua cara menyediakan media

Setiap endpoint media menerima file multipart atau URL yang diambil GOWA dari sisi server:

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

Kirim salah satu, jangan keduanya. URL media jarak jauh harus menggunakan HTTP atau HTTPS dan mengarah ke alamat publik. GOWA memblokir tujuan loopback, privat, link-local, serta alamat khusus lainnya, termasuk tujuan pengalihan. Unggah file lokal sebagai data multipart alih-alih menggunakan URL internal.

## Pemrosesan

GOWA memerlukan FFmpeg dan libwebp pada host (keduanya tersedia dalam image Docker).

| Opsi | Endpoint | Efek |
| - | - | - |
| `compress` | image (default `true`), video (default `false`) | Enkode ulang sebelum mengirim. |
| `hd` | image, video | Kirim dalam HD tanpa memperbesar resolusi: gambar hingga 2560 px pada sisi terpanjang; video dalam H.264 dengan batas 1280×1280. Mengesampingkan `compress`. |
| `view_once` | image, video | Penerima hanya dapat membukanya sekali. |
| `gif_playback` | video | Putar sebagai GIF berulang. |
| `ptt` | audio | Kirim sebagai pesan suara (push-to-talk). Dikonversi dengan FFmpeg. |
| (otomatis) | sticker | JPG, PNG, WebP, atau GIF dikonversi menjadi stiker WebP 512×512. WebP animasi harus memenuhi batasan stiker WhatsApp. |

`/send/file` mengirim dokumen tanpa konversi.

Pemrosesan gambar memeriksa dimensi pada header sebelum melakukan dekode. Sisi terpanjang yang diterima adalah 32,768 piksel. Gambar non-JPEG dibatasi hingga 40 juta piksel. JPEG memiliki batas 80 juta piksel serta alokasi memori dekode 320 MiB, sehingga sebagian JPEG progresif atau CMYK berukuran besar dapat ditolak meskipun jumlah pikselnya masih di bawah batas. Pengiriman gambar asli dapat tidak menyertakan thumbnail jika proses dekode melampaui alokasi tersebut. Gambar carousel interaktif memiliki batas terpisah yang lebih kecil di [Pesan interaktif](https://gowa-docs.mintlify.site/id/examples/interactive-messages.md).

## Media masuk

Dengan `WHATSAPP_AUTO_DOWNLOAD_MEDIA=true` (default), GOWA mengunduh media dari pesan masuk ke `statics/media/` dan menyertakan path relatifnya dalam payload webhook:

```json theme={null}
{
  "image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"
}
```

Ambil file melalui `http://<host>:3000/statics/media/<file>`. Atur `WHATSAPP_IGNORE_STATUS_MEDIA=true` untuk melewati media dari pembaruan status.

Jika unduhan otomatis dinonaktifkan, payload memuat URL CDN WhatsApp. Unduh melalui GOWA agar file didekripsi:

```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 menyimpan media di servernya untuk waktu terbatas. Segera unduh media yang Anda perlukan.

Pada branch `main` GOWA setelah v9.9.0, permintaan unduhan dan penerusan secara eksplisit dapat meminta ponsel mengunggah ulang media yang kedaluwarsa. Ponsel harus online dan masih memiliki file tersebut. GOWA menunggu respons hingga 30 detik. Hal ini juga berlaku untuk tindakan MCP `download_media` dan `forward`, serta [impor riwayat Chatwoot](https://gowa-docs.mintlify.site/id/integrations/chatwoot.md#impor-riwayat).

## Penyimpanan dan pembersihan

Path bersifat relatif terhadap direktori proses, biasanya `src/` saat dijalankan dari kode sumber atau `/app` di Docker. Compose memasang direktori `storages/` dan `statics/` dari repositori ke `/app`.

| Path | Isi |
| - | - |
| `statics/media/` | Media webhook yang diunduh dan unduhan eksplisit, termasuk subdirektori chat/tanggal. |
| `storages/<timestamp>-<uuid>[.<extension>]` | Salinan tambahan yang disimpan penangan gambar masuk saat unduhan otomatis diaktifkan. |
| `storages/scheduled/` | Lampiran yang disimpan untuk pengiriman terjadwal. Biarkan penjadwal mengelolanya. |
| `storages/history-*.json` | Dump riwayat, terpisah dari unduhan media. |

Tidak ada pengaturan retensi media berdasarkan umur maupun endpoint pembersihan. Sebuah gambar dapat memiliki salinan di `storages/` dan `statics/media/`. Jangan pernah menghapus seluruh direktori `storages/` untuk mengosongkan ruang media.

Hentikan sementara GOWA dan proses lain yang menulis file, cadangkan file yang diperlukan, lalu tinjau daftar file yang akan dihapus. Contoh GNU find ini dijalankan dari direktori deployment dan memilih file yang berumur setidaknya 31 hari penuh.

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

Setelah meninjau setiap path, ganti `-print` dengan `-delete` pada perintah yang sama. Pertahankan file database, file pendamping SQLite `-wal` dan `-shm`, lampiran terjadwal, serta file kustom. Setelah itu, jalankan ulang GOWA. Path dan URL statis yang dihapus tidak lagi berfungsi, dan menghapus media tidak menghapus riwayat chat.

`WHATSAPP_AUTO_DOWNLOAD_MEDIA=false` menghentikan unduhan otomatis dan pembuatan salinan gambar tambahan berikutnya. Pengaturan ini tidak menghapus file lama atau mencegah unduhan eksplisit melalui REST maupun MCP. Lihat [panduan penyimpanan dan pembersihan media](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/media-storage.md) selengkapnya.

`/statics` tetap bersifat publik. HTML, SVG, skrip, dan dokumen lain yang tersimpan disajikan sebagai lampiran dengan `application/octet-stream` dan `nosniff`. Data gambar yang didukung pada path pratinjau gambar dapat ditampilkan langsung. Perlindungan konten ini tidak membatasi siapa yang dapat mengunduh file. Lindungi media sensitif pada reverse proxy.

## Pemecahan masalah

| Masalah | Solusi |
| - | - |
| Error `413` atau batas body | File melebihi 100 MB; kirim tautan sebagai gantinya. |
| Pesan suara gagal atau diputar sebagai file | Instal FFmpeg; atur `ptt=true`. |
| Konversi stiker gagal | Instal alat libwebp (`cwebp`, `dwebp`, `webpmux`). |
| Media dari URL gagal | URL harus publik, mengembalikan file secara langsung (bukan halaman HTML), dan memenuhi batas ukuran. |


## Related topics

- [Mengirim Pesan](https://gowa-docs.mintlify.site/id/examples/sending-messages.md)
- [Penanganan Kesalahan](https://gowa-docs.mintlify.site/id/advanced/error-handling.md)
- [Unduh media dari pesan](https://gowa-docs.mintlify.site/id/api-reference/message/unduh-media-dari-pesan.md)
- [Unduh media dari pesan newsletter](https://gowa-docs.mintlify.site/id/api-reference/newsletter/unduh-media-dari-pesan-newsletter.md)
- [Error](https://gowa-docs.mintlify.site/id/api-reference/errors.md)


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