Dokumentasi API

Langkah awal

Permintaan pertama

Buat token, kirim OTP, lalu verifikasi kodenya. Contoh di bawah memakai cURL, tetapi setiap endpoint juga punya tab Node.js dan PHP.

1
Buat token API
Pilih izin otp-sms:create atau otp-whatsapp:create sesuai kanal yang dipakai.
2
Kirim permintaan OTP
Sertakan Bearer token dan Idempotency-Key yang unik.
3
Verifikasi kode
Kirim kode yang diterima penerima ke endpoint verifikasi.

bashPOST /v1/otp/sms/send

curl -X POST "https://app.notif.biz/api/v1/otp/sms/send" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: otp-login-2026-11-05-001" \
  -d '{
  "recipient": "081234567890",
  "template": "Kode OTP notif.biz: {otp}. Berlaku 5 menit. Jangan bagikan kode ini kepada siapa pun.",
  "ttl": 300
}'

Buat token Lihat detail endpoint

Alur status OTP

pending→accepted→delivered→verified

accepted berarti layanan pengiriman sudah menerima pesan. delivered berarti pesan sampai ke penerima. verified baru terjadi setelah kode diverifikasi.

Keamanan

Autentikasi

Setiap permintaan wajib membawa Bearer token. Token mewakili akun beserta izin aksesnya, jadi jangan pernah menyimpannya di browser, aplikasi mobile, atau repositori publik.

Format header:

Authorization: Bearer YOUR_API_TOKEN

Token yang dicabut, sudah kedaluwarsa, atau akun yang tidak aktif akan menghasilkan HTTP 401. Token valid tanpa izin yang sesuai menghasilkan HTTP 403.

Setiap token hanya bisa mengakses data milik akun pemiliknya. ID dari akun lain akan menghasilkan 404.

Izin token

Pilih izin sesedikit mungkin sesuai kebutuhan aplikasi.

sms:createBisa membuat batch SMS.
sms:readBisa melihat batch dan status pesan SMS.
rcs:createBisa membuat batch RCS.
rcs:readBisa melihat batch dan status pesan RCS.
mms:createBisa membuat batch MMS dengan media.
mms:readBisa melihat batch dan status pesan MMS.
otp-sms:createBisa mengirim kode OTP lewat SMS.
otp-sms:verifyBisa memverifikasi kode OTP yang dikirim lewat SMS.
otp-sms:readBisa melihat status permintaan OTP SMS.
otp-whatsapp:createBisa mengirim kode OTP lewat WhatsApp.
otp-whatsapp:verifyBisa memverifikasi kode OTP yang dikirim lewat WhatsApp.
otp-whatsapp:readBisa melihat status permintaan OTP WhatsApp.
whatsapp:createBisa mengirim pesan WhatsApp Marketing.
whatsapp:readBisa melihat batch dan status pesan WhatsApp Marketing.

Konsistensi

Aturan umum permintaan

Semua endpoint mengikuti pola yang sama supaya integrasi mudah diprediksi.

Base path: /api/v1
Versi: v1
ID: ULID
Waktu: UTC, format ISO 8601
Format tanggal: ISO 8601 dengan timezone
Nomor telepon: 08xxx dinormalkan ke 628xxx
Penyamaran: Nomor disamarkan di respons
Halaman: 20 batch per halaman

Aman saat coba ulang

Idempotensi

Coba ulang tanpa takut batch dobel atau saldo tertahan dua kali. Pakai Idempotency-Key di setiap operasi tulis.

POST SMS dan WhatsApp wajib mengirim Idempotency-Key. OTP menerima header yang sama dan sebaiknya selalu dikirim.

Key yang sama dengan body yang sama akan mengembalikan hasil sebelumnya.
Key yang sama dengan body berbeda menghasilkan HTTP 409 IDEMPOTENCY_KEY_REUSED.
Panjang key maksimal 255 karakter.

httpheader permintaan

Idempotency-Key: batch-2026-11-05-001

Operasional

Batas dan kuota

Batas berikut berlaku di API. Layanan pengiriman atau konfigurasi akun bisa punya batas yang lebih ketat.

Batas dan kuota API
Parameter	Nilai	Keterangan
Batas permintaan	120 permintaan / menit	Dihitung per token dan per akun. Jika terlampaui, respons 429 menyertakan header Retry-After.
Penerima per batch SMS	1 sampai 1.000	Nomor harus unik dalam satu permintaan.
Panjang pesan	5.000 karakter	Berlaku untuk SMS, RCS, dan WhatsApp.
Media	URL HTTPS	Maksimal 2.048 karakter. Kirim URL, bukan file base64.
Media RCS	1 file	Tipe image, video, atau document. URL HTTPS maksimal 2.048 karakter dan ukuran file maksimal 25 MB.
Media MMS	1 file	Tipe image, audio, atau document. URL HTTPS maksimal 2.048 karakter dan ukuran file maksimal 25 MB.
Masa berlaku OTP	60 sampai 900 detik	Bawaannya 300 detik.
Jeda antarpermintaan OTP	60 detik	Maksimal 5 permintaan per jam untuk nomor dan kanal yang sama.
Percobaan verifikasi	5 kali	Jika habis, OTP berstatus failed dan harus diminta ulang.
Jumlah pesan per halaman	1 sampai 1.000	Bawaannya 100 pesan per halaman di detail batch.

Referensi

Layanan OTP

Kirim kode verifikasi lewat SMS atau WhatsApp, lalu verifikasi kodenya. Saldo ditahan sementara saat permintaan dibuat dan diselesaikan setelah layanan pengiriman menerima pesan.

4 endpoint

POST/v1/otp/sms/send

otp-sms:create

Kirim OTP lewat SMS

Membuat permintaan OTP baru untuk kanal SMS. Sistem membuat kode 6 digit, menyimpan hash-nya, menahan saldo sementara, lalu memasukkan pengiriman ke antrean OTP.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.
`Content-Type` application/json	Header	string	Wajib	Wajib disertakan jika permintaan punya body.
`Idempotency-Key` otp-login-2026-11-05-001	Header	string	Opsional	Sebaiknya selalu dikirim. Nilai yang sama akan mengembalikan permintaan OTP yang sudah dibuat sebelumnya.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`recipient` 081234567890	Body	string	Wajib	Nomor tujuan. Bisa diawali 0 atau 62; sistem akan menormalkannya ke format 62. Panjang 9 sampai 16 digit setelah dinormalkan.
`template` Kode OTP notif.biz: {otp}. Berlaku 5 menit. Jangan bagikan kode ini kepada siapa pun.	Body	string	Opsional	Template pesan, maksimal 255 karakter. Wajib memuat placeholder {otp} atau {code}. Jika dikosongkan, sistem memakai template bawaan.
`ttl` 300	Body	integer	Opsional	Masa berlaku OTP dalam detik, 60 sampai 900. Bawaannya 300.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashPOST /v1/otp/sms/send

