SMS API vs SMPP: Koneksi Mana yang Sebaiknya Anda Pakai?

Panduan ini ditujukan bagi engineer dan technical lead yang sedang menentukan cara terhubung ke provider SMS: melalui SMS API HTTP/REST, melalui SMPP, atau keduanya. Panduan ini menjelaskan perbedaan nyata keduanya di level jaringan dan operasional, sehingga Anda dapat memilih antarmuka yang tepat untuk setiap jenis trafik dan merencanakan migrasi jika pilihan pertama Anda tidak lagi memadai.

Untuk gambaran pola integrasi yang lebih luas, termasuk webhook dan idempotensi, lihat panduan integrasi API pesan kami.

Apa perbedaan SMS API dan SMPP?

REST SMS API mengirim setiap pesan sebagai request HTTPS terpisah dan mengembalikan ID pesan. SMPP (Short Message Peer-to-Peer) menjaga satu sesi terautentikasi yang berumur panjang dan mempertukarkan pesan biner, yang disebut PDU, ke dua arah melalui sesi itu. REST dioptimalkan untuk kesederhanaan; SMPP dioptimalkan untuk volume SMS yang berkelanjutan.

Bagaimana cara kerja REST SMS API?

Anda membuat POST HTTPS dengan token dan body JSON, lalu provider membalas dengan sebuah ID. Setiap request bersifat independen, sehingga Anda dapat mengirim dari server, function, atau container mana pun tanpa mengelola koneksi.

Contoh pengiriman dengan API kami:

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "OmniDemo",
    "destinationNumber": "971500000000",
    "message": "Your OmniDemo code is 482913",
    "messageType": "TEXT"
  }'

Responsnya 200 OK dengan ID pesan sebagai teks biasa. Status akhir datang kemudian ke webhook Anda sebagai SUBMITTED, SENT, DELIVERED, FAILED, atau REJECTED. Nama field dan opsi ada di referensi SMS API.

Kelebihan REST:

• Tooling yang familiar: bahasa pemrograman apa pun, klien HTTP apa pun, kode status standar sebagaimana didefinisikan di RFC 9110.
• Keamanan mudah: TLS di mana-mana dan token di header Authorization.
• Pengiriman massal tanpa koneksi: unggah file penerima dalam satu request, tanpa membuka sesi.
• Satu API untuk banyak kanal: pola yang sama mengirim template WhatsApp atau kartu RCS.

Keterbatasan REST: setiap pesan, atau setiap batch, membutuhkan satu round trip HTTP, dan Anda akan menemui batas request per detik lebih dulu sebelum batas operator. Untuk sebagian besar trafik aplikasi, hal ini tidak menjadi masalah.

Bagaimana cara kerja SMPP?

SMPP adalah protokol biner yang didefinisikan oleh spesifikasi SMPP v3.4, diterbitkan oleh SMPP Developers Forum (kemudian SMS Forum) dan masih menjadi versi yang paling banyak digunakan. Sistem Anda, yang disebut ESME (External Short Message Entity), terhubung ke SMSC (Short Message Service Center) milik provider dan membuka sesi yang disebut bind.

Tipe bind

• Transmitter (TX), memakai bind_transmitter: hanya mengirim pesan.
• Receiver (RX), memakai bind_receiver: hanya menerima laporan pengiriman dan pesan masuk.
• Transceiver (TRX), memakai bind_transceiver: keduanya dalam satu sesi. Ini pilihan yang paling umum.

Siklus hidup sesi

1. Buka koneksi TLS ke host dan port yang diberikan provider Anda.
2. Kirim bind_transceiver dengan system_id dan password Anda, lalu tunggu respons dengan command_status 0.
3. Kirim pesan dengan submit_sm. Setiap submit_sm_resp mengembalikan message_id.
4. Terima laporan pengiriman sebagai deliver_sm dan jawab masing-masing dengan deliver_sm_resp.
5. Kirim enquire_link secara berkala saat sesi idle agar kedua sisi tahu sesi masih hidup.
6. Tutup dengan unbind dan tunggu unbind_resp.

Setiap PDU membawa sequence number, dan respons membawa nomor yang sama, sehingga Anda dapat mencocokkan submit_sm_resp dengan pesan yang Anda kirim. Dokumentasi SMPP kami membahas setiap langkah beserta pengaturan kami.

