Create Message POST
Kirim push notification ke perangkat Anda.
Endpoint
POST https://api.pocketalert.app/v1/messagesAutentikasi
Wajib
Sertakan salah satu header berikut dalam permintaan Anda:
Permintaan
Header
| Header | Wajib | Deskripsi |
|---|---|---|
Content-Type | ✅ | application/json |
Token | ✅ | Kunci API Anda |
Authorization | ✅ | Bearer <jwt-token> |
* Salah satu dari Token atau Authorization wajib diisi
Parameter Body
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
title | string | ✅ | Judul notifikasi |
message | string | ✅ | Teks isi notifikasi |
application_id | string | ❌ | TID aplikasi untuk mengelompokkan pesan |
device_id | string | ❌ | TID perangkat tertentu, hilangkan untuk semua perangkat |
level | string | int | ❌ | Tingkat prioritas yang mengatur cara push dikirim. Menerima nama atau int (-2..2). priority diterima sebagai sinonim. Default mengikuti level default aplikasi, lalu default. |
actions | array | ❌ | Hingga 3 tombol aksi yang ditampilkan pada notifikasi. Lihat Tombol aksi. |
send_at | string | int | ❌ | Kirim pada waktu tertentu, bukan langsung. RFC3339, Unix timestamp, atau YYYY-MM-DD HH:MM. Lihat Pengiriman terjadwal. |
delay | string | ❌ | Kirim setelah jeda relatif — 30m, 2h, atau detik saja. Tidak dapat digunakan bersamaan dengan send_at. |
Tombol aksi
Setiap notifikasi dapat memuat hingga 3 tombol aksi. Tombol tetap berfungsi baik ketika aplikasi terbuka, berjalan di latar belakang, maupun tertutup. actions adalah array objek, dengan ukuran maksimal 2048 byte setelah dienkode JSON (data ini ikut dikirim di dalam push, yang dibatasi 4 KB; message yang panjang akan dipersingkat untuk memberi ruang):
| Field | Tipe | Wajib | Deskripsi |
|---|---|---|---|
type | string | ✅ | view (membuka URL), http (mengirim permintaan HTTP), atau copy (menyalin teks ke clipboard) |
label | string | ✅ | Teks tombol, ditampilkan apa adanya di Android dan iOS |
value | string | ✅ | Bergantung pada type — lihat di bawah |
value berdasarkan tipe:
view— URL yang akan dibuka, misalnya"https://pocketalert.app".http— string JSON yang mendeskripsikan permintaan:{"url":"https://…","method":"POST","headers":{…},"body":"…"}. Hanyaurlyang wajib;methoddefault-nyaGET. Permintaan dikirim dari perangkat di latar belakang tanpa membuka aplikasi, sehingga dapat menjangkau host di jaringan lokal ponsel. Jika permintaan gagal (status selain 2xx/3xx atau error jaringan), notifikasi dengan tombol Retry akan ditampilkan; permintaan tidak pernah dicoba ulang secara otomatis setelah kemungkinan sudah sampai ke server.copy— teks literal yang disalin ke clipboard.
Human-in-the-loop
Dua aksi http (misalnya Approve / Decline) membentuk panel kontrol satu ketukan — ideal untuk menyetujui tindakan agen LLM langsung dari notifikasi.
Fitur berbayar
Tombol aksi dihapus pada paket gratis: pesan tetap dikirim tanpa tombol, dan actions tidak divalidasi.
Lihat Tombol aksi untuk batasan, validasi, dan template webhook.
Level prioritas
| Level | Alias | Perilaku |
|---|---|---|
silent | min, -2 | Hanya masuk ke tray — tanpa suara atau getaran |
low | -1 | Senyap, tanpa interupsi |
default | normal, 0 (atau dihilangkan) | Banner + suara standar |
high | 1 | Sensitif waktu — menembus Fokus / ringkasan terjadwal |
critical | max, urgent, 2 | Membangunkan perangkat meski tombol senyap dan Jangan Ganggu aktif. Lihat Level prioritas |
WARNING
critical adalah fitur paket berbayar. Pada paket gratis, level ini otomatis diturunkan menjadi high. Nilai tidak valid (nama tidak dikenal atau int di luar rentang) mengembalikan 400.
Lihat Level prioritas untuk perilaku setiap level di iOS dan Android.
Pengiriman terjadwal
Tambahkan send_at atau delay — jangan keduanya — dan pesan akan disimpan terenkripsi hingga waktu pengiriman, alih-alih dikirim langsung.
| Parameter | Menerima | Contoh |
|---|---|---|
send_at | RFC3339, Unix timestamp, atau YYYY-MM-DD HH:MM | 2026-08-15T09:00:00Z, 1786867200 |
delay | Durasi gaya Go atau detik saja | 30m, 2h, 3600 |
Waktu tanpa offset dibaca mengikuti zona waktu akun Anda. Batas waktunya 30 hari, dan send_at di masa lalu mengembalikan 400 (dengan toleransi 60 detik untuk selisih jam).
Permintaan terjadwal mengembalikan 201 dengan "scheduled": true, status, deliver_at, dan deliver_at_utc, bukan pesan yang sudah terkirim. Daftarkan dengan GET /v1/messages/scheduled dan batalkan dengan DELETE /v1/messages/scheduled/{tid} — lihat Pengiriman terjadwal.
WARNING
Pengiriman terjadwal adalah fitur paket berbayar. Permintaan paket gratis yang menggunakan send_at atau delay mengembalikan 403.
Contoh Permintaan
curl -X POST "https://api.pocketalert.app/v1/messages" \
-H "Token: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"title": "Server Alert",
"message": "CPU usage exceeded 90%",
"application_id": "qm47b9pzxzxg",
"level": "critical",
"actions": [
{ "type": "view", "label": "Dashboard", "value": "https://status.example.com" },
{ "type": "http", "label": "Restart", "value": "{\"url\":\"https://ops.example.com/restart\",\"method\":\"POST\"}" },
{ "type": "copy", "label": "Copy ID", "value": "incident-4821" }
]
}'const response = await fetch('https://api.pocketalert.app/v1/messages', {
method: 'POST',
headers: {
'Token': 'your-api-key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
title: 'Server Alert',
message: 'CPU usage exceeded 90%',
application_id: 'qm47b9pzxzxg'
})
});
const data = await response.json();
console.log(data);import requests
response = requests.post(
'https://api.pocketalert.app/v1/messages',
headers={
'Token': 'your-api-key',
'Content-Type': 'application/json'
},
json={
'title': 'Server Alert',
'message': 'CPU usage exceeded 90%',
'application_id': 'qm47b9pzxzxg'
}
)
print(response.json())$response = Http::withHeaders([
'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/messages', [
'title' => 'Server Alert',
'message' => 'CPU usage exceeded 90%',
'application_id' => 'qm47b9pzxzxg',
]);
return $response->json();Respons
Respons Sukses
201 Created
Pesan berhasil dibuat
| Field | Tipe | Deskripsi |
|---|---|---|
tid | string | Pengidentifikasi unik pesan |
title | string | Judul pesan |
message | string | Isi pesan |
application | string | Nama aplikasi (jika ditentukan) |
device | string | Nama perangkat tujuan |
actions | array | Tombol aksi yang dikembalikan (hanya jika dikirim) |
created_at | string | Waktu pembuatan |
{
"tid": "jb4xw9elz28g",
"title": "Server Alert",
"message": "CPU usage exceeded 90%",
"application": "Monitoring",
"device": "iPhone",
"actions": [
{ "type": "view", "label": "Dashboard", "value": "https://status.example.com" }
],
"created_at": "18.01.2026 15:35:35"
}Header Kuota
Respons memuat penggunaan batas harian hari ini (dihilangkan pada paket tanpa batas):
| Header | Deskripsi |
|---|---|
X-PA-Daily-Limit | Jumlah pesan yang diizinkan per hari pada paket Anda |
X-PA-Daily-Remaining | Sisa pesan hari ini, setelah pesan ini |
X-PA-Daily-Reset | Unix timestamp (detik) untuk reset berikutnya, 00:00 UTC |
Respons Error
| Status | Deskripsi |
|---|---|
400 | Bad Request — title atau message tidak ada, level tidak valid, atau pada paket berbayar, actions tidak valid |
401 | Unauthorized — Token tidak valid atau tidak ada |
403 | Forbidden — send_at atau delay pada paket gratis |
404 | Not Found — application_id atau device_id tidak ada |
429 | Batas harian tercapai — pesan tidak disimpan maupun dikirim. Tunggu selama Retry-After detik atau tingkatkan paket Anda. Lihat Batas pesan harian. |
{
"error": "Validation failed",
"details": {
"title": ["The title field is required"]
}
}Batas harian tercapai
Ketika kuota hari ini habis, pesan ditolak — tidak masuk antrean — hingga 00:00 UTC. Retry-After berisi jumlah detik tersisa hingga reset.
HTTP/1.1 429 Too Many Requests
Retry-After: 30142
X-PA-Daily-Limit: 50
X-PA-Daily-Remaining: 0
X-PA-Daily-Reset: 1790035200{
"error": "Daily message limit reached (50/50). New messages are rejected until 00:00 UTC. Upgrade your plan to raise the limit.",
"limit": 50,
"used": 50,
"resets_at": "2026-09-22T00:00:00Z",
"upgrade_url": "https://pocketalert.app/pricing"
}Menghapus pesan tidak mengembalikan kuota. Periksa penggunaan hari ini dengan GET /v1/messages/usage.