API Panggilan Balik

Ikhtisar

Data "status pesan" dan "respons pesan" akan dikirim balik ke sistem bisnis perusahaan, dan informasi ini dapat digunakan untuk keperluan statistik maupun membalas pengguna.

Alamat Callback

Perusahaan harus mengatur alamat callback untuk menerima status pesan dan respons pesan. Untuk detail lebih lanjut, silakan lihat pengaturan callback.

Format Callback

Metode permintaan menggunakan POST, body permintaan berupa JSON, dan tipe data "Content-Type: application/json".
Beberapa data dapat dikirim sekaligus.

Mekanisme Keamanan

Segera tersedia. Saat ini, callback tidak memuat informasi autentikasi, jadi jangan mengaktifkan verifikasi izin pada API penerima callback dari developer.

Mekanisme Respons

Setelah menerima callback dari EngageLab, layanan developer harus memberikan respons dalam waktu 3 detik sebagai berikut:
berhasil diterima: kode status HTTP harus mengembalikan 200 tanpa perlu pesan respons.

Mekanisme Retry

Segera tersedia.

Parameter Permintaan

Parameter yang dikirim EngageLab ke alamat callback sistem bisnis adalah sebagai berikut:

Field	Tipe	Opsi	Deskripsi
total	int	wajib	jumlah data callback
rows	JSON Array	wajib	detail callback

Parameter dalam rows:

Field	Tipe	Opsi	Deskripsi
message_id	string	opsional	status pesan dan respons.
from	string	opsional	Pengirim, status pesan, dikembalikan saat pesan upstream dikirim.
to	string	opsional	Penerima, status pesan, dan pesan upstream.
server	string	wajib	Layanan produk asal callback. Nilai tetap: whatsapp.
channel	string	opsional	Channel asal status/respons. Nilai tetap: whatsapp
itime	int	wajib	timestamp data callback. Untuk timestamp permintaan, pengiriman, pengantaran, dan pembacaan, gunakan field message_status.
custom_args	JSON Object	opsional	Field opsional yang dikustomisasi saat pengiriman pesan, akan dikembalikan pada callback status pesan.
status	JSON Object	opsional	Field status pesan
response	JSON Object	opsional	Field respons pesan

Status Pesan - status

Parameter callback

Field	Tipe	Opsi	Deskripsi
message_status	string	wajib	status pesan.
status_data	JSON Object	opsional	data detail status ini
error_code	int	opsional	kode error. Jika gagal, kode error dikembalikan.
error_detail	JSON Object	opsional	detail error. Pesan error jika gagal.
loss	JSON Object	opsional	tahap kehilangan dan sumber kehilangan

message_status - respons

Nilai	Deskripsi	Definisi
plan	pengiriman terjadwal	nomor ada dalam "nomor penerima" untuk mencatat status satu target pengiriman terjadwal.
target_valid	target valid	Lolos verifikasi validitas 1. Nomor dinyatakan legal oleh EngageLab. 2. Nomor dinyatakan legal oleh layanan Meta WhatsApp.
sent	berhasil dikirim	Pesan error yang dikembalikan setelah EngageLab mengirim nomor ke Meta WhatsApp.
delivered	berhasil diterima	Meta WhatsApp mengonfirmasi pesan sudah diterima oleh pengguna.
read	dibaca	Meta WhatsApp mengonfirmasi pesan sudah dibaca pengguna.
target_invalid	target tidak valid.	1. Nomor tidak valid menurut EngageLab. 2. Nomor tidak valid menurut Meta WhatsApp.
sent_failed	gagal dikirim	Pesan error setelah nomor dikirim ke Meta WhatsApp.
delivered_failed	gagal diterima	Nomor sudah dikirim ke Meta WhatsApp, tapi callback dari Meta gagal.
delivered_timeout	tidak diterima setelah timeout	Nomor sudah dikirim ke Meta WhatsApp, tapi tidak ada callback sukses/gagal dari Meta dalam 5 menit, dihitung timeout.

status_data

Field	Tipe	Opsi	Deskripsi
msg_time	int	wajib	waktu pesan dikirim.
channel_message_id	String	wajib	ID pesan dari WhatsApp.
whatsapp_business_account_id	String	wajib	ID akun bisnis WhatsApp pengirim.
timezone	String	wajib	zona waktu organisasi
plan_user_total	int	opsional	total target terjadwal. Hanya ada jika message_status = plan.
country_code	String	wajib	kode negara nomor ponsel penerima.
from_phone_id	String	wajib	ID nomor pengirim (from)
conversation	JSON Object	opsional	informasi sesi
pricing	JSON Object	opsional	informasi harga

conversation

Field	Tipe	Opsi	Deskripsi
id	String	opsional	ID sesi Meta tempat pesan berada.
origin	JSON Object	opsional	Siapa yang memulai percakapan, ditentukan oleh type. Contoh: "origin":{"type":"business_initiated"}. Nilai valid: business_initiated: Percakapan dimulai saat perusahaan mengirim pesan pertama ke pelanggan (lebih dari 24 jam dari pesan terakhir pelanggan). customer_initiated: Percakapan dimulai saat perusahaan membalas pesan pelanggan (dalam 24 jam sejak pesan terakhir pelanggan). referral_conversion: Percakapan dari titik masuk gratis. Selalu dimulai oleh pelanggan.