curl -X POST "https://app.notif.biz/api/v1/otp/sms/send" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: otp-login-2026-11-05-001" \
  -d '{
  "recipient": "081234567890",
  "template": "Kode OTP notif.biz: {otp}. Berlaku 5 menit. Jangan bagikan kode ini kepada siapa pun.",
  "ttl": 300
}'

Respons berhasil

HTTP 202Permintaan OTP diterima dan sedang dikirim.

jsonresponse.json

{
  "success": true,
  "message": "OTP sedang dikirim.",
  "data": {
    "id": "01JBCDEFGHJKMNPQRSTVWXYZ",
    "channel": "sms",
    "recipient": "6281******890",
    "status": "pending",
    "expires_at": "2026-11-05T16:32:00+00:00",
    "created_at": "2026-11-05T16:27:00+00:00"
  }
}

Field respons
Field	Tipe	Deskripsi
`success`	boolean	true jika permintaan OTP berhasil dibuat.
`message`	string	Pesan yang bisa langsung ditampilkan ke pengguna.
`data.id`	string (ULID)	ID permintaan OTP. Simpan ID ini untuk memantau status dan memverifikasi kode.
`data.channel`	string	Kanal pengiriman: sms atau whatsapp.
`data.recipient`	string	Nomor tujuan yang sudah disamarkan.
`data.status`	string	Status awal, umumnya pending.
`data.expires_at`	string (ISO 8601)	Waktu OTP kedaluwarsa.
`data.created_at`	string (ISO 8601)	Waktu permintaan dibuat.
`debug_otp`	string	Hanya muncul di environment local dan testing. Jangan diandalkan di production.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak dikirim, tidak valid, sudah dicabut, atau sudah kedaluwarsa.
403	`FORBIDDEN`	Token tidak punya izin create atau verify untuk kanal OTP yang dipakai.
422	`VALIDATION_ERROR`	Nomor tidak valid, template tidak punya placeholder, TTL di luar rentang, atau masih kena cooldown.
429	`RATE_LIMIT_EXCEEDED`	Batas 120 permintaan per menit untuk token atau akun sudah terlampaui.
503	`OTP_DISABLED`	Layanan OTP sedang dinonaktifkan.
503	`OTP_SMS_DISABLED`	Kanal OTP SMS sedang dinonaktifkan.

Yang perlu diperhatikan

Nomor 081234567890 dinormalkan menjadi 6281234567890 sebelum disimpan.
Jeda 60 detik dan batas 5 permintaan per jam berlaku untuk setiap nomor dan kanal.
Pakai Idempotency-Key yang sama saat mencoba ulang agar saldo tidak tertahan dua kali.
Status awalnya pending. Periksa GET /v1/otp/{id} secara berkala untuk melihat apakah statusnya berubah menjadi accepted, delivered, atau failed.

POST/v1/otp/whatsapp/send

otp-whatsapp:create

Kirim OTP lewat WhatsApp

Membuat permintaan OTP baru untuk kanal WhatsApp. Pengiriman mengikuti konfigurasi layanan WhatsApp yang sedang aktif.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.
`Content-Type` application/json	Header	string	Wajib	Wajib disertakan jika permintaan punya body.
`Idempotency-Key` otp-login-2026-11-05-001	Header	string	Opsional	Sebaiknya selalu dikirim. Nilai yang sama akan mengembalikan permintaan OTP yang sudah dibuat sebelumnya.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`recipient` 081234567890	Body	string	Wajib	Nomor tujuan. Bisa diawali 0 atau 62; sistem akan menormalkannya ke format 62. Panjang 9 sampai 16 digit setelah dinormalkan.
`template` Kode OTP notif.biz: {otp}. Berlaku 5 menit. Jangan bagikan kode ini kepada siapa pun.	Body	string	Opsional	Template pesan, maksimal 255 karakter. Wajib memuat placeholder {otp} atau {code}. Jika dikosongkan, sistem memakai template bawaan.
`ttl` 300	Body	integer	Opsional	Masa berlaku OTP dalam detik, 60 sampai 900. Bawaannya 300.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashPOST /v1/otp/whatsapp/send

curl -X POST "https://app.notif.biz/api/v1/otp/whatsapp/send" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: otp-login-2026-11-05-001" \
  -d '{
  "recipient": "081234567890",
  "template": "Kode OTP notif.biz: {otp}. Berlaku 5 menit. Jangan bagikan kode ini kepada siapa pun.",
  "ttl": 300
}'

Respons berhasil

HTTP 202Permintaan OTP WhatsApp diterima dan sedang dikirim.

jsonresponse.json

{
  "success": true,
  "message": "OTP sedang dikirim.",
  "data": {
    "id": "01JBCDEFGHJKMNPQRSTVWXYA",
    "channel": "whatsapp",
    "recipient": "6281******890",
    "status": "pending",
    "expires_at": "2026-11-05T16:32:00+00:00",
    "created_at": "2026-11-05T16:27:00+00:00"
  }
}

Field respons
Field	Tipe	Deskripsi
`success`	boolean	true jika permintaan OTP berhasil dibuat.
`message`	string	Pesan yang bisa langsung ditampilkan ke pengguna.
`data.id`	string (ULID)	ID permintaan OTP. Simpan ID ini untuk memantau status dan memverifikasi kode.
`data.channel`	string	Kanal pengiriman: sms atau whatsapp.
`data.recipient`	string	Nomor tujuan yang sudah disamarkan.
`data.status`	string	Status awal, umumnya pending.
`data.expires_at`	string (ISO 8601)	Waktu OTP kedaluwarsa.
`data.created_at`	string (ISO 8601)	Waktu permintaan dibuat.
`debug_otp`	string	Hanya muncul di environment local dan testing. Jangan diandalkan di production.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak dikirim, tidak valid, sudah dicabut, atau sudah kedaluwarsa.
403	`FORBIDDEN`	Token tidak punya izin create atau verify untuk kanal OTP yang dipakai.
422	`VALIDATION_ERROR`	Nomor tidak valid, template tidak punya placeholder, TTL di luar rentang, atau masih kena cooldown.
429	`RATE_LIMIT_EXCEEDED`	Batas 120 permintaan per menit untuk token atau akun sudah terlampaui.
503	`OTP_DISABLED`	Layanan OTP sedang dinonaktifkan.
503	`OTP_WHATSAPP_DISABLED`	Kanal OTP WhatsApp sedang dinonaktifkan.
503	`WHATSAPP_DISABLED`	Layanan WhatsApp sedang dinonaktifkan, jadi OTP WhatsApp tidak bisa dikirim.

