Logo Site EngageLab Mark Colored TransparentDokumen
SMS
Beranda Dokumen
DokumentasiReferensi API
Cari
Masuk
Referensi API/Referensi Event Callback
Referensi APIReferensi Event Callback...

Referensi Event Callback

Terakhir diperbarui：5 hari yang lalu

Konfigurasi dan Verifikasi Alamat Callback

Setelah Anda mengonfigurasi alamat callback, EngageLab SMS akan otomatis mengirim satu request HTTP POST ke alamat tersebut untuk memverifikasi ketersediaan endpoint. Layanan Anda harus mengembalikan HTTP status code 200 dalam waktu 3 detik, jika tidak sistem akan menganggap alamat tersebut tidak tersedia.

Catatan:
Untuk memastikan data callback dapat diterima dengan normal, harap tambahkan 119.8.170.74 dan 114.119.180.30 ke whitelist firewall server Anda.

Contoh Request

Misalkan alamat callback Anda adalah https://example.engagelabSMS.callback.com, sistem akan mengirim request berikut:

curl -X POST https://example.engagelabSMS.callback.com -d '{}'
              
              curl -X POST https://example.engagelabSMS.callback.com -d '{}'
Tampilkan blok kode ini di jendela mengambang

Persyaratan Response

Layanan Anda hanya perlu mengembalikan HTTP status code 200, tanpa perlu mengembalikan konten apa pun. Contoh:

HTTP/1.1 200 OK Content-Length: 0
              
              HTTP/1.1 200 OK
Content-Length: 0
Tampilkan blok kode ini di jendela mengambang

Catatan:
Verifikasi alamat callback hanya memeriksa HTTP status code, tidak mengharuskan pengembalian konten payload tertentu. Pastikan endpoint layanan Anda dapat merespons 200 dengan benar dalam waktu 3 detik.

Mekanisme Keamanan Callback

Untuk menjamin keamanan data callback dan kredibilitas sumbernya, EngageLab SMS mendukung berbagai metode verifikasi keamanan.

Verifikasi Username dan Secret Key (opsional)

  • Konfigurasi opsional. Jika username diatur, maka secret key juga harus diatur.
  • Setelah dikonfigurasi, EngageLab akan menambahkan field X-CALLBACK-ID pada HTTP Header setiap request callback, dengan format sebagai berikut:
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
Tampilkan blok kode ini di jendela mengambang
  • Di mana:
    • timestamp: timestamp pengiriman callback
    • nonce: angka acak
    • username: username yang Anda konfigurasi
    • signature: informasi signature, dihitung dengan cara berikut

Cara Menghitung Signature (Contoh Python)

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg=f'{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=f'{timestamp}{nonce}{username}'.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
Tampilkan blok kode ini di jendela mengambang
  • Sisi server dapat memverifikasi keabsahan request callback dengan cara di atas.

Autentikasi Authorization (opsional)

  • Jika endpoint callback Anda memerlukan autentikasi (seperti Basic Auth, Bearer Token, dll.), Anda dapat mengisi informasi Authorization saat konfigurasi.
  • EngageLab akan otomatis menyertakan field Authorization tersebut saat melakukan request, sehingga layanan Anda dapat memverifikasi identitas request.

Penjelasan Event Callback

Status Pesan

Status pesan digunakan untuk melacak perubahan status setiap pesan sepanjang siklus hidupnya. Digunakan untuk mengetahui secara real-time progres pesan pada setiap tahap seperti pengiriman, penerimaan, dan verifikasi, sehingga memudahkan analisis statistik, penanganan anomali, dan optimasi pengalaman pengguna.

Identifier Event Penjelasan
plan Pesan dijadwalkan untuk dikirim, masuk ke antrian tunggu kirim
target_valid Nomor tujuan valid
target_invalid Nomor tujuan tidak valid
sent Pesan berhasil dikirim
sent_failed Pengiriman pesan gagal
delivered Pesan terkirim ke perangkat pengguna
delivered_failed Pesan telah dikirim, tetapi gagal terkirim ke perangkat pengguna

Struktur Data Callback

