Dokumentasi API SMS Gateway

Otentikasi & Base URL

Semua endpoint API memakai header X-API-Key. Kunci API dibuat otomatis untuk setiap tenant dan bisa dilihat di dashboard — simpan seperti layaknya password, jangan pernah menaruhnya di kode sisi klien yang publik. Ganti <BASE_URL_API> pada contoh di halaman ini dengan base URL API yang tertera di dashboard akun Anda.

X-API-Key: <API_KEY_ANDA>

Kirim SMS — Single

Endpoint utama: POST /api/v1/sms/send dengan Content-Type application/json. Prioritas HIGH untuk OTP/transaksional (didahulukan), LOW untuk campaign/promosi.

curl -X POST https://<BASE_URL_API>/api/v1/sms/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <API_KEY_ANDA>" \
  -d '{
    "destination_number": "0812987654321",
    "message": "{Halo|Hai|Selamat Pagi} {Bos|Gan}, pesan Anda sudah siap.",
    "priority": "HIGH"
  }'

Kirim SMS — Bulk / Massal

Untuk blast massal, kirim array messages dalam satu request. Setiap pesan tetap diproses individual: spintax dimutasi berbeda per nomor, nomor masuk blacklist otomatis ditolak, dan antrean dikirim bertahap dengan pacing aman per SIM.

curl -X POST https://<BASE_URL_API>/api/v1/sms/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <API_KEY_ANDA>" \
  -d '{
    "priority": "LOW",
    "messages": [
      { "destination_number": "0812987654321", "message": "Promo hari ini" },
      { "destination_number": "085712345678", "message": "Diskon 50% khusus Anda" }
    ]
  }'

Cek Status Pesan

GET /api/v1/sms/status/:id mengembalikan status antrean (PENDING/QUEUED/SENT/FAILED) dan status delivery report (dr_status) dari operator hingga delivered.

curl -H "X-API-Key: <API_KEY_ANDA>" \
  https://<BASE_URL_API>/api/v1/sms/status/<message_id>

Referensi Endpoint Lain

• GET /api/v1/nodes — daftar node (HP Android) beserta telemetri baterai & status online.
• GET /api/v1/nodes/:id — detail satu node dan SIM terpasang.
• GET /api/v1/sims — daftar SIM: operator, kuota harian, sisa pulsa.
• POST /api/v1/sims/:id/check-balance — trigger cek pulsa USSD untuk SIM.
• POST /api/v1/blacklists — tambah nomor ke blacklist (unsubscribe).
• DELETE /api/v1/blacklists/:phone — hapus nomor dari blacklist.

Webhook SMS Masuk

SMS yang diterima SIM node Anda diforward ke webhook URL yang Anda set di pengaturan tenant. Pengiriman webhook di-retry hingga 3x dengan backoff bila endpoint Anda sedang tidak tersedia — pastikan endpoint membalas 2xx dengan cepat.

Spintax & Personalisasi

Template pesan mendukung spintax nested: {Halo|Hai|Selamat Pagi} dipilih acak berbeda untuk setiap penerima. Pada campaign dashboard, kolom tambahan kontak (nama, kota, dst.) otomatis menjadi variabel {nama}, {kota} untuk personalisasi massal — placeholder tanpa nilai akan dibuang sehingga teks {nama} mentah tidak pernah terkirim.

Catatan Penting

• Nomor tujuan dalam blacklist otomatis ditolak (HTTP 403) — gunakan ini untuk menghormati permintaan berhenti berlangganan.
• Pacing per SIM dibatasi dan diberi jitter agar nomor Anda tetap sehat — jangan mengharapkan burst ribuan SMS per menit dari satu SIM.
• SMS gagal kirim otomatis di-retry hingga 3x ke node/SIM lain sebelum status FAILED, lalu biaya layanannya di-refund penuh ke wallet.