OTP adalah use case paling menuntut dari sebuah SMS gateway: harus cepat, andal, dan statusnya bisa dipercaya. Artikel ini merangkum cara mengirim OTP via API REST di BroadcastSMS beserta best practice integrasinya.
Endpoint Utama
Semua request diautentikasi dengan header X-API-Key (generate dari dashboard):
curl -X POST https://<BASE_URL_API>/api/v1/sms/send \
-H "Content-Type: application/json" \
-H "X-API-Key: sk-xxxxxxxx" \
-d '{
"destination_number": "6281234567890",
"message": "Kode OTP Anda: 4821. Jangan bagikan ke siapa pun.",
"priority": "HIGH"
}'
Poin penting dari payload di atas:
priority: "HIGH"memasukkan pesan ke antrean prioritas tinggi (RabbitMQ) — diproses sebelum campaign massal yang menumpuk di jalur LOW. Untuk OTP, selalu pakai HIGH.- Response berisi
message_idyang dipakai untuk cek status. - Format nomor tujuan memakai prefix negara (
62…).
Mode Bulk untuk Notifikasi Massal
Endpoint yang sama mendukung mode bulk — cocok untuk notifikasi bukan OTP (mis. pengingat jatuh tempo):
{
"messages": [
{ "destination_number": "6281111111111", "message": "Tagihan Anda jatuh tempo besok.", "priority": "LOW" },
{ "destination_number": "6282222222222", "message": "Tagihan Anda jatuh tempo besok.", "priority": "LOW" }
]
}
Cek Status Pengiriman (DLR)
curl https://<BASE_URL_API>/api/v1/sms/status/<message_id> \
-H "X-API-Key: sk-xxxxxxxx"
Status berkembang dari pending → sent/delivered/failed sesuai laporan operator (DLR). Untuk aplikasi production, jangan andalkan polling saja — pakai webhook.
Webhook Status
Daftarkan URL webhook di dashboard; server akan POST status setiap perubahan. Kalau endpoint Anda sedang down, server mencoba ulang otomatis hingga 3x — tapi tetap buat handler Anda idempoten (aman dipanggil dua kali untuk message_id yang sama).
Best Practice OTP di Sisi Aplikasi
- Jangan blokir UI menunggu DLR. Kirim OTP, langsung tampilkan form verifikasi; status delivery pantau di belakang.
- Timeout & retry yang sopan. Beri jeda minimal 30–60 detik sebelum user minta kirim ulang; batas 3–5 percobaan per nomor per jam.
- Hindari race condition — simpan hash OTP + timestamp di DB, bukan plaintext, dan invalidate setelah sukses verifikasi.
- Pantau rasio kegagalan per operator. Kalau satu operator mendadak tinggi failure-nya, cek kesehatan SIM/node untuk network group tersebut di dashboard.
- Rate limit di level bisnis Anda. Blacklist otomatis menolak nomor bermasalah (HTTP 403) — tambahkan juga guard sendiri anti abuse (mis. satu nomor maksimal N OTP/hari).
Uji Sebelum Production
- Kirim ke nomor uji Anda sendiri dan verifikasi timeline statusnya.
- Uji jalur gagal: matikan node, kirim OTP, pastikan retry 3x berjalan lalu status
failed+ saldo refund masuk. - Uji webhook dengan endpoint penerima dummy (mis. webhook.site) untuk memastikan payload sesuai ekspektasi.
Penutup
OTP via API pada dasarnya soal disiplin: antrean prioritas yang benar, penanganan status yang idempoten, dan fallback yang jelas saat gagal. Dokumentasi endpoint lengkap (termasuk nodes, SIM, dan blacklist management) ada di dokumentasi API kami.