Apa itu windowing SMPP dan mengapa penting?

Windowing berarti mengirim beberapa PDU submit_sm sebelum responsnya kembali. Jumlah PDU belum terkonfirmasi yang boleh in flight disebut window. Inilah alasan utama SMPP dapat menjaga throughput lebih tinggi daripada HTTP yang mengirim satu request per satu waktu.

Dengan window 1, klien Anda mengirim satu pesan, menunggu satu round trip penuh untuk responsnya, baru mengirim pesan berikutnya. Throughput dibatasi oleh latensi jaringan, bukan oleh kecepatan yang Anda sepakati. Dengan window yang lebih besar, koneksi tetap sibuk selagi respons berdatangan.

Pedoman praktis:

• Gunakan ukuran window yang disepakati dengan provider Anda, dan jangan melampauinya; PDU berlebih dapat ditolak.
• Patuhi kecepatan yang disepakati per bind. Jika Anda menerima ESME_RTHROTTLED, perlambat dan coba lagi dengan backoff.
• Lacak sequence number yang masih outstanding agar koneksi yang terputus tidak membuat Anda kehilangan jejak pesan mana yang sudah diterima.
• Skalakan dengan menambah bind, hingga jumlah yang disepakati untuk akun Anda, bukan dengan window yang terus membesar.

Batas default untuk REST API dan bind SMPP kami tercantum di error dan batas; batas akun Anda dikonfirmasi saat akses disediakan.

Apa perbedaan laporan pengiriman?

Di REST, provider mengirim event JSON ke webhook Anda. Di SMPP, laporan datang sebagai PDU deliver_sm di sesi, dengan receipt bit diatur di esm_class. Keduanya asinkron; baik 200 OK maupun submit_sm_resp tidak berarti handset sudah menerima pesan.

Spesifikasi SMPP v3.4 memberikan format teks receipt sebagai contoh dan menyerahkan format persisnya kepada vendor SMSC, tetapi sebagian besar provider mengikutinya:

id:2603121407537573731 sub:001 dlvrd:001 submit date:2610100914 done date:2610100915 stat:DELIVRD err:000 text:Your OmniDemo code

Jika sistem Anda memakai kedua antarmuka, petakan status SMPP ke satu model status. Contoh pemetaan:

Dua perbedaan praktis yang lebih penting daripada format:

• Konfirmasi. Klien SMPP harus menjawab setiap deliver_sm. Laporan yang tidak dikonfirmasi dikirim ulang dan dapat memperlambat bind. Handler webhook harus menjawab 2xx dengan cepat karena alasan yang sama.
• Pemulihan. Jika klien SMPP Anda terputus, laporan menunggu bind berikutnya atau dapat kedaluwarsa di antrean provider. Di REST, provider mungkin menyediakan push ulang laporan untuk rentang tanggal tertentu. Tanyakan cara kerja masing-masing.

Baca lebih lanjut tentang arti setiap status di penjelasan status pengiriman pesan.

Bagaimana encoding ditangani?

Kedua antarmuka harus memilih antara GSM-7 dan Unicode, dan keduanya memecah pesan panjang menjadi segmen. Bedanya ada pada siapa yang mengerjakannya.

• REST: Anda mengatur field seperti messageType ke TEXT atau UNICODE, dan platform yang memecah pesan panjang. API kami juga memiliki POST /sms/identify untuk menghitung karakter dan segmen terlebih dahulu.
• SMPP: Anda mengatur data_coding (0 untuk alfabet default GSM-7, 8 untuk UCS-2) dan meng-encode byte sendiri. Untuk pesan panjang, Anda menambahkan User Data Header ke setiap bagian dan mengatur esm_class ke 0x40, atau mengirim seluruh teks di field message_payload jika provider Anda mengaktifkannya.

Menurut 3GPP TS 23.040, satu SMS membawa 140 oktet: 160 karakter GSM-7 atau 70 karakter UCS-2, turun menjadi 153 atau 67 per bagian saat header ditambahkan. Satu huruf Arab atau satu emoji membuat seluruh pesan menjadi Unicode. Bug encoding adalah kesalahan integrasi SMPP yang paling sering terjadi, jadi uji dengan huruf Arab, emoji, dan teks panjang. Lihat panduan batas karakter kami.

Bagaimana perbandingan model keamanannya?