pricing

Field	Tipe	Opsi	Deskripsi
pricing_model	String	opsional	nilai tetap: CBP
category	String	opsional	kategori harga percakapan. Nilai valid: business_initiated: Percakapan merchant. customer_initiated: Percakapan pengguna. referral_conversion: Percakapan titik akses gratis.

error_detail

Field	Tipe	Opsi	Deskripsi
message	String	wajib	penyebab

loss

Field	Tipe	Opsi	Deskripsi
loss_step	int	wajib	tahap kehilangan 1: Target plan ke target efektif (target tidak valid) 2: Target valid ke pengiriman (gagal kirim) 3: Pengiriman ke diterima (gagal diterima)
loss_source	String	wajib	sumber kehilangan. Nilai valid: engagelab: Kehilangan akibat verifikasi EngageLab meta: error dari Meta.

Contoh Callback

{ "total": 1, "rows": [ { "message_id": "1666165485030094861", "from": "", "to": "", "server": "whatsapp", "channel": "whatsapp", "itime": 1640707579, "custom_args": {}, "status": { "message_status": "delivered", "status_data": { "msg_time": 1663432355, "channel_message_id": "wamid.123321abcdefed==", "whatsapp_business_account_id": "", "timezone": "", "plan_user_total": 2007, "country_code": "CN", "from_phone_id": "111111", "conversation": { "id": "ebe2398cdaa37a0899ca5268b987b0c8", "origin": { "type": "business_initiated" } }, "pricing": { "pricing_model": "CBP", "category": "business_initiated" } }, "error_code": 0, "error_detail": { "message": "" }, "loss": { "loss_step": 1, "loss_source": "aa" } } } ] }

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861",
            "from": "",
            "to": "",
            "server": "whatsapp",
            "channel": "whatsapp",
            "itime": 1640707579,
            "custom_args": {},
            "status": {
                "message_status": "delivered",
                "status_data": {
                    "msg_time": 1663432355,
                    "channel_message_id": "wamid.123321abcdefed==",
                    "whatsapp_business_account_id": "",
                    "timezone": "",
                    "plan_user_total": 2007,
                    "country_code": "CN",
                    "from_phone_id": "111111",
                    "conversation": {
                        "id": "ebe2398cdaa37a0899ca5268b987b0c8",
                        "origin": {
                            "type": "business_initiated"
                        }
                    },
                    "pricing": {
                        "pricing_model": "CBP",
                        "category": "business_initiated"
                    }
                },
                "error_code": 0,
                "error_detail": {
                    "message": ""
                },
                "loss": {
                    "loss_step": 1,
                    "loss_source": "aa"
                }
            }
        }
    ]
}

Tampilkan blok kode ini di jendela mengambang

Respons Pesan

Parameter callback

Field	Tipe	Opsi	Deskripsi
event	string	opsional	event respons
response_data	JSON Object	opsional	isi pesan balasan/interaksi upstream

event

Nilai	Deskripsi	Detail
received	pesan pengguna diterima	pengguna mengirim pesan langsung.
reply	pengguna membalas pesan Anda.	Perusahaan mengirim pesan ke pengguna terlebih dahulu, lalu pengguna membalas pesan tersebut.
order	pengguna melakukan pemesanan	-
deleted	pengguna menghapus pesannya.	Pesan yang dikirim pengguna dihapus sendiri (segera tersedia)

response_data

Field	Tipe	Opsi	Deskripsi
channel_message_id	String	wajib	ID pesan dari WhatsApp.
whatsapp_business_account_id	String	wajib	ID akun bisnis WhatsApp pengirim.
contact	JSON Object	opsional	info pengirim
message	JSON Object	wajib	isi pesan
message_context	JSON Object	Opsional	Konteks pesan, muncul pada event reply, menunjukkan pesan mana yang dibalas pengguna

contact

Field	Tipe	Opsi	Deskripsi
profile	JSON Object	opsional	info pengirim (pelanggan). Saat ini hanya field name yang menunjukkan nama pelanggan. Contoh: "profile": {"name": "bob"}
wa_id	String	opsional	nomor pengirim.

message

Field	Tipe	Opsi	Deskripsi
type	String	wajib	nilai valid: text, image, audio, video, document, sticker, button, interactive, unknown, order.
text	JSON Object	opsional	Lihat deskripsi objek text
image	JSON Object	opsional	Lihat deskripsi objek image
audio	JSON Object	opsional	Lihat deskripsi objek audio
video	JSON Object	opsional	Lihat deskripsi objek video
document	JSON Object	opsional	Lihat deskripsi objek document
sticker	JSON Object	opsional	Lihat deskripsi objek sticker

message_context

