Referensi API

Semua endpoint /v1: trigger, bulk, status event, subscriber, preferensi, inbox, log pesan, dan workflow.

Di halaman ini

Format Respons & Kode Error
POST /events/trigger
POST /events/bulk
GET & DELETE /events/{id}
Subscribers
Preferensi Notifikasi
Inbox API
Log Pesan
GET /workflows

#Format Respons & Kode Error

Base URL: https://api.notifora.my.id/v1. Semua body JSON UTF-8.

Sukses

{ "data": { }, "meta": { "request_id": "req_8f3a…" } }

Error

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "details": { "to.subscriberId": ["The to.subscriber id field is required."] },
    "request_id": "req_zkaannwbmt9j9gmv"
  }
}

HTTP	code	Arti & tindakan
401	`unauthenticated`	API key hilang, salah, atau dicabut
402	`quota_exceeded`	Kuota event bulanan habis; upgrade plan
403	`forbidden`	Tidak punya akses
404	`not_found`	Workflow, event, atau subscriber tidak ditemukan
409	`idempotency_conflict`	Lihat Idempotency
422	`validation_failed`	Input tidak valid; lihat `details`
422	`workflow_inactive`	Workflow belum dipublish / dinonaktifkan
429	`rate_limited`	Tunggu sesuai `Retry-After`
5xx	`server_error`	Coba lagi dengan backoff; sertakan `request_id` saat menghubungi support

Header yang selalu ada: X-Request-Id, X-RateLimit-*. Paginasi memakai cursor: ?limit=50&cursor=… (maks. 100); cursor berikutnya ada di meta.next_cursor.

#POST /events/trigger

POST /v1/events/trigger

Memicu workflow untuk satu penerima. Event disimpan durable sebelum respons, lalu diproses di background.

Field	Tipe	Wajib	Keterangan
`workflow`	string	Ya	`trigger key` workflow yang sudah aktif
`to`	string \| object	Ya	String = `subscriberId`. Objek: `subscriberId` (wajib), `email`, `phone`, `telegramChatId`, `firstName`, `lastName`, `locale`, `timezone`, `data`. Hanya field yang dikirim yang diperbarui.
`payload`	object	Tidak	Data untuk template (`{{ payload.* }}`). Maks. 64 KB.
`overrides`	object	Tidak	Ganti subject/isi per channel; lihat Override Template

Request

{
  "workflow": "order-confirmed",
  "to": {
    "subscriberId": "usr_102",
    "email": "[email protected]",
    "phone": "0812-3456-7890",
    "telegramChatId": "123456789",
    "firstName": "Budi",
    "locale": "id",
    "timezone": "Asia/Jakarta",
    "data": { "plan": "gold" }
  },
  "payload": { "invoiceId": "INV-9901", "amount": 450000 }
}

202 Accepted

{ "data": { "event_id": "01m5y…", "status": "QUEUED", "workflow": "order-confirmed" }, "meta": { "request_id": "req_…" } }

Nomor telepon dinormalisasi ke E.164 (0812-3456-7890 → +6281234567890).
Subscriber dibuat otomatis bila belum ada, dan diperbarui bila sudah.
Body maksimum 256 KB. Sertakan X-Idempotency-Key pada pemanggilan yang bisa di-retry.

#POST /events/bulk

POST /v1/events/bulk

Hingga 100 trigger dalam satu request. Setiap item divalidasi sendiri; satu item gagal tidak membatalkan yang lain.

Request

{ "events": [
  { "workflow": "order-confirmed", "to": "usr_1", "payload": { "invoiceId": "A" } },
  { "workflow": "order-confirmed", "to": "usr_2", "payload": { "invoiceId": "B" } }
] }

202 — hasil per item

{ "data": [
  { "index": 0, "status": "QUEUED", "event_id": "01m5y…" },
  { "index": 1, "status": "REJECTED", "error": { "code": "workflow_inactive", "message": "…" } }
] }

#GET & DELETE /events/{id}

GET /v1/events/{event_id}

Status eksekusi dan ringkasan tiap step.

200 OK

