API Callback

Ikhtisar

Data status pesan akan dikirim balik (callback) ke sistem bisnis perusahaan, sehingga analisis statistik dapat dilakukan berdasarkan informasi tersebut.

Alamat Callback

Perusahaan perlu mengatur alamat callback untuk menerima perubahan status pesan. Saat ini belum tersedia antarmuka web. Silakan hubungi tim teknis Engagelab untuk pengaturan alamat callback.

Verifikasi Validitas Alamat Callback

Saat mengonfigurasi alamat callback di backend Push pada Pengaturan Aplikasi, permintaan POST akan dikirim dengan string acak 8 karakter sebagai parameter request body echostr. Anda perlu mengembalikan nilai echostr pada Response Body, dengan format berikut:

Request Body:

              
              {
    "echostr": "12345678"
}

            

Response Body:

              
              12345678

            

Mekanisme Keamanan

Digunakan untuk autentikasi klien, opsional.

Untuk memastikan sumber pesan benar-benar dari Engagelab, Anda dapat memilih melakukan autentikasi sumber data POST. Atau, Anda juga bisa langsung mengurai data POST tanpa autentikasi.

Metode autentikasi:

• Konfigurasikan username callback (username) dan secret callback (secret) di konsol Engagelab untuk alamat callback.

Ambil X-CALLBACK-ID dari header permintaan, contoh:

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

            

Penjelasan:

• timestamp: waktu callback pesan (format standar)
• nonce: angka acak
• signature: informasi tanda tangan

Metode tanda tangan:

              
              signature=HMAC-SHA256(secret, timestamp+nonce+username)

            

Mekanisme Respons

Setelah layanan developer menerima callback dari Engagelab, perlu memberikan respons dalam waktu 3 detik sesuai ketentuan berikut:

• Berhasil diterima: Kode status HTTP harus mengembalikan 200 atau 204, tanpa perlu pesan respons.
• Gagal diterima: Kode status HTTP harus mengembalikan 5XX atau 4XX beserta pesan respons. Format:

              
              {
    "code": 2002,
    "message": "error"
}

            

Penjelasan Field Callback

Body Pesan

Field Array rows

Field Object status

Nilai Status Pesan

Konten Callback

Metode callback: POST
Content-Type: application/json

Contoh

Header Permintaan

              
              POST /developer_define_url HTTP/1.1
Content-Type: application/json

            

Body Permintaan

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861",
            "from": "",
            "to": "",
            "server": "WebPush",
            "channel": "Chrome",
            "custom_args": {},
            "itime": 1640707579,
            "status": {
                "message_status": "delivered",
                "status_data": {
                    "channel_message_id": "wamid.123321abcdefed==",
                    "ntf_msg": 1,
                    "platform": "a",
                    "uid": 100,
                    "app_version": "",
                    "channel": "",
                    "msg_time": 1640707579,
                    "time_zone": "+8",
                    "loss_valid_type": 0,
                    "plan_user_total": 0,
                    "callback_type": 0
                },
                "error_code": 0,
                "error_detail": {
                    "message": ""
                },
                "loss": {
                    "loss_source": "vivo",
                    "loss_step": 1
                }
            }
        }
    ]
}

            

Penjelasan Parameter

Tahap Kehilangan

1. Target rencana → Target valid
2. Target valid → Terkirim
3. Terkirim → Diterima
4. Diterima → Klik