Yang perlu diperhatikan

Endpoint ini punya batas permintaan sendiri, terpisah dari OTP SMS.
Jika layanan WhatsApp dimatikan, responsnya 503 dengan kode WHATSAPP_DISABLED.
Jika layanan WhatsApp belum siap, permintaan bisa berakhir failed setelah diproses antrean.

POST/v1/otp/verify

otp-sms:verifyotp-whatsapp:verify

Verifikasi kode OTP

Memverifikasi kode OTP terbaru yang masih berlaku untuk nomor dan kanal tertentu. Setiap kode yang salah menambah jumlah percobaan.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.
`Content-Type` application/json	Header	string	Wajib	Wajib disertakan jika permintaan punya body.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`recipient` 081234567890	Body	string	Wajib	Nomor yang menerima OTP. Format 0 atau 62 sama-sama diterima.
`code` 123456	Body	string	Wajib	Kode OTP, 4 sampai 10 karakter.
`channel` sms	Body	string	Opsional	Batasi pencarian ke kanal sms atau whatsapp. Jika dikosongkan, sistem memakai OTP terbaru untuk nomor itu.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashPOST /v1/otp/verify

curl -X POST "https://app.notif.biz/api/v1/otp/verify" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "recipient": "081234567890",
  "code": "123456",
  "channel": "sms"
}'

Respons berhasil

HTTP 200Kode OTP valid dan sudah ditandai verified.

jsonresponse.json

{
  "success": true,
  "message": "Verifikasi OTP berhasil.",
  "data": {
    "id": "01JBCDEFGHJKMNPQRSTVWXYZ",
    "channel": "sms",
    "recipient": "6281******890",
    "status": "verified",
    "verified_at": "2026-11-05T16:28:00+00:00"
  }
}

Field respons
Field	Tipe	Deskripsi
`success`	boolean	true jika kodenya valid.
`message`	string	Pesan yang bisa langsung ditampilkan ke pengguna.
`data.id`	string (ULID)	ID permintaan OTP yang diverifikasi.
`data.channel`	string	Kanal OTP.
`data.recipient`	string	Nomor yang sudah disamarkan.
`data.status`	string	verified.
`data.verified_at`	string (ISO 8601)	Waktu verifikasi berhasil.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak valid atau sudah tidak bisa dipakai.
403	`FORBIDDEN`	Token tidak punya izin create atau verify untuk kanal OTP yang dipakai.
422	`VALIDATION_ERROR`	Kode salah, OTP kedaluwarsa, percobaan habis, atau permintaannya tidak ditemukan.
429	`RATE_LIMIT_EXCEEDED`	Batas permintaan per menit sudah terlampaui.

Yang perlu diperhatikan

Maksimal 5 percobaan verifikasi untuk setiap permintaan OTP.
OTP yang sudah verified tidak bisa diverifikasi ulang.
Jika channel dikosongkan, sistem memilih OTP terbaru yang masih pending atau accepted untuk nomor itu.

GET/v1/otp/{id}

otp-sms:readotp-whatsapp:read

Lihat status permintaan OTP

Menampilkan status terkini satu permintaan OTP. Pakai endpoint ini untuk memantau status setelah pengiriman diterima.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`id` 01JBCDEFGHJKMNPQRSTVWXYZ	Path	string (ULID)	Wajib	ID permintaan OTP yang dikembalikan endpoint pengiriman.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashGET /v1/otp/{id}

curl -X GET "https://app.notif.biz/api/v1/otp/01JBCDEFGHJKMNPQRSTVWXYZ" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Respons berhasil

HTTP 200Status permintaan OTP.

jsonresponse.json

{
  "data": {
    "id": "01JBCDEFGHJKMNPQRSTVWXYZ",
    "channel": "sms",
    "recipient": "6281******890",
    "status": "accepted",
    "provider_status": "accepted",
    "attempts": 0,
    "max_attempts": 5,
    "expires_at": "2026-11-05T16:32:00+00:00",
    "verified_at": null,
    "created_at": "2026-11-05T16:27:00+00:00"
  }
}

Field respons
Field	Tipe	Deskripsi
`data.id`	string (ULID)	ID permintaan OTP.
`data.channel`	string	sms atau whatsapp.
`data.recipient`	string	Nomor yang sudah disamarkan.
`data.status`	string	pending, accepted, delivered, verified, failed, atau expired.
`data.provider_status`	string\|null	Status dari layanan pengiriman. Nilai yang umum muncul: accepted, rejected, disabled, no_connected_device, exception, provider_not_configured. Layanan SMS bisa mengirim kode numerik.
`data.attempts`	integer	Jumlah percobaan verifikasi yang sudah dicoba.
`data.max_attempts`	integer	Batas percobaan verifikasi.
`data.expires_at`	string (ISO 8601)	Waktu OTP kedaluwarsa.
`data.verified_at`	string\|null (ISO 8601)	Waktu verifikasi berhasil.
`data.created_at`	string (ISO 8601)	Waktu permintaan dibuat.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak valid.
403	`FORBIDDEN`	Token tidak punya izin baca untuk kanal OTP itu.
404	`NOT_FOUND`	ID tidak ditemukan atau bukan milik akun token.

Yang perlu diperhatikan

Aman untuk diperiksa setiap 2 sampai 5 detik selama statusnya masih pending.
Status accepted berarti layanan pengiriman sudah menerima pesan, bukan jaminan kodenya sudah dibaca penerima.

Referensi

SMS, RCS, dan MMS Marketing

Buat batch SMS, RCS, atau MMS, pantau status batch, lalu cek status tiap penerima.

4 endpoint

GET/v1/sms

sms:readrcs:readmms:read

