Pengaturan Callback

Pengaturan callback digunakan untuk mengonfigurasi alamat callback pada sistem bisnis Anda agar dapat menerima event "Status Pesan" dan "Respons Pesan" secara real-time yang dikirimkan oleh layanan SMS EngageLab. Dengan memanfaatkan callback, Anda dapat mengotomatisasi pelacakan pesan, menerapkan strategi pengiriman ulang, memicu peringatan sistem, serta meningkatkan efisiensi pemrosesan pesan dan kecerdasan sistem.

• Status Pesan: Perubahan status setiap pesan SMS pada berbagai tahapan seperti pengiriman, diterima, dibaca, dan verifikasi.
• Respons Pesan: Konten dan event dari pesan balasan pengguna (uplink).

Daftar Callback

Halaman daftar callback menampilkan seluruh informasi callback yang telah dikonfigurasi beserta status kesehatannya, sehingga memudahkan manajemen dan pemeliharaan secara terpusat.

• Bilah Pencarian: Mendukung pencarian real-time berdasarkan deskripsi callback untuk menemukan callback yang diinginkan dengan cepat.
• Konfigurasi Callback: Klik tombol ini untuk menambah callback baru sesuai kebutuhan bisnis Anda.

Penjelasan Kolom

Konfigurasi Callback

Klik tombol [Konfigurasi Callback] di pojok kanan atas untuk mengakses halaman ini.

Seperti terlihat pada gambar di atas, silakan isi kolom seperti "Deskripsi Callback", "URL Callback", "Username", "Otorisasi", "Event Callback", dan "Respons Pesan".

• Pilih event callback untuk mengirimkan informasi ke alamat callback yang telah Anda atur saat event tersebut terjadi.
• Klik opsi status pesan dan respons pesan di sebelah kanan untuk melihat contoh terkait.

Proses Konfigurasi

Saat mengonfigurasi alamat callback, sistem SMS EngageLab akan mengirim permintaan HTTP POST ke alamat yang ditentukan. Layanan developer yang sesuai dengan alamat ini harus merespons dengan kode status HTTP 200 dalam waktu 3 detik; jika tidak, sistem akan menganggap alamat tersebut tidak valid.

• Layanan developer hanya perlu merespons dengan kode status HTTP 200, tanpa perlu mengembalikan body respons.

Contoh Permintaan

Misalkan alamat callback yang dikonfigurasi adalah https://example.engagelabSMS.callback.com, maka sistem akan mengirim payload kosong ke alamat tersebut. Berikut representasinya menggunakan perintah curl:

              
              curl -X POST https://example.engagelabSMS.callback.com -d ''

            

Contoh Respons

Layanan developer yang menerima permintaan callback hanya perlu memberikan respons dengan kode status HTTP 200, seperti berikut:

              
              HTTP/1.1 200 OK
Content-Length: 0

            

Konfigurasi Callback

• Konfigurasi Username
  Opsional. Jika Anda mengatur username, maka secret juga harus diisi.

  Untuk memastikan keaslian sumber pesan dari EngageLab, Anda dapat memilih melakukan autentikasi sumber data POST.

  Setelah mengonfigurasi username dan secret, data yang dikirimkan EngageLab akan menyertakan header HTTP: X-CALLBACK-ID.
  Nilai dari X-CALLBACK-ID adalah:
  timestamp={timestamp};nonce={nonce};username={username};signature={signature}

  Contoh:

  X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

                
                X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
  
              

  Tampilkan blok kode ini di jendela mengambang
  • timestamp: Waktu pengiriman pesan callback (format standar).
  • nonce: Angka acak.
  • signature: Informasi tanda tangan, dihitung dengan rumus:
    signature=HMAC-SHA256(secret, timestamp+nonce+username)

  Berikut contoh kode Python untuk menghitung signature:

  import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg='{}{}{}'.format(timestamp, nonce, username).encode(), digestmod=hashlib.sha256 ).hexdigest()

                
                import hashlib, hmac
  
  def verify(username, secret, timestamp, nonce, signature):
      return signature == hmac.new(
          key=secret.encode(),
          msg='{}{}{}'.format(timestamp, nonce, username).encode(),
          digestmod=hashlib.sha256
      ).hexdigest()
  
              

  Tampilkan blok kode ini di jendela mengambang

• Konfigurasi Otorisasi
  Opsional. Jika alamat callback Anda memerlukan autentikasi untuk permintaan dari EngageLab, silakan isi informasi autentikasi di sini. EngageLab akan menyertakan header Authorization pada permintaannya.

Body Permintaan Callback

Ketika event callback terjadi, sistem SMS EngageLab akan mengirim data ke alamat callback.

Contoh Permintaan "Status Pesan"

Status Pesan:

• plan: Direncanakan untuk dikirim.
• sent: Berhasil dikirim.
• sent_failed: Gagal dikirim.
• delivered: Berhasil diterima.
• delivered_failed: Gagal diterima.

              
              {
    "total": 2,
    "rows": [
        {
            "message_id": "1742442805608914944",
            "to": "+8615989574757",
            "server": "SMS",
            "channel": "SMS",
            "itime": 1704265712,
            "status": {
                "message_status": "plan",
                "status_data": {
                    "msg_time": 1704265712,
                    "message_id": "1742442805608914944",
                    "template_key": "auto_create_templateu25az170295320745",
                    "business_id": "100917676394736"
                },
                "error_code": 0
            }
        },
        {
            "message_id": "1742442805608914944",
            "to": "+8615989574757",
            "server": "SMS",
            "channel": "SMS",
            "itime": 1704265712,
            "status": {
                "message_status": "sent_failed",
                "status_data": {
                    "msg_time": 1704265712,
                    "message_id": "1742442805608914944",
                    "template_key": "auto_create_templateu25az170295320745",
                    "business_id": "100917676394736"
                },
                "error_code": 5001,
                "error_detail": {
                    "message": "konfigurasi pengirim tidak valid"
                }
            }
        }
    ]
}

            

Contoh Permintaan "Respons Pesan"

Event:

• uplink_message: Pesan uplink.

              
              {
    "total": 1,
    "rows": [
        {
            "server": "SMS",
            "itime": 1741083306,
            "message_id": "0",
            "business_id": "0",
            "response": {
                "event": "uplink_message",
                "response_data": {
                    "message_sid": "SM1234567890",
                    "account_sid": "AC1234567890",
                    "from": "+1234567890",
                    "to": "+0987654321",
                    "body": "Halo, saatnya berjuang!"
                }
            }
        }
    ]
}