Struktur Luar

{ "total": 1, "rows": [ { // Objek ReportLifecycle } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // Objek ReportLifecycle
    }
  ]
}
Tampilkan blok kode ini di jendela mengambang
Nama Field Tipe Penjelasan
total int Jumlah data yang disertakan dalam callback ini
rows array Array data status siklus hidup

Objek ReportLifecycle

Nama Field Tipe Penjelasan
message_id string ID unik pesan
to string Nomor penerima
server string Tipe layanan (misalnya SMS)
channel string Tipe channel
itime int64 Timestamp callback (detik)
custom_args object Parameter kustom (dikembalikan jika ada yang dikirim)
status object Objek detail status

Objek status

Nama Field Tipe Penjelasan
message_status string Status pesan saat ini (lihat tabel di bawah)
status_data object Objek data status
billing object Objek informasi penagihan (dikembalikan jika ada penagihan)
error_code int Kode error, 0 berarti tidak ada error
error_detail object Detail error (dikembalikan saat terjadi error)

Objek status_data

Nama Field Tipe Penjelasan
msg_time int64 Timestamp pembuatan pesan (detik)
message_id string ID pesan
current_send_channel string Nama channel pengirim saat ini
template_key string Key konfigurasi template
business_id string ID bisnis
plan_id string ID plan

Objek billing (dikembalikan jika ada penagihan)

Nama Field Tipe Penjelasan
cost float64 Jumlah biaya
currency string Mata uang, selalu "USD"

Umumnya hanya pesan pada tahap sent yang menyertakan informasi penagihan.

Objek error_detail (dikembalikan saat terjadi error)

Nama Field Tipe Penjelasan
message string Deskripsi pesan error

Contoh: Pesan Berhasil Dikirim

{ "total": 1, "rows": [ { "message_id": "123456789", "to": "+6598765432", "server": "sms", "channel": "sms", "itime": 1701234567, "custom_args": { "order_id": "ORDER123", "user_id": "USER456" }, "status": { "message_status": "sent", "status_data": { "msg_time": 1701234560, "message_id": "123456789", "current_send_channel": "CHANNEL_A", "template_key": "verify_code", "business_id": "1001", "plan_id": "7198765432109876543" }, "billing": { "cost": 0.005, "currency": "USD" }, "error_code": 0 } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "sent",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001",
          "plan_id": "7198765432109876543"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}
Tampilkan blok kode ini di jendela mengambang

Contoh: Pengiriman Pesan Gagal

{ "total": 1, "rows": [ { "message_id": "123456790", "to": "+6598765433", "server": "sms", "channel": "sms", "itime": 1701234568, "status": { "message_status": "sent_fail", "status_data": { "msg_time": 1701234561, "message_id": "123456790", "current_send_channel": "CHANNEL_B", "template_key": "verify_code", "business_id": "1001", "plan_id": "7198765432109876543" }, "error_code": 4001, "error_detail": { "message": "Invalid phone number" } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+6598765433",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001",
          "plan_id": "7198765432109876543"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number"
        }
      }
    }
  ]
}
Tampilkan blok kode ini di jendela mengambang

Notifikasi Pesan

Notifikasi pesan mengacu pada event bisnis tingkat sistem atau peringatan (alert). Digunakan untuk mengingatkan pihak bisnis agar memperhatikan informasi penting seperti status operasi layanan, saldo, dan peninjauan template, sehingga memudahkan penanganan tepat waktu dan peringatan dini risiko.

Identifier Event Penjelasan
template_audit_result Notifikasi hasil peninjauan template

Respons Pesan

Respons pesan terutama mengacu pada event respons callback saat berinteraksi dengan pengguna atau sistem eksternal.

Identifier Event Penjelasan
uplink_message Konten pesan uplink yang dibalas pengguna melalui SMS dan cara lainnya

Contoh

{ "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": "Hello, it's time to struggle!" } } } ] }
              
              {
    "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": "Hello, it's time to struggle!"
                }
            }
        }
    ]
}
Tampilkan blok kode ini di jendela mengambang

Event Sistem

