# Scheduled Delivery

Kirim pesan sekarang, tiba nanti. Tambahkan `send_at` atau `delay` ke permintaan [Create Message](https://info.pocketalert.app/api/messages/create.md) mana pun dan Pocket Alert menyimpannya secara terenkripsi hingga waktu pengiriman, lalu mengirimkannya sebagai push notification biasa.

Tidak perlu cron job di sisi Anda, tidak perlu queue worker, tidak perlu proses yang harus terus berjalan sampai hari Selasa.

## Dua cara menentukan waktu

| Parameter | Menerima | Contoh |
|-----------|----------|--------|
| `send_at` | RFC3339, Unix timestamp, atau `YYYY-MM-DD HH:MM` | `2026-08-15T09:00:00Z`, `1786867200`, `2026-08-15 09:00` |
| `delay` | Durasi gaya Go atau detik saja | `30m`, `2h`, `90s`, `3600` |

Kirim salah satu saja — mengirim keduanya akan mengembalikan `400`.

`send_at` tanpa offset zona waktu dibaca dalam **zona waktu akun Anda**, sehingga `2026-08-15 09:00` berarti pukul sembilan pagi di tempat Anda berada, bukan UTC. Atur di [pengaturan akun](https://pocketalert.app/account).

## Menjadwalkan pesan

**cURL — absolute time**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Certificate expires tomorrow",
    "message": "api.example.com — renew before 09:00 UTC",
    "send_at": "2026-08-15T09:00:00Z",
    "level": "high"
  }'
```

**cURL — relative delay**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Check the migration",
    "message": "Started at 14:02 — verify row counts",
    "delay": "2h"
  }'
```

**JavaScript**

```javascript
await fetch('https://api.pocketalert.app/v1/messages', {
  method: 'POST',
  headers: { 'Token': 'your-api-key', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Check the migration',
    message: 'Started at 14:02 — verify row counts',
    delay: '2h'
  })
});
```

**Python**

```python
import requests

requests.post(
    'https://api.pocketalert.app/v1/messages',
    headers={'Token': 'your-api-key'},
    json={
        'title': 'Check the migration',
        'message': 'Started at 14:02 — verify row counts',
        'delay': '2h'
    }
)
```

Pesan yang dijadwalkan mengembalikan `201` dengan `"scheduled": true`, bukan pesan yang sudah terkirim:

```json
{
  "tid": "n8k2vq7pxr4m",
  "scheduled": true,
  "status": "pending",
  "title": "Check the migration",
  "deliver_at": "09.08.2026 16:02:00",
  "deliver_at_utc": "2026-08-09T13:02:00Z",
  "tz": "Europe/Berlin"
}
```

Simpan `tid` — itulah yang digunakan untuk membatalkan.

## Melihat daftar pesan terjadwal (GET)

```
GET https://api.pocketalert.app/v1/messages/scheduled
```

Secara default mengembalikan pesan yang masih menunggu, diurutkan dari yang paling dekat.

| Query parameter | Nilai | Deskripsi |
|-----------------|-------|-----------|
| `status` | `pending`, `sending`, `sent`, `canceled`, `failed`, `all` | Filter berdasarkan status. Defaultnya `pending`. |

```bash
curl -X GET "https://api.pocketalert.app/v1/messages/scheduled?status=all" \
  -H "Token: your-api-key"
```

Setiap item memuat `tid`, `title`, `message`, `priority`, `status`, `deliver_at`, `deliver_at_utc`, `tz`, `application`, `device`, `created_at`, dan `actions` jika pesan memiliki tombol.

## Membatalkan (DELETE)

```
DELETE https://api.pocketalert.app/v1/messages/scheduled/{tid}
```

```bash
curl -X DELETE "https://api.pocketalert.app/v1/messages/scheduled/n8k2vq7pxr4m" \
  -H "Token: your-api-key"
```

| Status | Arti |
|:------:|------|
| `200` | Dibatalkan. Lampiran apa pun ikut dihapus. |
| `404` | Tidak ada pesan terjadwal dengan `tid` tersebut di akun Anda |
| `409` | Sudah terkirim, sedang dikirim, atau sudah dibatalkan |

Pembatalan ditangani dengan aman terhadap dispatcher: jika pengiriman sudah dimulai, Anda mendapat `409` alih-alih pesan yang setengah dibatalkan.

## Aturan yang perlu diketahui

**Batas waktu ke depan adalah 30 hari.** Waktu yang lebih jauh akan ditolak.

**Waktu di masa lalu mengembalikan `400`**, dengan toleransi 60 detik untuk perbedaan jam. Dalam rentang itu, pesan langsung dikirim.

**Level dan paket ditentukan saat penjadwalan, bukan saat pengiriman.** Pesan yang dijadwalkan sebagai `critical` pada paket berbayar tetap tiba sebagai `critical` meskipun paket berakhir di antara waktu tersebut. Penjadwalan adalah sebuah janji.

**Batas harian dihitung saat penjadwalan.** Pesan terjadwal dihitung ke [batas pesan harian](https://info.pocketalert.app/features/daily-limits.md) pada hari Anda menjadwalkannya, bukan pada hari pengirimannya — dan pengiriman tidak pernah diblokir oleh batas. Jika melampaui batas, permintaan penjadwalan itu sendiri mengembalikan `429`. Pembatalan tidak mengembalikan kuota.

**Lampiran diunggah saat penjadwalan** dan ditautkan ke pesan saat pengiriman. Pembatalan menghapus file yang tersimpan.

**Pesan yang terlambat dikirim terlambat, bukan dibuang.** Jika layanan restart melewati waktu pengiriman, pesan akan dikirim pada siklus berikutnya alih-alih hilang.

**Konten dienkripsi saat disimpan** menggunakan kunci pribadi Anda sejak saat Anda menjadwalkannya, sama seperti pesan biasa.

> **Warning: Fitur berbayar**
>
> Pengiriman terjadwal tersedia pada paket berbayar. Permintaan paket gratis dengan `send_at` atau `delay` mengembalikan `403` — tidak ada yang diabaikan secara diam-diam.

## Terkait

- [Create Message](https://info.pocketalert.app/api/messages/create.md) — referensi permintaan lengkap
- [Tingkat prioritas](https://info.pocketalert.app/features/priority-levels.md) — cara peringatan yang terkirim berperilaku
- [Tombol aksi](https://info.pocketalert.app/features/action-buttons.md) — pesan terjadwal mempertahankan tombolnya
- [Batas pesan harian](https://info.pocketalert.app/features/daily-limits.md) — cara pesan terjadwal dihitung