{ "data": {
  "event_id": "01m5y…", "workflow": "order-confirmed", "status": "COMPLETED",
  "created_at": "2026-10-27T10:31:30+00:00", "finished_at": "2026-10-27T10:31:31+00:00",
  "steps": [
    { "order": 1, "name": "Inbox", "type": "CHANNEL", "status": "COMPLETED", "skip_reason": null, "message_id": "01m5…", "message_status": "DELIVERED" },
    { "order": 2, "name": "WhatsApp", "type": "CHANNEL", "status": "FAILED", "skip_reason": null, "message_id": "01m5…", "message_status": "FAILED" }
  ]
} }

DELETE /v1/events/{event_id}

Membatalkan eksekusi yang belum selesai (mis. masih menunggu delay). Step yang sedang diproses dibiarkan selesai; sisanya dilewati dengan alasan canceled. Eksekusi yang sudah final → 422.

#Subscribers

PUT /v1/subscribers/{subscriberId}

Membuat atau memperbarui (upsert) penerima. Field opsional: email, phone, telegramChatId, firstName, lastName, locale, timezone, data (digabung dengan data yang ada).

bash

curl -X PUT https://api.notifora.my.id/v1/subscribers/usr_102 \
  -H "Authorization: Bearer $NOTIFORA_KEY" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","phone":"0812-3456-7890","firstName":"Budi"}'

GET /v1/subscribers/{subscriberId}

DELETE /v1/subscribers/{subscriberId}

DELETE menghapus profil, preferensi, pesan inbox, dan event terkait secara permanen (hak penghapusan data). Tidak dapat dibatalkan.

#Preferensi Notifikasi

GET /v1/subscribers/{subscriberId}/preferences

PUT /v1/subscribers/{subscriberId}/preferences

PUT body

{ "preferences": [
  { "channel": "WHATSAPP", "enabled": false },                        // global: matikan WhatsApp untuk semua workflow
  { "channel": "EMAIL", "workflow": "promo-weekly", "enabled": false } // hanya untuk workflow ini
] }

channel: WHATSAPP, EMAIL, TELEGRAM, IN_APP. Aturan lengkap ada di Preferensi & Opt-out.

#Inbox API

GET /v1/subscribers/{subscriberId}/inbox

Parameter: unread=1, limit, cursor. Respons memuat meta.unread_count dan meta.next_cursor.

json

{ "data": [ { "id": "01m5…", "title": "Pesanan INV-9901 dikonfirmasi", "body": "Halo Budi…", "action_url": null, "data": null, "read_at": null, "created_at": "2026-10-27T10:31:30+00:00" } ],
  "meta": { "next_cursor": null, "unread_count": 1 } }

POST /v1/subscribers/{subscriberId}/inbox/read

Body: {"ids":["01m5…"]} atau {"all":true}. Membalas jumlah ditandai dan unread terbaru, serta menyiarkan perubahan ke semua tab yang terhubung.

POST /v1/subscribers/{subscriberId}/inbox-token

Menerbitkan token untuk widget real-time. Lihat Alur Token Subscriber.

Agar pesan In-App memiliki tautan, sertakan _action_url (dan _data opsional) di payload trigger.

#Log Pesan

GET /v1/messages

Filter: status (QUEUED|SENT|DELIVERED|READ|FAILED), channel, subscriberId, limit, cursor.

GET /v1/messages/{message_id}

Detail satu pengiriman, termasuk riwayat percobaan (attempts[]: nomor, sukses/gagal, HTTP status, durasi).

Status	Arti
`QUEUED`	Menunggu giliran / sedang dicoba
`SENT`	Diterima provider
`DELIVERED`	Sampai ke perangkat penerima (dari webhook provider; In-App langsung)
`READ`	Dibaca penerima
`FAILED`	Gagal permanen; lihat `error_code`

Status hanya bergerak maju (QUEUED → SENT → DELIVERED → READ); webhook terlambat tidak memundurkan status.

#GET /workflows

GET /v1/workflows

Daftar workflow berstatus aktif beserta trigger_key, prioritas, versi, dan channel yang dipakai. Berguna untuk memvalidasi konfigurasi dari sisi aplikasi Anda. Pembuatan/penyuntingan workflow dilakukan di Console.