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

# Pengiriman Terjadwal

> Kirim pesan nanti, sekali atau berulang setiap hari, minggu, atau bulan, dan kelola jadwal melalui /send/schedules.

![Gambaran Umum Penjadwal Pesan GOWA](https://mintcdn.com/gowa-docs/G0gUpNl3gUGyehVX/images/GOWA-Message-Scheduler-Overview.png?fit=max\&auto=format\&n=G0gUpNl3gUGyehVX\&q=85\&s=663bfdbb9e1c0bb451c0fa782380b139)

Setiap permintaan pengiriman dapat dijadwalkan. Tambahkan `scheduled_at` dan `timezone`; GOWA menyimpan permintaan tersebut, lalu worker latar belakang mengirimkannya pada waktu yang ditentukan. Jadwal tetap tersimpan setelah server dimulai ulang dan menunggu jika perangkat sedang offline.

Jenis pesan yang dapat dijadwalkan: teks, gambar, file, video, audio, stiker, kontak, tautan, lokasi, polling, dan penerusan (`/message/{id}/forward`). Status kehadiran, indikator mengetik, dan endpoint eksperimental `/send/interactive` tidak dapat dijadwalkan.

## Kolom jadwal

| Kolom | Wajib | Deskripsi |
| - | - | - |
| `scheduled_at` | ya | Waktu pengiriman pertama dalam format RFC 3339, harus di masa mendatang, misalnya `2026-11-01T09:00:00+07:00`. Pengiriman pertama selalu dilakukan pada waktu ini. |
| `timezone` | ya | Zona IANA (misalnya `Asia/Jakarta`) untuk menghitung pengulangan, sehingga "09:00 setiap hari" tetap pada 09:00 meskipun terjadi perubahan DST. |
| `recurrence` | tidak | `once` (default), `daily`, `weekly`, atau `monthly`. |
| `weekdays` | untuk weekly | Hari pengiriman, `0` = Minggu … `6` = Sabtu, misalnya `[1, 3, 5]`. |
| `day_of_month` | untuk monthly | `1`–`31`; dibatasi ke hari terakhir jika bulan tersebut memiliki lebih sedikit hari. |
| `end_at` | tidak | Hanya untuk jadwal berulang. Tidak ada pengiriman setelah waktu ini. |
| `occurrence_limit` | tidak | Hanya untuk jadwal berulang. Berhenti setelah jumlah pengiriman ini tercapai. |

Tanpa `scheduled_at`, permintaan langsung dikirim seperti biasa.

## Contoh

```bash theme={null}
# once, tomorrow morning
curl -u admin:changeme -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" -H "X-Device-Id: my-device" \
  -d '{
    "phone": "628123456789",
    "message": "Reminder: meeting at 10:00",
    "scheduled_at": "2026-11-01T09:00:00+07:00",
    "timezone": "Asia/Jakarta"
  }'
```

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Success",
  "results": {
    "schedule_id": "0b5c3a8e-7f5d-4d6f-9d1e-2f8c1a7b9e10",
    "scheduled_at": "2026-11-01T02:00:00Z",
    "next_run_at": "2026-11-01T02:00:00Z"
  }
}
```

Respons terjadwal memiliki `schedule_id` sebagai pengganti `message_id`.

```bash theme={null}
# every Monday, Wednesday and Friday at 08:30, 12 times
curl -u admin:changeme -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" -H "X-Device-Id: my-device" \
  -d '{
    "phone": "120363025246125486@g.us",
    "message": "Standup in 30 minutes",
    "scheduled_at": "2026-11-02T08:30:00+07:00",
    "timezone": "Asia/Jakarta",
    "recurrence": "weekly",
    "weekdays": [1, 3, 5],
    "occurrence_limit": 12
  }'
```

```bash theme={null}
# monthly invoice on the 1st, with an uploaded file (multipart: repeat weekdays as separate fields if used)
curl -u admin:changeme -X POST http://localhost:3000/send/file \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 \
  -F file=@invoice.pdf \
  -F scheduled_at=2026-12-01T09:00:00+07:00 \
  -F timezone=Asia/Jakarta \
  -F recurrence=monthly \
  -F day_of_month=1 \
  -F end_at=2027-12-31T23:59:59+07:00