Daftar batch SMS, RCS, dan MMS

Menampilkan batch milik akun Anda yang sesuai dengan izin baca, diurutkan dari yang terbaru. Setiap halaman berisi 20 batch.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`page` 1	Query	integer	Opsional	Nomor halaman. Bawaannya 1, dan setiap halaman berisi 20 batch.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashGET /v1/sms

curl -X GET "https://app.notif.biz/api/v1/sms?page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Respons berhasil

HTTP 200Daftar batch dengan pagination.

jsonresponse.json

{
  "data": [
    {
      "batch_id": "01JBCDEFGHJKMNPQRSTVWXYZ",
      "name": "Promo November",
      "type": "SMS",
      "status": "running",
      "recipient_count": 250
    }
  ],
  "links": {
    "first": "https://api.example.com/api/v1/sms?page=1",
    "last": "https://api.example.com/api/v1/sms?page=3",
    "prev": null,
    "next": "https://api.example.com/api/v1/sms?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "per_page": 20,
    "to": 20,
    "total": 45
  }
}

Field respons
Field	Tipe	Deskripsi
`data[].batch_id`	string (ULID)	ID batch.
`data[].name`	string	Nama batch.
`data[].type`	string	SMS, RCS, atau MMS.
`data[].status`	string	Status siklus hidup batch (lifecycle_status).
`data[].recipient_count`	integer	Jumlah penerima.
`links`	object	URL untuk berpindah halaman.
`meta`	object	Metadata halaman.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak valid.
403	`FORBIDDEN`	Token tidak punya izin baca untuk tipe batch atau pesan itu.
429	`RATE_LIMIT_EXCEEDED`	Batas permintaan per menit sudah terlampaui.

Yang perlu diperhatikan

Daftar ini tidak memuat pesan individual. Untuk itu, pakai endpoint detail batch.
Pakai query page untuk berpindah halaman.

POST/v1/sms

sms:creatercs:createmms:create

Buat batch SMS, RCS, atau MMS

Membuat batch baru sesuai tipe pesan. Izin yang dibutuhkan mengikuti tipe: sms:create, rcs:create, atau mms:create. Header Idempotency-Key wajib disertakan.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.
`Content-Type` application/json	Header	string	Wajib	Wajib disertakan jika permintaan punya body.
`Idempotency-Key` batch-2026-11-05-001	Header	string	Wajib	Kunci unik, maksimal 255 karakter. Pakai nilai yang sama saat mencoba ulang agar batch tidak dibuat dua kali.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`name` Promo November	Body	string	Opsional	Nama batch, maksimal 255 karakter. Jika dikosongkan, sistem memakai "API SMS" atau "API RCS".
`recipients` [ "081234567890", "081234567891" ]	Body	array<string>	Wajib	Daftar nomor. Minimal 1, maksimal 1.000, dan harus unik. Nomor berawalan 08 akan dinormalkan menjadi 628.
`type` SMS	Body	string	Wajib	Jenis pesan: SMS, RCS, atau MMS.
`message` Promo spesial hari ini. Gunakan kode NOTIF20 untuk diskon 20%.	Body	string	Wajib	Isi pesan, maksimal 5.000 karakter.
`media`	Body	object	Opsional	Opsional untuk RCS, wajib untuk MMS, dan tidak boleh untuk SMS.
`media.url` https://cdn.example.com/promo-november.jpg	Body	string	Opsional	URL media HTTPS. Wajib jika media dikirim, maksimal 2.048 karakter.
`media.type` image	Body	string	Opsional	Untuk RCS: image, video, atau document. Untuk MMS: image, audio, atau document. Wajib jika media dikirim.
`mms_title` Promo November	Body	string	Opsional	Judul MMS, khusus tipe MMS, maksimal 80 karakter. Jika kosong, sistem memakai name atau potongan message.
`mms_type` 1	Body	integer	Opsional	Tipe MMS: 1 atau 2, khusus tipe MMS. Bawaannya 1.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashPOST /v1/sms

curl -X POST "https://app.notif.biz/api/v1/sms" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-2026-11-05-001" \
  -d '{
  "name": "Promo November",
  "recipients": [
    "081234567890",
    "081234567891"
  ],
  "type": "SMS",
  "message": "Promo spesial hari ini. Gunakan kode NOTIF20 untuk diskon 20%."
}'

Respons berhasil

HTTP 202Batch dibuat dan diterima untuk diproses.

jsonresponse.json

{
  "data": {
    "batch_id": "01JBCDEFGHJKMNPQRSTVWXYZ",
    "name": "Promo November",
    "type": "SMS",
    "status": "draft",
    "recipient_count": 2,
    "messages": [
      {
        "id": "01JBCDEFGHJKMNPQRSTVWXYA",
        "recipient": "628123***7890",
        "operator": null,
        "type": "SMS",
        "status": "pending",
        "sending_time": null,
        "count_sent": 0,
        "is_sent": false
      },
      {
        "id": "01JBCDEFGHJKMNPQRSTVWXYB",
        "recipient": "628123***7891",
        "operator": null,
        "type": "SMS",
        "status": "pending",
        "sending_time": null,
        "count_sent": 0,
        "is_sent": false
      }
    ]
  }
}

Field respons
Field	Tipe	Deskripsi
`data.batch_id`	string (ULID)	ID batch SMS, RCS, atau MMS.
`data.name`	string	Nama batch.
`data.type`	string	SMS, RCS, atau MMS.
`data.status`	string	Status siklus hidup batch (lifecycle_status): draft, importing, pending, running, completed, failed, atau cancelled.
`data.recipient_count`	integer	Jumlah penerima di batch ini.
`data.messages`	array	Daftar pesan. Hanya ikut di respons pembuatan, tidak di daftar.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak valid.
403	`FORBIDDEN`	Token tidak punya izin create untuk tipe pesan yang dikirim.
409	`IDEMPOTENCY_KEY_REUSED`	Idempotency-Key sudah dipakai dengan body yang berbeda.
422	`VALIDATION_ERROR`	Idempotency-Key tidak ada atau lebih dari 255 karakter, atau ada field body yang tidak valid.
429	`RATE_LIMIT_EXCEEDED`	Batas permintaan per menit sudah terlampaui.

Yang perlu diperhatikan

