Pengaturan Panggilan Balik

Ikhtisar

Atur alamat callback untuk menerima data callback dari layanan OTP EngageLab, baik untuk "Status Pesan" maupun "Pesan Notifikasi". Data callback ini dapat digunakan untuk analisis statistik, strategi pengiriman ulang, atau pemicu peringatan sistem.

• Status Pesan: Setelah pengguna mengirim OTP, status ini meliputi terkirim, diterima, dibaca, terverifikasi, dan lainnya.
• Pesan Notifikasi: Biasanya berupa peristiwa sistem, seperti tingkat verifikasi rendah, saldo tidak cukup, dan lain-lain.

Konfigurasi Callback

Pada menu "Manajemen Konfigurasi" → "Pengaturan Callback", klik "Konfigurasi Callback" untuk mengatur callback layanan OTP EngageLab.

Seperti pada gambar di atas, isi secara berurutan "Deskripsi Callback", "Alamat Callback", "Username", "Otorisasi", "Peristiwa Callback", dan lainnya.

• Centang peristiwa callback untuk mengirimkan informasi ke alamat yang Anda tentukan saat peristiwa tersebut terjadi.
• Klik ikon di kanan status pesan dan respons pesan untuk melihat contoh data.

Konfigurasi Alamat Callback

Saat mengonfigurasi alamat callback, sistem OTP EngageLab akan mengirim HTTP POST ke alamat tersebut. Layanan developer harus merespons dengan status HTTP 200 dalam waktu 3 detik, jika tidak, sistem menganggap alamat tidak valid.

• Layanan developer hanya perlu merespons dengan kode status HTTP 200, tanpa perlu mengembalikan pesan apa pun.

Contoh Permintaan

Misal alamat callback yang dikonfigurasi adalah https://example.engagelabotp.callback.com. EngageLab akan mengirim permintaan kosong seperti berikut (menggunakan curl):

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

            

Contoh Respons

Layanan developer hanya perlu merespons dengan status HTTP 200:

              
              HTTP/1.1 200 OK
Content-Length: 0

            

Konfigurasi Mekanisme Keamanan Alamat Callback

• Pengaturan Username

Opsional. Jika username diisi, secret juga harus diisi.

Untuk memastikan pesan benar-benar dari EngageLab, Anda dapat memilih melakukan otentikasi sumber data POST.

Setelah mengatur username dan secret, data dari EngageLab akan menyertakan HTTP Header: X-CALLBACK-ID. Nilai X-CALLBACK-ID seperti: timestamp={timestamp};nonce={nonce};username={username};signature={signature}

Contoh:

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

            

• timestamp: waktu pengiriman pesan callback (format standar)
• nonce: angka acak
• signature: tanda tangan HMAC-SHA256(secret, timestamp+nonce+username)

Contoh kode Python untuk menghitung signature:

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

            

• Pengaturan Otorisasi

Opsional. Jika alamat callback Anda memerlukan autentikasi, masukkan info otorisasi di sini. EngageLab akan menyertakan header Authorization pada permintaan.

Body Permintaan Callback

Saat peristiwa callback terjadi, sistem OTP EngageLab akan mengirim data ke alamat callback.

Contoh Permintaan "Status Pesan"

Status pesan meliputi:

• plan: Direncanakan untuk dikirim
• sent: Terkirim
• sent_failed: Gagal dikirim
• delivered: Diterima
• delivered_failed: Gagal diterima
• verified: Terverifikasi
• verified_failed: Verifikasi gagal
• verified_timeout: Waktu verifikasi habis

              
              {
    "total": 2,
    "rows": [{
        "message_id": "1742442805608914944",
        "to": "+8615989574757",
        "server": "otp",
        "channel": "otp",
        "itime": 1704265712,
        "status": {
            "message_status": "plan",
            "status_data": {
                "msg_time": 170426571,
                "message_id": "1742442805608914944",
                "template_key": "auto_create_templateu25az170295320745",
                "business_id": "100917676394736"
            },
            "error_code": 0
        }
    }, {
        "message_id": "1742442805608914944",
        "to": "+8615989574757",
        "server": "otp",
        "channel": "otp",
        "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 "Pesan Notifikasi"

Peristiwa:

• insufficient_balance: Saldo di bawah ambang batas peringatan

              
              {
    "total": 1,
    "rows": [{
        "server": "otp",
        "itime": 1712458844,
        "notification": {
            "event": "insufficient_balance",
            "notification_data": {
                "business_id": "1744569418236633088",
                "remain_balance": -0.005,
                "balance_threshold": 2
            }
        }
    }]
}