Endpoint SMPP

Informasi endpoint

Protokol ini mendefinisikan protokol komunikasi SMPP untuk layanan EngageLab OTP, yang bertujuan untuk mewujudkan pengiriman pesan dan pelaporan status yang efisien dan andal melalui koneksi TCP. Informasi endpoint mencakup alamat IP, nomor port, serta informasi autentikasi yang diperlukan untuk koneksi. Pastikan konfigurasi dilakukan dengan benar sesuai akun dan password yang disediakan oleh channel resmi.

Alamat SMPP

Alamat smpp: otpsmpp.api.engagelab.cc Harap dapatkan informasi berikut dari channel resmi (seperti bisnis atau dukungan teknis):

• Port: { port }
• Akun: { system_id }
• Password: { password }

Membangun koneksi

Paket data klien

Setelah koneksi TCP terbentuk, paket data pertama perlu mengirim perintah BindTransceiver (yaitu 0x00000009) untuk validasi autentikasi. Paket data ini perlu menyertakan field berikut:

• system_id: akun sistem yang dialokasikan kepada pelanggan, digunakan untuk mengidentifikasi identitas.
• password: password akses yang sesuai dengan akun sistem, digunakan untuk autentikasi identitas.

Respons server

Respons sukses

• Server akan mengirim perintah BindTransceiverResp (yaitu 0x80000009) sebagai respons.
• Mengisi field system_id, dengan nilai yang sama dengan field system_id yang diterima.

Respons gagal

• Jika autentikasi gagal, server akan memutuskan koneksi TCP tersebut, dan mencatat alasan kegagalan.

Pengiriman pesan

Logika server

Pengiriman pesan menggunakan perintah SUBMIT_SM (yaitu 0x00000004) untuk mengajukan request pengiriman pesan, dengan logika server sebagai berikut:

1. Server mem-parsing konten request, dan selalu menggunakan channel SMS untuk pengiriman.
2. Pengiriman pesan dalam mode sinkron, hasilnya akan direspons dengan perintah SUBMIT_SM_RESP (yaitu 0x80000004).
3. Status penerimaan akan dilaporkan melalui pesan, untuk detail lihat Laporan penerimaan.
4. Disarankan menggunakan encoding UCS2 untuk mendukung karakter khusus dan internasionalisasi.

Paket data klien

Klien mengirim perintah SUBMIT_SM (yaitu 0x00000004) untuk mengajukan pesan, perlu menyertakan field berikut:

1. service_type
   • Nilai: MSG / CODE / MRKT
   • Nilai default: MSG
2. source_addr
   • Boleh dikosongkan, saat ini belum digunakan dalam OTP.
3. destination_addr
   • Target pesan, harus dalam bentuk nomor ponsel internasional (seperti +6598765432).
4. short_message
   • Konten pesan, dalam format JSON, dengan format sebagai berikut:
     { "id": "xxx", // ID template "language": "default", // bahasa yang digunakan, default adalah default "code": "xx", // kode verifikasi, hanya digunakan ketika service_type adalah code "params": { // pasangan key-value kustom "key1": "val1" // format val adalah string } }

                   
                   {
       "id": "xxx",          // ID template
       "language": "default", // bahasa yang digunakan, default adalah default
       "code": "xx",          // kode verifikasi, hanya digunakan ketika service_type adalah code
       "params": {            // pasangan key-value kustom
         "key1": "val1"       // format val adalah string
       }
     }
     
                 

     Tampilkan blok kode ini di jendela mengambang
5. data_coding
   • Disarankan menggunakan encoding UCS2 untuk memastikan karakter khusus {} ter-parsing dengan normal.
   • Jika mendukung pengiriman langsung {}, maka dapat menggunakan encoding default (yaitu 0x00).
6. status pada header
   • Diatur ke 0x00000000.

Respons server

Server mengirim perintah SUBMIT_SM_RESP (yaitu 0x80000004) sebagai respons hasil pengiriman pesan.

Respons sukses

• Nilai field status pada header: 0x00000000
• Field MESSAGE_ID: ID pesan respons, digunakan untuk mengaitkan laporan penerimaan.

Respons gagal

• Server mengisi field status pada header untuk memberikan alasan kegagalan:

Laporan penerimaan

Server melaporkan laporan penerimaan melalui perintah DELIVER_SM (yaitu 0x00000005). Field spesifiknya sebagai berikut:

1. service_type
   • Nilai tetap: MSG
2. source_addr
   • Dikosongkan.
3. destination_addr
   • Sama dengan destination_addr dalam perintah SUBMIT_SM.
4. data_coding
   • Metode encoding: nilai default 0x00.
5. esm_class
   • Diatur ke 0x00.
6. short_message
   • Membungkus laporan penerimaan dalam format delivery receipt.
7. ReceiptedMessageID pada tlv
   • ID pesan, digunakan untuk identifikasi pengaitan.
8. MessageState pada tlv
   • Status pesan, nilai field 0x0427.

Parsing status

Pada field short_message, arti nilai stat adalah sebagai berikut:

Penjelasan lain

Perintah tidak valid

Untuk perintah tidak valid yang diajukan klien, server akan mengembalikan perintah GENERIC_NACK (yaitu 0x80000000) dan mencatat log terkait. Server hanya mendukung perintah berikut:

1. Perintah EnquireLink (yaitu 0x00000015)
2. Perintah Unbind (yaitu 0x00000006)
3. Perintah SubmitSM (yaitu 0x00000004)
4. Perintah DeliverSMResp (yaitu 0x80000005)
5. Perintah BindTransceiver (yaitu 0x00000009)

Menjaga koneksi tetap aktif

Klien perlu mengirim perintah EnquireLink (yaitu 0x00000015) setiap 30 detik (toleransi ±5 detik), untuk memastikan koneksi tetap aktif.

Arti status pengiriman

Penjelasan istilah

• SMPP: Short Message Peer-to-Peer Protocol, digunakan untuk pertukaran pesan pada gateway SMS.
• SUBMIT_SM: perintah SMPP untuk mengajukan pesan SMS.
• DELIVER_SM: perintah SMPP yang digunakan server untuk melaporkan status penerimaan pesan.

Jika ada pertanyaan, silakan hubungi Dukungan Teknis OTP.