Header Idempotency-Key wajib dan maksimal 255 karakter.
Jika mencoba ulang dengan key dan body yang sama, sistem mengembalikan batch yang sama.
Jika key-nya sama tetapi body-nya berbeda, hasilnya 409.
Batch baru berstatus draft. Pengiriman mengikuti konfigurasi layanan dan jadwal.
Pakai izin sesuai tipe: sms:create untuk SMS, rcs:create untuk RCS, dan mms:create untuk MMS.
RCS dan MMS memakai media HTTPS. Media diunduh dan disimpan sebelum batch dibuat; MMS wajib menyertakan media.

GET/v1/sms/{id}

sms:readrcs:readmms:read

Status satu pesan SMS, RCS, atau MMS

Menampilkan status satu pesan berdasarkan ID pesan, bukan ID batch.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`id` 01JBCDEFGHJKMNPQRSTVWXYA	Path	string (ULID)	Wajib	ID pesan dari field messages[].id.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashGET /v1/sms/{id}

curl -X GET "https://app.notif.biz/api/v1/sms/01JBCDEFGHJKMNPQRSTVWXYA" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Respons berhasil

HTTP 200Status satu pesan.

jsonresponse.json

{
  "data": {
    "id": "01JBCDEFGHJKMNPQRSTVWXYA",
    "recipient": "628123***7890",
    "operator": "Telkomsel",
    "type": "SMS",
    "status": "delivered",
    "sending_time": "2026-11-05T16:30:00+00:00",
    "count_sent": 1,
    "is_sent": true
  }
}

Field respons
Field	Tipe	Deskripsi
`data.id`	string (ULID)	ID pesan.
`data.recipient`	string	Nomor penerima yang sudah disamarkan.
`data.operator`	string\|null	Operator penerima, jika diketahui.
`data.type`	string	SMS, RCS, atau MMS.
`data.status`	string	pending, sending, submitted, delivered, atau failed.
`data.sending_time`	string\|null (ISO 8601)	Waktu pesan mulai diproses.
`data.count_sent`	integer	Berapa kali pengiriman dicoba.
`data.is_sent`	boolean	true jika pesan sudah selesai diproses.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak valid.
403	`FORBIDDEN`	Token tidak punya izin baca untuk tipe batch atau pesan itu.
404	`NOT_FOUND`	Pesan tidak ditemukan atau bukan milik akun token.

Yang perlu diperhatikan

Pakai ID pesan, bukan batch_id.
Jika yang Anda punya ID batch, pakai GET /v1/sms/batches/{id}.

GET/v1/sms/batches/{id}

sms:readrcs:readmms:read

Detail batch SMS, RCS, atau MMS

Menampilkan detail batch beserta daftar pesan yang dibagi per halaman. Izin baca harus sesuai dengan tipe batch.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`id` 01JBCDEFGHJKMNPQRSTVWXYZ	Path	string (ULID)	Wajib	ID batch yang ingin dilihat.
`per_page` 100	Query	integer	Opsional	Jumlah pesan per halaman, 1 sampai 1.000. Bawaannya 100.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashGET /v1/sms/batches/{id}

curl -X GET "https://app.notif.biz/api/v1/sms/batches/01JBCDEFGHJKMNPQRSTVWXYZ?per_page=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Respons berhasil

HTTP 200Detail batch dan halaman pesan.

jsonresponse.json

{
  "data": {
    "batch_id": "01JBCDEFGHJKMNPQRSTVWXYZ",
    "name": "Promo November",
    "type": "SMS",
    "status": "running",
    "recipient_count": 250,
    "messages": [
      {
        "id": "01JBCDEFGHJKMNPQRSTVWXYA",
        "recipient": "628123***7890",
        "operator": "Telkomsel",
        "type": "SMS",
        "status": "delivered",
        "sending_time": "2026-11-05T16:30:00+00:00",
        "count_sent": 1,
        "is_sent": true
      }
    ],
    "message_links": {
      "first": "https://api.example.com/api/v1/sms/batches/01JBCDEFGHJKMNPQRSTVWXYZ?page=1",
      "last": "https://api.example.com/api/v1/sms/batches/01JBCDEFGHJKMNPQRSTVWXYZ?page=3",
      "prev": null,
      "next": "https://api.example.com/api/v1/sms/batches/01JBCDEFGHJKMNPQRSTVWXYZ?page=2"
    },
    "message_meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 3,
      "per_page": 100,
      "to": 100,
      "total": 250
    }
  }
}

Field respons
Field	Tipe	Deskripsi
`data.batch_id`	string (ULID)	ID batch.
`data.name`	string	Nama batch.
`data.type`	string	SMS, RCS, atau MMS.
`data.status`	string	Status siklus hidup batch (lifecycle_status).
`data.recipient_count`	integer	Total penerima.
`data.messages[]`	array	Pesan pada halaman ini.
`data.message_links`	object	URL untuk berpindah halaman pesan.
`data.message_meta`	object	Metadata halaman pesan.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak valid.
403	`FORBIDDEN`	Token tidak punya izin baca untuk tipe batch atau pesan itu.
404	`NOT_FOUND`	Batch tidak ditemukan atau bukan milik akun token.

Yang perlu diperhatikan

Pakai per_page untuk mengatur jumlah pesan per halaman, antara 1 dan 1.000.
Endpoint ini tidak dibatasi 20 data seperti daftar batch.

Referensi

WhatsApp Marketing

Kirim pesan WhatsApp lewat perangkat yang terhubung, lalu pantau status batch dan tiap pesan.

4 endpoint

GET/v1/whatsapp

whatsapp:read

Daftar batch WhatsApp

Menampilkan batch WhatsApp milik akun Anda, diurutkan dari yang terbaru. Setiap halaman berisi 20 batch.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`page` 1	Query	integer	Opsional	Nomor halaman. Bawaannya 1, dan setiap halaman berisi 20 batch.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashGET /v1/whatsapp

curl -X GET "https://app.notif.biz/api/v1/whatsapp?page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Respons berhasil

HTTP 200Daftar batch WhatsApp dengan pagination.

jsonresponse.json

{
  "data": [
    {
      "batch_id": "01JBCDEFGHJKMNPQRSTVWXYZ",
      "name": "Follow up November",
      "status": "running",
      "recipient_count": 120
    }
  ],
  "links": {
    "first": "https://api.example.com/api/v1/whatsapp?page=1",
    "last": "https://api.example.com/api/v1/whatsapp?page=2",
    "prev": null,
    "next": "https://api.example.com/api/v1/whatsapp?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "per_page": 20,
    "to": 20,
    "total": 35
  }
}

