Logo Site EngageLab Mark Colored TransparentDokumen
WhatsApp
Beranda Dokumen
Akses CepatPanduan KonsolPanduan Operasi MetaAPI RESTFAQCatatan Perubahan
Cari
Masuk
API REST/API Callback Pesan
API RESTAPI Callback Pesan...

API Callback Pesan

Terakhir diperbarui：2 hari yang lalu

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.

Callback status pesan dan pesan masuk pengguna dapat menyertakan Business-Scoped User ID (BSUID) untuk mengidentifikasi pengguna WhatsApp terkait. BSUID dikembalikan melalui field opsional baru dan tidak memengaruhi field maupun event callback yang sudah ada.

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. Dikembalikan pada callback status dan pesan masuk; tetap menggunakan arti awal sebagai field nomor dan tidak boleh digunakan sebagai BSUID.
to string opsional Penerima. Dikembalikan pada callback status dan pesan masuk; tetap menggunakan arti awal sebagai field nomor dan tidak boleh digunakan sebagai BSUID.
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

Field BSUID

BSUID dikembalikan melalui field opsional berikut dalam payload callback yang sudah ada:

Jenis callback Jalur JSON Tipe Deskripsi
Callback status pesan rows[].status.status_data.recipient_user_id String BSUID penerima
Callback pesan masuk pengguna rows[].response.response_data.contact.user_id String BSUID pengguna yang mengirim pesan
  • Jika BSUID tidak tersedia, field terkait tidak dikembalikan. Parser di sisi klien harus mengizinkan field tersebut tidak ada.
  • Untuk menampilkan nomor dan BSUID sekaligus, gunakan to bersama status_data.recipient_user_id pada callback status, atau contact.wa_id bersama contact.user_id pada callback pesan masuk.
  • Field BSUID hanya digunakan untuk mengidentifikasi pengguna dalam callback. API pengiriman saat ini belum mendukung BSUID sebagai penerima.

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)
recipient_user_id String opsional BSUID penerima; dikembalikan jika tersedia dan tidak disertakan jika tidak tersedia
conversation JSON Object opsional informasi sesi
pricing JSON Object opsional informasi harga

recipient_user_id umumnya dikembalikan pada callback sent, delivered, dan read setelah BSUID penerima tersedia. Field ini mungkin tidak disertakan pada status prapemrosesan atau kegagalan, pesan historis, maupun data yang dihasilkan melalui alur pemrosesan lama.

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", "recipient_user_id": "ID.1234567890123456", "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",
                    "recipient_user_id": "ID.1234567890123456",
                    "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.
    user_id String opsional BSUID pengguna yang mengirim pesan; dikembalikan jika tersedia dan tidak disertakan jika tidak tersedia

    contact.wa_id tetap menggunakan arti awal sebagai field nomor, sedangkan contact.user_id berisi BSUID. Untuk mengidentifikasi pengguna berdasarkan BSUID, baca contact.user_id; jangan gunakan from, to, atau contact.wa_id sebagai BSUID.

    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", "user_id": "ID.1234567890123456" }, "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",
                        "user_id": "ID.1234567890123456"
                    },
                    "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
    Icon Solid Transparent White Qiyu
    Hubungi Sales