REST mengandalkan TLS dan bearer token di setiap request. SMPP v3.4 tidak memiliki enkripsi sendiri dan mengirim kredensial dalam bind, sehingga bergantung pada transport dan kontrol jaringan di sekitarnya.

Untuk SMPP:

• Gunakan TLS (TLS 1.3 didefinisikan di RFC 8446) atau jalur privat; jangan pernah memakai SMPP polos melalui internet publik.
• Daftarkan alamat IP sumber agar hanya server Anda yang dapat melakukan bind.
• Simpan system_id dan password sebagai secret, terpisah untuk setiap environment, dan ganti jika terekspos.
• Pantau kegagalan bind, yang bisa menandakan salah konfigurasi atau penyalahgunaan kredensial.

Untuk REST:

• Simpan token hanya di server, jangan pernah di aplikasi mobile atau kode browser.
• Hindari antarmuka HTTP lama yang mengirim username dan password di URL, karena akhirnya tercatat di log.
• Lindungi webhook dengan HTTPS, path yang sulit ditebak, dan validasi body yang ketat.

Berapa beban operasional masing-masing opsi?

REST nyaris tidak menambah beban operasional: request berhasil atau mengembalikan error yang dapat Anda coba ulang. SMPP menambahkan komponen yang berjalan terus-menerus yang harus Anda pantau dan rawat.

Klien SMPP membutuhkan:

1. manajemen koneksi, dengan reconnect memakai backoff dan jitter, bukan loop yang rapat;
2. keep-alive dan deteksi koneksi half-open yang diam;
3. kontrol window dan kecepatan per bind;
4. pelacakan sequence dan rekonsiliasi setelah koneksi terputus;
5. konfirmasi dan penyimpanan laporan pengiriman;
6. logika encoding dan penggabungan pesan (concatenation);
7. pemantauan status bind, throughput, error throttling, dan lag laporan pengiriman.

Library open source yang matang menangani protokolnya, tetapi tim Anda tetap bertanggung jawab atas perilaku di sekitarnya, termasuk saat jendela pemeliharaan provider pada pukul 03.00 dini hari.

Kapan sebaiknya memakai masing-masing?

Gunakan REST kecuali Anda punya alasan yang jelas untuk menambahkan SMPP.

Pilih REST SMS API jika

• Anda mengirim OTP, alert, notifikasi, atau kampanye dari aplikasi;
• Anda membutuhkan WhatsApp, RCS, atau kanal lain selain SMS;
• platform Anda berjalan di serverless function atau container berumur pendek;
• tim Anda tidak punya pengalaman SMPP dan tidak perlu membangunnya.

Pilih SMPP jika

• Anda mengirim SMS dengan volume tinggi dan berkelanjutan serta sudah mencapai batas REST;
• Anda sudah menjalankan gateway atau platform pesan berbasis SMPP;
• Anda agregator, carrier, atau reseller yang menyalurkan trafik SMS pelanggan Anda sendiri;
• Anda membutuhkan protokol yang sama di beberapa provider upstream.

Seperti apa setup hibrida?

Banyak bisnis memakai keduanya dalam satu akun: REST untuk trafik multikanal dan aplikasi, SMPP untuk SMS blast. Jebakannya adalah berakhir dengan dua model pengiriman.

• Arahkan berdasarkan use case, bukan secara acak: misalnya OTP dan WhatsApp lewat REST, SMS blast untuk tagihan bulanan lewat SMPP.
• Normalkan status dari webhook dan deliver_sm ke satu tabel dengan kunci ID pesan.
• Gunakan satu kebijakan Sender ID di keduanya, karena registrasi berlaku apa pun antarmuka yang Anda pakai.
• Buat laporan terpadu, sehingga kampanye yang terbagi di kedua antarmuka menampilkan satu hasil.

Bagaimana cara migrasi dari SMS API ke SMPP?

Berpindahlah secara bertahap dengan kedua antarmuka tetap berjalan, dan ukur sebelum Anda memindahkan volume.