Field respons
Field	Tipe	Deskripsi
`data[].batch_id`	string (ULID)	ID batch WhatsApp.
`data[].name`	string	Nama batch.
`data[].status`	string	Status siklus hidup batch (lifecycle_status).
`data[].recipient_count`	integer	Jumlah penerima.
`links`	object	URL untuk berpindah halaman.
`meta`	object	Metadata halaman.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak valid.
403	`FORBIDDEN`	Token tidak punya izin whatsapp:read.
429	`RATE_LIMIT_EXCEEDED`	Batas permintaan per menit sudah terlampaui.

Yang perlu diperhatikan

Daftar ini tidak memuat pesan individual.
Untuk melihat pesan per penerima, pakai endpoint detail batch.

POST/v1/whatsapp

whatsapp:create

Kirim pesan WhatsApp

Membuat batch WhatsApp berisi satu penerima lalu memasukkannya ke antrean. Pesan dikirim lewat perangkat yang terhubung. Header Idempotency-Key wajib disertakan.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.
`Content-Type` application/json	Header	string	Wajib	Wajib disertakan jika permintaan punya body.
`Idempotency-Key` batch-2026-11-05-001	Header	string	Wajib	Kunci unik, maksimal 255 karakter. Pakai nilai yang sama saat mencoba ulang agar batch tidak dibuat dua kali.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`recipient` 081234567890	Body	string	Wajib	Nomor tujuan. Bisa diawali 0 atau 62; sistem akan menormalkannya ke format 62.
`recipient_name` Budi Santoso	Body	string	Opsional	Nama penerima untuk keperluan internal, maksimal 255 karakter.
`message` Halo Budi, pesanan Anda sudah dikonfirmasi dan sedang diproses.	Body	string	Wajib	Isi pesan WhatsApp, maksimal 5.000 karakter.
`media`	Body	object	Opsional	Lampiran media, opsional.
`media.url` https://cdn.example.com/invoice-budi.jpg	Body	string	Opsional	URL media HTTPS. Wajib jika media dikirim, maksimal 2.048 karakter.
`media.type` image	Body	string	Opsional	image, video, audio, atau document. Wajib jika media dikirim.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashPOST /v1/whatsapp

curl -X POST "https://app.notif.biz/api/v1/whatsapp" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-2026-11-05-001" \
  -d '{
  "recipient": "081234567890",
  "recipient_name": "Budi Santoso",
  "message": "Halo Budi, pesanan Anda sudah dikonfirmasi dan sedang diproses."
}'

Respons berhasil

HTTP 202Batch WhatsApp dibuat dan diterima untuk diproses.

jsonresponse.json

{
  "data": {
    "batch_id": "01JBCDEFGHJKMNPQRSTVWXYZ",
    "name": "API WhatsApp",
    "status": "draft",
    "recipient_count": 1,
    "messages": [
      {
        "id": "01JBCDEFGHJKMNPQRSTVWXYA",
        "recipient": "628123***7890",
        "operator": null,
        "status": "pending",
        "sending_time": null,
        "count_sent": 0,
        "is_sent": false
      }
    ]
  }
}

Field respons
Field	Tipe	Deskripsi
`data.batch_id`	string (ULID)	ID batch WhatsApp.
`data.name`	string	Nama batch.
`data.status`	string	Status siklus hidup batch (lifecycle_status).
`data.recipient_count`	integer	Jumlah penerima.
`data.messages[]`	array	Pesan yang baru dibuat.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak valid.
403	`FORBIDDEN`	Token tidak punya izin whatsapp:create.
409	`IDEMPOTENCY_KEY_REUSED`	Idempotency-Key sudah dipakai dengan body yang berbeda.
422	`VALIDATION_ERROR`	Idempotency-Key tidak ada atau body tidak valid.
429	`RATE_LIMIT_EXCEEDED`	Batas permintaan per menit sudah terlampaui.
503	`SERVICE_UNAVAILABLE`	Tidak ada perangkat WhatsApp terhubung yang bisa dipakai akun ini.

Yang perlu diperhatikan

Jika tidak ada perangkat aktif, responsnya 503 dengan pesan No connected WhatsApp device is available.
Header Idempotency-Key wajib dan maksimal 255 karakter.
Jika mencoba ulang dengan key dan body yang sama, sistem mengembalikan batch yang sama.

GET/v1/whatsapp/{id}

whatsapp:read

Status satu pesan WhatsApp

Menampilkan status satu pesan WhatsApp berdasarkan ID pesan, bukan ID batch.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`id` 01JBCDEFGHJKMNPQRSTVWXYA	Path	string (ULID)	Wajib	ID pesan dari field messages[].id.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashGET /v1/whatsapp/{id}

curl -X GET "https://app.notif.biz/api/v1/whatsapp/01JBCDEFGHJKMNPQRSTVWXYA" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Respons berhasil

HTTP 200Status satu pesan WhatsApp.

jsonresponse.json

{
  "data": {
    "id": "01JBCDEFGHJKMNPQRSTVWXYA",
    "recipient": "628123***7890",
    "operator": null,
    "status": "delivered",
    "sending_time": "2026-11-05T16:30:00+00:00",
    "count_sent": 1,
    "is_sent": true
  }
}

Field respons
Field	Tipe	Deskripsi
`data.id`	string (ULID)	ID pesan WhatsApp.
`data.recipient`	string	Nomor penerima yang sudah disamarkan.
`data.operator`	string\|null	Operator penerima, jika diketahui.
`data.status`	string	pending, sending, submitted, delivered, failed, atau skipped.
`data.sending_time`	string\|null (ISO 8601)	Waktu pesan mulai diproses.
`data.count_sent`	integer	Berapa kali pengiriman dicoba.
`data.is_sent`	boolean	true jika pesan sudah selesai diproses.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak valid.
403	`FORBIDDEN`	Token tidak punya izin whatsapp:read.
404	`NOT_FOUND`	Pesan tidak ditemukan atau bukan milik akun token.

Yang perlu diperhatikan

Pakai ID pesan, bukan batch_id.
Jika yang Anda punya ID batch, pakai GET /v1/whatsapp/batches/{id}.

GET/v1/whatsapp/batches/{id}

whatsapp:read

Detail batch WhatsApp

Menampilkan detail batch WhatsApp beserta daftar pesan yang dibagi per halaman.