```

File yang diunggah disimpan di server hingga jadwal selesai. Dalam body multipart, kirim `weekdays` sebagai kolom berulang (`-F weekdays=1 -F weekdays=3`).

## Mengelola jadwal

Jadwal terikat pada perangkat; kirim `X-Device-Id` yang sama.

| Tindakan | Permintaan |
| - | - |
| Daftar | `GET /send/schedules` dengan parameter opsional `status`, `search` (penerima atau teks), `message_type`, `limit`, `offset` |
| Ambil satu | `GET /send/schedules/{schedule_id}` |
| Jeda | `POST /send/schedules/{schedule_id}/pause` |
| Lanjutkan | `POST /send/schedules/{schedule_id}/resume` |
| Batalkan | `POST /send/schedules/{schedule_id}/cancel` |

```bash theme={null}
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/send/schedules?status=active&limit=25"
```

Daftar mengembalikan `results.data` dan `results.pagination` (`limit`, default 25; `offset`; `total`).

### Status

| Status | Arti |
| - | - |
| `active` | Menunggu eksekusi berikutnya. |
| `running` | Diklaim oleh worker dan sedang dikirim. |
| `paused` | Ditahan hingga dilanjutkan. |
| `completed` | Tidak ada eksekusi tersisa. |
| `failed` | Dihentikan setelah percobaan ulang, atau permintaan yang disimpan tidak valid. |
| `cancelled` | Dibatalkan oleh Anda. |

## Perilaku pengiriman

* Worker memeriksa jadwal yang sudah waktunya dijalankan setiap 5 detik.
* **Perangkat offline atau belum login:** eksekusi menunggu dan mencoba lagi setiap 30 detik. Menunggu tidak dihitung sebagai percobaan gagal, sehingga jadwal tetap berlaku meskipun koneksi terputus lama.
* **Kesalahan pengiriman:** dicoba ulang dengan jeda bertahap mulai dari 15 detik hingga maksimum 5 menit, maksimal 10 percobaan per pengiriman terjadwal. Jadwal berulang kemudian melewati pengiriman tersebut dan beralih ke pengiriman berikutnya; jadwal sekali kirim menjadi `failed`.
* **Permintaan tidak valid** (misalnya penerima yang salah): langsung gagal tanpa percobaan ulang.
* **Eksekusi terlambat:** pengiriman yang tertunda hingga melewati `end_at` tidak dikirim.
* **Crash dan mulai ulang:** penghentian server tidak membatalkan pengiriman yang sedang berlangsung. Sebelum percobaan pertama, GOWA menyimpan ID pesan WhatsApp untuk pengiriman tersebut. Setelah masa klaim 2 menit berakhir, pengiriman yang terputus dimasukkan kembali ke antrean dengan ID yang sama dan dihitung dalam batas percobaan. Polling juga mempertahankan kunci rahasia enkripsinya pada percobaan ulang. Ini menjaga identitas pesan saat konfirmasi penerimaan tidak pasti, tetapi tidak menjamin pesan terkirim tepat satu kali.
* **Percobaan lama yang terputus:** percobaan dari versi lama dengan hasil yang tidak diketahui tetap dipulihkan secara konservatif. Worker melewati pengiriman tersebut untuk jadwal berulang atau menggagalkan jadwal sekali kirim, alih-alih memberikan identitas pesan baru.

## Melalui MCP

Tool MCP `whatsapp_send` menerima kolom jadwal yang sama, sedangkan `whatsapp_schedule` dapat menampilkan daftar, mengambil, menjeda, melanjutkan, dan membatalkan jadwal. Lihat [Server MCP](https://gowa-docs.mintlify.site/id/integrations/mcp.md).

> [!NOTE]
>
> Periksa `GET /app/info`: `results.scheduled_sends` bernilai `true` jika server menerima kolom jadwal dan menyediakan `/send/schedules`.


## Related topics

- [Daftar pengiriman terjadwal](https://gowa-docs.mintlify.site/id/api-reference/send/daftar-pengiriman-terjadwal.md)
- [Jeda pengiriman terjadwal](https://gowa-docs.mintlify.site/id/api-reference/send/jeda-pengiriman-terjadwal.md)
- [Ambil pengiriman terjadwal](https://gowa-docs.mintlify.site/id/api-reference/send/ambil-pengiriman-terjadwal.md)
- [Batalkan pengiriman terjadwal](https://gowa-docs.mintlify.site/id/api-reference/send/batalkan-pengiriman-terjadwal.md)
- [Lanjutkan pengiriman terjadwal yang dijeda](https://gowa-docs.mintlify.site/id/api-reference/send/lanjutkan-pengiriman-terjadwal-yang-dijeda.md)


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