1. Pastikan kebutuhannya: dokumentasikan volume atau throughput yang tidak dapat dipenuhi REST.
2. Minta provisioning: bagikan negara tujuan, Sender ID, perkiraan throughput puncak, dan alamat IP sumber.
3. Pilih library klien yang matang di stack Anda dan bungkus dengan antarmuka pengiriman Anda sendiri.
4. Bangun penanganan laporan pengiriman lebih dulu, dipetakan ke model status yang sama dengan webhook Anda.
5. Uji encoding: GSM-7, huruf Arab, emoji, dan pesan multi-bagian di handset sungguhan.
6. Uji kegagalan: putuskan koneksi di tengah pengiriman, picu throttling, dan periksa rekonsiliasi.
7. Jalankan paralel: pindahkan sebagian kecil satu jenis trafik ke SMPP dan bandingkan pengiriman serta laporan pengirimannya.
8. Pindahkan volume bertahap, dengan REST tetap sebagai jalur fallback (kanal cadangan).

Berikut contoh konfigurasi bind sebagai ilustrasi. Host, port, dan batas hanyalah placeholder; nilai sebenarnya diberikan bersama kredensial yang disediakan untuk Anda.

host:                 <provided with your bind>
port:                 <TLS port provided with your bind>
bind type:            transceiver
system_id:            <your system_id>
password:             <your password>
system_type:          (empty unless told otherwise)
interface_version:    0x34
source_addr_ton/npi:  5 / 0   (alphanumeric sender ID)
dest_addr_ton/npi:    1 / 1   (international number)
registered_delivery:  1       (request delivery receipts)
data_coding:          0 (GSM-7) or 8 (UCS-2)
enquire_link:         every 30 seconds while idle
window:               as agreed for your account

Contoh kasus: retailer regional menambahkan SMPP untuk tagihan

"Souq Rafiq" (fiktif), retailer online di Uni Emirat Arab (UEA), Mesir, dan Yordania, mengirim OTP dan update pesanan lewat REST API, serta template WhatsApp melalui API yang sama. Tagihan akun bulanan, yang dikirim lewat SMS ke seluruh basis pelanggannya, tumbuh hingga proses REST-nya memakan waktu lebih lama dari yang diinginkan bisnis.

• Keputusan: OTP, update pesanan, dan WhatsApp tetap di REST. Pengiriman SMS tagihan bulanan dipindah ke bind SMPP transceiver.
• Provisioning: tim mendaftarkan dua IP sumber, mengonfirmasi Sender ID per negara, serta menyepakati throughput dan jumlah bind.
• Pembangunan: layanan SMPP kecil memakai library open source, menulis laporan pengiriman ke tabel status yang sama dengan webhook, dan menyediakan antarmuka pengiriman internal yang sama dengan jalur REST.
• Pengujian: tagihan berbahasa Arab dikonfirmasi sebagai UCS-2 dengan concatenation yang benar di beberapa handset.
• Peluncuran: satu negara pindah lebih dulu. Setelah membandingkan pengiriman dan waktu laporan dengan baseline REST, negara lain menyusul, dengan REST tetap sebagai fallback.

Kesalahan umum

• Memilih SMPP demi gengsi. Jika REST sudah memenuhi volume Anda, SMPP hanya menambah pekerjaan.
• Menjalankan window 1, lalu menyalahkan provider karena throughput rendah.
• Tidak mengonfirmasi deliver_sm, yang menyebabkan laporan dikirim ulang dan throttling.
• Reconnect dalam loop yang rapat setelah terputus, yang bisa terlihat seperti serangan.
• Mencampur short_message dan message_payload dalam satu PDU, yang menyebabkan error panjang pesan.
• SMPP polos melalui internet, yang membuka kredensial dan isi pesan.
• Dua model status di setup hibrida, sehingga laporan saling bertentangan.
• Batasan: panduan ini menjelaskan praktik umum. Ukuran window, kecepatan, port TLS, dan detail laporan pengiriman berbeda antar provider dan akun; konfirmasikan saat provisioning.

Bagaimana OmniChannels.ai membantu

OmniChannels.ai menyediakan keduanya. REST API di https://api.broadnet.me memakai Bearer token dan mencakup SMS bersama WhatsApp, RCS, Messenger, Instagram, Telegram, Email, dan Push, dengan status pengiriman yang dikirim ke webhook Anda dalam satu format. Untuk SMS volume tinggi, bind SMPP 3.4 melalui TLS disediakan per akun, dengan IP sumber yang masuk allow list, dan memakai rute SMS yang sama melalui jalur langsung ke operator BroadNet. Reseller dan mitra wholesale dapat memperoleh bind khusus. Mulailah dengan dokumentasi SMPP atau quickstart, atau lihat ringkasan developer.