Header

Header
Nama	Lokasi	Tipe	Wajib	Deskripsi
`Authorization` Bearer YOUR_API_TOKEN	Header	string	Wajib	Token Bearer dari halaman API Token. Formatnya: Bearer notif.<64 karakter hex>.
`Accept` application/json	Header	string	Opsional	Isi application/json agar error validasi dan error autentikasi selalu dibalas dalam bentuk JSON.

Parameter

Parameter
Nama	Lokasi	Tipe	Wajib	Deskripsi
`id` 01JBCDEFGHJKMNPQRSTVWXYZ	Path	string (ULID)	Wajib	ID batch yang ingin dilihat.
`per_page` 100	Query	integer	Opsional	Jumlah pesan per halaman, 1 sampai 1.000. Bawaannya 100.

Contoh permintaan

Ganti YOUR_API_TOKEN dengan token aktif milik akun Anda.

bashGET /v1/whatsapp/batches/{id}

curl -X GET "https://app.notif.biz/api/v1/whatsapp/batches/01JBCDEFGHJKMNPQRSTVWXYZ?per_page=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Respons berhasil

HTTP 200Detail batch dan halaman pesan WhatsApp.

jsonresponse.json

{
  "data": {
    "batch_id": "01JBCDEFGHJKMNPQRSTVWXYZ",
    "name": "Follow up November",
    "status": "running",
    "recipient_count": 120,
    "messages": [
      {
        "id": "01JBCDEFGHJKMNPQRSTVWXYA",
        "recipient": "628123***7890",
        "operator": null,
        "status": "delivered",
        "sending_time": "2026-11-05T16:30:00+00:00",
        "count_sent": 1,
        "is_sent": true
      }
    ],
    "message_links": {
      "first": "https://api.example.com/api/v1/whatsapp/batches/01JBCDEFGHJKMNPQRSTVWXYZ?page=1",
      "last": "https://api.example.com/api/v1/whatsapp/batches/01JBCDEFGHJKMNPQRSTVWXYZ?page=2",
      "prev": null,
      "next": "https://api.example.com/api/v1/whatsapp/batches/01JBCDEFGHJKMNPQRSTVWXYZ?page=2"
    },
    "message_meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 2,
      "per_page": 100,
      "to": 100,
      "total": 120
    }
  }
}

Field respons
Field	Tipe	Deskripsi
`data.batch_id`	string (ULID)	ID batch WhatsApp.
`data.name`	string	Nama batch.
`data.status`	string	Status siklus hidup batch (lifecycle_status).
`data.recipient_count`	integer	Total penerima.
`data.messages[]`	array	Pesan pada halaman ini.
`data.message_links`	object	URL untuk berpindah halaman pesan.
`data.message_meta`	object	Metadata halaman pesan.

Error yang mungkin muncul

Kemungkinan error
HTTP	Code	Kondisi
401	`UNAUTHORIZED`	Token tidak valid.
403	`FORBIDDEN`	Token tidak punya izin whatsapp:read.
404	`NOT_FOUND`	Batch tidak ditemukan atau bukan milik akun token.

Yang perlu diperhatikan

Pakai per_page untuk mengatur jumlah pesan per halaman, antara 1 dan 1.000.
Endpoint ini tidak dibatasi 20 data seperti daftar batch.

Event

Webhook batch

Terima notifikasi setiap kali status batch SMS atau WhatsApp berubah. URL webhook diatur dari halaman Webhook dan wajib memakai HTTPS publik di port 443.

Atur URL webhookSecret dibuat saat URL webhook disimpan.

Header pengiriman

X-Webhook-Id: ID unik untuk setiap event. Pakai untuk mencegah pemrosesan ganda.
X-Webhook-Timestamp: Unix timestamp saat event dikirim.
X-Webhook-Signature: sha256=HMAC_SHA256(timestamp + "." + raw body, webhook secret).

Aturan pengiriman

Sukses: Endpoint Anda harus membalas HTTP 2xx dalam 20 detik.
Coba ulang: Maksimal 5 kali percobaan, dengan jeda 10, 60, 300, dan 900 detik.
Keamanan: HTTPS publik di port 443, tanpa redirect, dan tanpa kredensial di URL. Pengiriman dibatalkan jika URL webhook berubah.

Verifikasi signature

Hitung HMAC dari timestamp, titik, dan body mentah.

phpverifikasi signature

$secret = 'WEBHOOK_SECRET_DARI_HALAMAN_WEBHOOK';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');

$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$body, $secret);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

sms.batch.updatedDikirim setiap kali lifecycle_status atau status batch SMS berubah.

jsonpayload.json

{
  "id": "8f14e45f-ea5b-4f2f-9a2b-0e6f6d2a1c33",
  "event": "sms.batch.updated",
  "created_at": "2026-11-05T16:30:00+00:00",
  "data": {
    "id": "01JBCDEFGHJKMNPQRSTVWXYZ",
    "status": "running",
    "lifecycle_status": "running"
  }
}

whatsapp.batch.updatedDikirim setiap kali lifecycle_status atau status batch WhatsApp berubah.

jsonpayload.json

{
  "id": "a6f2c1d4-7b8e-4f0a-b3c1-9d2e4f6a8b10",
  "event": "whatsapp.batch.updated",
  "created_at": "2026-11-05T16:30:00+00:00",
  "data": {
    "id": "01JBCDEFGHJKMNPQRSTVWXYZ",
    "status": "running",
    "lifecycle_status": "running"
  }
}

Referensi

Status dan siklus hidup

Nilai status yang mungkin muncul di respons. Pakai nilai ini untuk logika pemantauan dan tampilan ke pengguna.

Status batch SMS, RCS, dan MMS

lifecycle_status

Status batch SMS, RCS, dan MMS
Nilai	Label	Penjelasan
`draft`	Draft	Batch baru dibuat dan belum masuk antrean.
`importing`	Importing	Batch sedang menyiapkan data penerima.
`pending`	Pending	Batch menunggu jadwal atau giliran diproses.
`running`	Running	Batch sedang mengirim pesan.
`completed`	Completed	Semua pesan sudah selesai diproses.
`failed`	Failed	Batch gagal diproses.
`cancelled`	Cancelled	Batch dibatalkan.

Status pesan SMS, RCS, dan MMS

status

