API SMPP

Informasi API

Protokol ini mendefinisikan komunikasi SMPP untuk layanan OTP EngageLab dan dirancang untuk memungkinkan pengiriman pesan serta pelaporan status yang efisien dan andal melalui koneksi TCP. Informasi API mencakup alamat IP, nomor port, dan detail autentikasi yang diperlukan untuk koneksi. Harap pastikan akun dan kata sandi yang diberikan melalui saluran resmi telah dikonfigurasi dengan benar.

Alamat SMPP

Alamat SMPP: otpsmpp.api.engagelab.cc

Silakan dapatkan informasi berikut melalui saluran resmi, seperti dukungan bisnis atau teknis:

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

Membangun Koneksi

Paket Klien

Setelah koneksi TCP berhasil dibuat, paket pertama harus mengirim perintah BindTransceiver (0x00000009) untuk autentikasi. Paket ini harus menyertakan field berikut:

• system_id: Akun sistem yang ditetapkan untuk klien, digunakan untuk mengidentifikasi klien.
• password: Kata sandi akses yang sesuai dengan akun sistem, digunakan untuk autentikasi.

Respons Server

Respons Berhasil

• Server mengembalikan perintah BindTransceiverResp (0x80000009).
• Field system_id diisi dengan nilai yang sama seperti field system_id yang diterima.

Respons Gagal

• Jika autentikasi gagal, server memutus koneksi TCP dan mencatat alasan kegagalan.

Pengiriman Pesan

Logika Server

Pengiriman pesan menggunakan perintah SUBMIT_SM (0x00000004) untuk mengirim permintaan pengiriman pesan. Logika server adalah sebagai berikut:

1. Server mem-parsing konten permintaan dan selalu menggunakan saluran SMS untuk pengiriman.
2. Pengiriman pesan bersifat sinkron, dan hasilnya dikembalikan melalui perintah SUBMIT_SM_RESP (0x80000004).
3. Status pengiriman dilaporkan melalui delivery report. Untuk detailnya, lihat Laporan Pengiriman.
4. Disarankan menggunakan encoding UCS2 untuk mendukung karakter khusus dan internasionalisasi.

Paket Klien

Klien mengirim perintah SUBMIT_SM (0x00000004) untuk mengirim pesan. Paket harus menyertakan field berikut:

1. service_type

   • Nilai: MSG / CODE / MRKT
   • Nilai default: MSG

2. source_addr

   • Dapat dikosongkan dan saat ini tidak digunakan dalam OTP.

3. destination_addr

   • Tujuan pesan, yang harus menggunakan format nomor ponsel internasional (misalnya, +6598765432).

4. short_message

   • Konten pesan menggunakan format JSON, seperti ditunjukkan di bawah ini:
     { "id": "xxx", // ID template "language": "default", // Bahasa yang digunakan; default adalah default "code": "xx", // Kode verifikasi; hanya digunakan saat service_type adalah CODE "params": { // Pasangan key-value kustom "key1": "val1" // val harus dalam format string } }

                   
                   {
       "id": "xxx",           // ID template
       "language": "default", // Bahasa yang digunakan; default adalah default
       "code": "xx",          // Kode verifikasi; hanya digunakan saat service_type adalah CODE
       "params": {            // Pasangan key-value kustom
         "key1": "val1"       // val harus dalam format string
       }
     }
     
                 

     Tampilkan blok kode ini di jendela mengambang

5. data_coding

   • Disarankan menggunakan encoding UCS2 untuk memastikan karakter khusus seperti {} dapat diuraikan dengan benar.
   • Jika transmisi langsung {} didukung, encoding default dapat digunakan (0x00).

6. status in the header

   • Atur ke 0x00000000.

Respons Server

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

Respons Berhasil

• Value of the status field in the header: 0x00000000
• MESSAGE_ID field: ID pesan respons, digunakan untuk mengaitkan delivery report.

Respons Gagal

• Server mengisi status field in the header untuk menunjukkan alasan kegagalan:

Laporan Pengiriman

Server melaporkan status pengiriman melalui perintah DELIVER_SM (0x00000005). Field yang relevan adalah sebagai berikut:

1. service_type

   • Nilai tetap: MSG

2. source_addr

   • Biarkan kosong.

3. destination_addr

   • Sama seperti destination_addr pada perintah SUBMIT_SM.

4. data_coding

   • Metode encoding: nilai default 0x00.

5. esm_class

   • Atur ke 0x00.

6. short_message

   • Delivery report dikemas menggunakan format delivery receipt.

7. ReceiptedMessageID in TLV

   • ID pesan, digunakan untuk korelasi dan identifikasi.

8. MessageState in TLV

   • Status pesan, nilai field 0x0427.

Parsing Status

Dalam field short_message, arti nilai stat adalah sebagai berikut:

Catatan Lainnya

Perintah Tidak Valid

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

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

Keepalive

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

Arti Status Pengiriman

Terminologi

• SMPP: Short Message Peer-to-Peer Protocol, digunakan untuk pertukaran pesan dengan gateway SMS.
• SUBMIT_SM: Perintah SMPP untuk mengirim pesan SMS.
• DELIVER_SM: Perintah SMPP yang digunakan oleh server untuk melaporkan status pengiriman pesan.

Jika Anda memiliki pertanyaan, silakan hubungi Dukungan Teknis OTP.