Field	Tipe	Opsi	Deskripsi
origin_from_phone	String	Wajib	Nomor pengirim pesan yang dirujuk, tanpa spasi atau simbol +
origin_channel_message_id	String	Wajib	ID unik pesan yang dirujuk
origin_from_phone_id	String	Opsional	ID nomor pengirim pesan yang dirujuk, biasanya ada field ini
origin_message_id	String	Opsional	ID pesan yang dirujuk, biasanya ada field ini

Contoh Callback

{ "total": 1, "rows": [ { "message_id": "1666165485030094861", "from": "", "to": "", "server": "whatsapp", "channel": "whatsapp", "itime": 1640707579, "response": { "event": "", "response_data": { "channel_message_id": "wamid.123321abcdefed==", "whatsapp_business_account_id": "123321", "contact": { "profile": { "name": "bob" }, "wa_id": "8613800138000" }, "message": { "type": "text", "text": { "body": "ini adalah isi pesan teks" } } } } } ] }

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861",
            "from": "",
            "to": "",
            "server": "whatsapp",
            "channel": "whatsapp",
            "itime": 1640707579,
            "response": {
                "event": "",
                "response_data": {
                    "channel_message_id": "wamid.123321abcdefed==",
                    "whatsapp_business_account_id": "123321",
                    "contact": {
                        "profile": {
                            "name": "bob"
                        },
                        "wa_id": "8613800138000"
                    },
                    "message": {
                        "type": "text",
                        "text": {
                            "body": "ini adalah isi pesan teks"
                        }
                    }
                }
            }
        }
    ]
}

Tampilkan blok kode ini di jendela mengambang

Notifikasi Pesan - Notification

Parameter Callback

Field	Tipe	Opsi	Deskripsi
event	string	Opsional	Event respons
notification_data	JSON Object	Opsional	Isi detail notifikasi pesan sistem

event

Nilai	Deskripsi	Penjelasan Detail
insufficient_balance	Saldo Tidak Cukup	Saldo real-time di bawah ambang batas yang Anda atur (default $10)
template_update	Status Template Berubah	Perubahan status dan kualitas template
phone_number_update	Status Nomor Pengirim Berubah	Perubahan status nomor pengirim, saat ini hanya perubahan "batas pengiriman pesan" yang didukung resmi, nilai: TIER_50：50 pelanggan/24 jam TIER_250：250 pelanggan/24 jam TIER_1K：1000 pelanggan/24 jam TIER_10K：10000 pelanggan/24 jam TIER_100K：100000 pelanggan/24 jam TIER_UNLIMITED：Tanpa Batas
whatsapp_business_update	Akun WABA Berubah	Akun WABA diblokir, diperingatkan, dll.

notification_data

Field	Tipe	Opsi	Deskripsi
whatsapp_business_account_id	String	Wajib	Nomor akun bisnis WhatsApp
remain_balance	int	Opsional	Ada jika event insufficient_balance Saldo real-time saat ini (USD)
balance_threshold	int	Opsional	Ada jika event insufficient_balance Ambang batas saldo yang Anda atur (USD)
template_id	String	Opsional	Ada jika event template_update ID template
template_name	String	Opsional	Ada jika event template_update Nama template
template_language	String	Opsional	Ada jika event template_update Bahasa template
template_status	String	Opsional	Ada jika event template_update Status template: APPROVED/REJECTED/PENDING/DISABLED/FLAGGED/REINSTATED
template_status_reason	String	Opsional	Ada jika event template_update Alasan perubahan, biasanya saat template ditolak, jika tidak string "NONE" atau kosong
phone_number_id	String	Opsional	Ada jika event phone_number_update ID nomor pengirim
display_phone_number	String	Opsional	Ada jika event phone_number_update, nomor pengirim, contoh: +1 320-302-7083 +86 183 7981 2430
current_limit	String	Opsional	Ada jika event phone_number_update Batas pengiriman nomor saat ini: TIER_50/TIER_250/TIER_1K/TIER_10K/TIER_100K/TIER_UNLIMITED
waba_event	String	Opsional	Ada jika event whatsapp_business_update, nilai: DISABLED_UPDATE Akun dinonaktifkan ACCOUNT_VIOLATION Pelanggaran akun
ban_state	String	Opsional	Ada jika event whatsapp_business_update dan waba_event DISABLED_UPDATE, nilai: DISABLE Dinonaktifkan
violation_type	String	Opsional	Ada jika event whatsapp_business_update dan waba_event ACCOUNT_VIOLATION, nilai: SPAM Ditandai spam/pelecehan SCAM Ditandai penipuan

Contoh Callback

{ "total": 1, "rows": [ { "server": "whatsapp", "itime": 1640707579, "notification": { "event": "insufficient_balance", "notification_data": { "whatsapp_business_account_id": "", "remain_balance": 5.1234, "balance_threshold": 10 } } } ] }

              
              {
  "total": 1,
  "rows": [
    {
      "server": "whatsapp",
      "itime": 1640707579,
      "notification": {
        "event": "insufficient_balance",
        "notification_data": {
          "whatsapp_business_account_id": "",
          "remain_balance": 5.1234,
          "balance_threshold": 10
        }
      }
    }
  ]
}

Tampilkan blok kode ini di jendela mengambang