Event sistem mencakup tindakan operasional terkait akun, template, panggilan API, dan lainnya. Memudahkan pemantauan, audit, dan pemrosesan otomatis atas operasi penting seperti login akun, perubahan secret key, dan panggilan API.

Identifier Event Penjelasan
account_login Notifikasi operasi terkait login akun
key_manage Notifikasi operasi terkait perubahan dan pengelolaan secret key
template_manage Notifikasi operasi penambahan, perubahan, penghapusan template
api_call Notifikasi operasi terkait panggilan endpoint API

Struktur Data Callback

Struktur Luar

{ "total": 1, "rows": [ { // Objek event sistem } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // Objek event sistem
    }
  ]
}
Tampilkan blok kode ini di jendela mengambang
Field Tipe Penjelasan
total int64 Total event yang disertakan dalam callback ini
rows array Array objek event sistem

Objek Event Sistem

Field Tipe Penjelasan
server string Selalu "SMS"
itime int64 Timestamp terjadinya event (detik)
system_event object Konten event sistem

Objek system_event

Field Tipe Penjelasan
event string Tipe event
data object Data event

Objek data

Field Tipe Penjelasan
business_id string ID bisnis
org_id string ID organisasi
operator object Informasi operator

Objek operator

Field Tipe Penjelasan
email string Email operator (jika ada)
api_key string API Key (jika ada)
ip_address string IP operasi

Struktur Request

{ "total": 1, "rows": [ { "server": "SMS", "itime": 1694012345, "system_event": { "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "api_key": "api-xxxx", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "server": "SMS",
      "itime": 1694012345,
      "system_event": {
        "event": "account_login",
        "data": {
          "business_id": "123",
          "org_id": "org-abc",
          "operator": {
            "email": "foo@example.com",
            "api_key": "api-xxxx",
            "ip_address": "1.2.3.4"
          },
          "account_login": {
            "action": "login_success"
          }
        }
      }
    }
  ]
}
Tampilkan blok kode ini di jendela mengambang

Event Login Akun

Field Tipe Penjelasan
action string Login berhasil/login gagal/logout
fail_reason string Alasan kegagalan login, hanya dikembalikan saat login_failed

Contoh

{ "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } }
              
              {
  "event": "account_login",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "account_login": {
      "action": "login_success"
    }
  }
}
Tampilkan blok kode ini di jendela mengambang

Event Pengelolaan Template

Field Tipe Penjelasan
action string Buat template/perbarui template/hapus template
template_id string ID template
template_name string Nama template

Contoh

{ "event": "template_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "template_manage": { "action": "update template", "template_id": "tmpl-456", "template_name": "Verification Code" } } }
              
              {
  "event": "template_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "template_manage": {
      "action": "update template",
      "template_id": "tmpl-456",
      "template_name": "Verification Code"
    }
  }
}
Tampilkan blok kode ini di jendela mengambang

Event Pengelolaan Secret Key

Field Tipe Penjelasan
action string Buat secret key/perbarui secret key/hapus secret key/lihat secret key
api_key string API Key
description string Deskripsi (opsional)

Contoh

{ "event": "key_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "key_manage": { "action": "create", "api_key": "apikey-789", "description": "Buat secret key" } } }
              
              {
  "event": "key_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "key_manage": {
      "action": "create",
      "api_key": "apikey-789",
      "description": "Buat secret key"
    }
  }
}
Tampilkan blok kode ini di jendela mengambang

Event Panggilan API

Field Tipe Penjelasan
api_path string Path endpoint
method string Metode HTTP

Contoh

{ "event": "api_call", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "api_key": "apikey-789", "ip_address": "1.2.3.4" }, "api_call": { "api_path": "/api/v1/messages/send", "method": "POST" } } }
              
              {
  "event": "api_call",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "api_key": "apikey-789",
      "ip_address": "1.2.3.4"
    },
    "api_call": {
      "api_path": "/api/v1/messages/send",
      "method": "POST"
    }
  }
}
Tampilkan blok kode ini di jendela mengambang
Icon Solid Transparent White Qiyu
Hubungi Sales