Status pesan SMS, RCS, dan MMS
Nilai	Label	Penjelasan
`pending`	Pending	Pesan menunggu antrean.
`sending`	Sending	Pesan sedang dikirim.
`submitted`	Submitted	Layanan pengiriman sudah menerima pesan, tetapi laporan pengiriman belum final.
`delivered`	Delivered	Pesan sampai ke penerima.
`failed`	Failed	Pesan gagal dikirim.

Status batch WhatsApp

lifecycle_status

Status batch WhatsApp
Nilai	Label	Penjelasan
`draft`	Draft	Batch baru dibuat.
`importing`	Importing	Batch sedang menyiapkan data penerima.
`pending`	Pending	Batch menunggu giliran diproses.
`running`	Running	Batch sedang mengirim pesan.
`paused`	Paused	Batch dijeda.
`completed`	Completed	Semua pesan sudah selesai diproses.
`failed`	Failed	Batch gagal diproses.
`cancelled`	Cancelled	Batch dibatalkan.

Status pesan WhatsApp

status

Status pesan WhatsApp
Nilai	Label	Penjelasan
`pending`	Pending	Pesan menunggu antrean.
`sending`	Sending	Pesan sedang dikirim.
`submitted`	Submitted	Pesan sudah diserahkan ke layanan pengiriman.
`delivered`	Delivered	Pesan diterima penerima.
`failed`	Failed	Pesan gagal dikirim.
`skipped`	Skipped	Pesan dilewati, misalnya karena batch dibatalkan.

Status permintaan OTP

status

Status permintaan OTP
Nilai	Label	Penjelasan
`pending`	Pending	Permintaan dibuat dan menunggu hasil pengiriman.
`accepted`	Accepted	Layanan pengiriman sudah menerima pesan.
`delivered`	Delivered	Pesan OTP sampai ke penerima.
`verified`	Verified	Kode OTP berhasil diverifikasi.
`failed`	Failed	Pengiriman gagal atau layanan pengiriman belum siap.
`expired`	Expired	Kode OTP sudah lewat masa berlaku.

Status pengiriman OTP

provider_status

Status pengiriman OTP
Nilai	Label	Penjelasan
`accepted`	Accepted	Layanan pengiriman menerima pesan.
`rejected`	Rejected	Layanan pengiriman menolak pesan.
`disabled`	Disabled	Layanan atau kanal dinonaktifkan saat proses berjalan.
`no_connected_device`	No connected device	Tidak ada perangkat WhatsApp yang aktif.
`exception`	Exception	Terjadi exception saat menghubungi layanan pengiriman.
`provider_not_configured`	Provider not configured	Layanan pengiriman belum siap atau belum dikonfigurasi.

Penanganan masalah

Referensi error

Pakai kode error untuk menentukan tindakan. Jangan bergantung pada teks pesan karena teksnya bisa berubah.

Bentuk respons error. Endpoint OTP membalas dengan { success, message, error: { code, message, details? } }, sedangkan endpoint SMS dan WhatsApp memakai { message, errors? }. Kolom Kode di bawah adalah kategori error. Khusus OTP, nilai yang sama juga dikirim di error.code.

Referensi error API
HTTP	Kode	Penjelasan	Tindakan
401	`UNAUTHORIZED`	Token tidak validToken tidak dikirim, salah, sudah dicabut, atau sudah kedaluwarsa.	Buat token baru dari halaman API Token.
403	`FORBIDDEN`	Izin tidak cukupToken valid, tetapi tidak punya izin yang diminta endpoint ini.	Buat token dengan izin yang sesuai.
404	`NOT_FOUND`	Data tidak ditemukanID tidak ada atau bukan milik akun token.	Pastikan ID berasal dari akun yang sama.
409	`IDEMPOTENCY_KEY_REUSED`	Idempotency-Key bentrokKey yang sama sudah dipakai dengan body yang berbeda.	Pakai key baru setiap kali isi permintaannya berubah.
422	`VALIDATION_ERROR`	Validasi gagalAda field wajib yang kosong, formatnya salah, atau batas bisnis terlampaui.	Periksa bagian errors pada respons.
429	`RATE_LIMIT_EXCEEDED`	Batas permintaan terlampauiJumlah permintaan per menit sudah melewati batas.	Tunggu sesuai header Retry-After, lalu coba lagi.
500	`INTERNAL_ERROR`	Kesalahan serverTerjadi kesalahan tak terduga.	Coba lagi dengan Idempotency-Key yang sama. Hubungi support jika terus berulang.
503	`SERVICE_UNAVAILABLE`	Layanan tidak tersediaLayanan sedang nonaktif atau perangkat WhatsApp tidak tersedia.	Periksa status layanan, lalu coba lagi setelah aktif.
503	`OTP_DISABLED`	OTP nonaktifSemua layanan OTP sedang dinonaktifkan.	Aktifkan layanan OTP dari pengaturan.
503	`OTP_SMS_DISABLED`	OTP SMS nonaktifKanal OTP SMS sedang dinonaktifkan.	Pakai kanal WhatsApp atau aktifkan lagi kanal SMS.
503	`OTP_WHATSAPP_DISABLED`	OTP WhatsApp nonaktifKanal OTP WhatsApp sedang dinonaktifkan.	Pakai kanal SMS atau aktifkan lagi kanal WhatsApp.
503	`WHATSAPP_DISABLED`	WhatsApp nonaktifLayanan WhatsApp sedang dinonaktifkan.	Aktifkan layanan WhatsApp dari pengaturan.

Validasi marketing

jsonvalidasi 422

{
  "message": "The recipients field is required.",
  "errors": {
    "recipients": [
      "The recipients field is required."
    ]
  }
}

OTP saat layanan nonaktif

json503 OTP nonaktif

{
  "success": false,
  "message": "Pengiriman OTP lewat SMS sedang dinonaktifkan.",
  "error": {
    "code": "OTP_SMS_DISABLED",
    "message": "Pengiriman OTP lewat SMS sedang dinonaktifkan.",
    "details": {
      "service": "otp_sms",
      "channel": "sms"
    }
  }
}

Bantuan

Butuh bantuan?

Cek status layanan di atas dulu. Jika masalahnya masih berlanjut, sertakan ID permintaan, waktu kejadian, dan respons error saat menghubungi support.

Token

Buat, rotasi, dan cabut token dari halaman API Token.

Buka halaman token

Webhook

Atur URL dan lihat secret untuk verifikasi signature.

Buka Webhook