Skip to main content

Webhook pesan, dan status pesan

Webhook ini memungkinkan aplikasi menerima notifikasi saat ada pesan masuk atau perubahan status pesan. Pesan dapat berupa teks, reply, reaction, atau update status pesan.

Kategori Webhook​

Tiga kategori webhook terkait pesan:

  • message: Menerima pesan masuk, termasuk teks, reply, dan reaction.
  • message_ack: Status pengiriman pesan di perangkat.
  • message_ack_browser: Status pengiriman pesan di WhatsApp Web.

Message​

Karena webhook message ini kompleks, ada beberapa hal yang perlu Anda ketahui, di webhook message dibagi menjadi 3 object type lagi :

  • reactionMessage
  • extendedTextMessage
  • conversation

reactionMessage adalah pesan yang diberikan reaction oleh pengguna whatsapp lain

extendedTextMessage dan conversation adalah object type untuk menerima pesan masuk berupa text, kedua object ini memiliki struktur yang sama, jadi Anda tidak perlu bingung dengan kedua type ini, karena keduanya tidak berbeda struktur json!.

Lebih lengkapnya silahkan lihat object json dibawah

{
  "type": "message", // Tipe webhook yang dikirim
  "results": { // Kumpulan object dari event message
    /*
      Object dibawah ini hanya akan tampil ketika Anda mengirim pesan lewat API
    */
    "messageStubParameters": [],
    "labels": [],
    "userReceipt": [],
    "reactions": [],
    "pollUpdates": [],
    "eventResponses": [],
    "statusMentions": [],
    "messageAddOns": [],
    "statusMentionSources": [],
    "supportAiCitations": [],
    /* ---------------- */
    "key": { // Informasi pengirim
      "remoteJid": "[email protected]", // Nomer pengirim
      "fromMe": false, // Dikirim dari nomer sendiri ?
      "id": "xxxxx", // ID pesan
      "senderLid": "xxxxx@lid", // Nomor samaran di whatsapp
      "senderPn": "[email protected]" // Nomer pengirim
    },
    "messageTimestamp": 1691639955, // Waktu pesan
    "pushName": "xxxxx", // Nama Whatsapp
    "broadcast": false, // Apakah pesan broadcast ?
    "status": 2, // Object ini hanya muncul ketika mengirim pesan via API
    "message": {
      ... // Object disini adalah raw pesan whatsapp, bisa berubah sewaktu2
    },
    "verifiedBizName": "WHAPI", // Object untuk nama whatsapp bisnis
    "t": 1691639955, // Waktu pesan
    "id": "xxxxx", // ID pesan
    "from": "[email protected]", // Nomer pengirim
    "fromMe": false, // Dikirim dari nomer sendiri ?
    "chatId": "[email protected]", // Nomer pengirim
    "isGroupMsg": false, // Apakah pesan dari grup ?
    "isStories": false, // Apakah pesan story ?
    "sender": "[email protected]", // Nomer pengirim
    "pushname": "WHAPI", // Object untuk nama whatsapp bisnis
    "timestamp": 1691639955, // Waktu pesan
    "isEphemeralMessage": false,
    "viewOnce": false, // Pesan dilihat 1x
    "type": "extendedTextMessage", // ada 3 type reactionMessage | extendedTextMessage | conversation
    "isMedia": false, // Apakah pesan media?
    "quotedMsg": { // Jika pesan berupa quote, akan ada data disini
     ... // Data object disini adalah raw dari whatsapp.
    }, 
    "mentionedJidList": [], // Mention nama akan muncul disini
    "body": "Isi Pesan", // Berisi isi pesan / caption pada gambar / caption pada dokumen
    "replyData": "xxxxxx", // ID Untuk mereply pesan ini
    "apiKey": "xxxxx" // Alamat API Key dari device
  }
}

Struktur dari webhook json message seperti contoh diatas, kami akan jelaskan beberapa object tertentu :

  • verifiedBizName, object ini hanya akan muncul ketika whatsapp yang digunakan adalah whatsapp bisnis.
  • status, berfungsi untuk penanda bahwa pesan berhasil dikirim dengan status pending. Terkait status ini, nanti akan dibahas pada message_ack dan message_ack_browser. Object ini hanya akan muncul ketika mengirim pesan via API.
  • messageTimestamp, timestamp, dan t. Ketiga object ini sama - sama untuk menampilkan waktu pesan dikirim
  • results -> message, ini adalah object raw dari whatsapp. Isi dari object ini bisa berubah sewaktu - waktu. Perlu dilihat secara berkala jika ada perubahan, karena object ini tidak statis. Jika kebutuhannya mengambil text/caption pesan, silahkan ambil di object body.
  • quotedMsg, ini adalah object ketika ada pesan yang di quote, raw json pada object ini berubah - ubah, silahkan diesuaikan dengan kebutuhan Anda.
  • mentionedJidList, ketika isi pesan memiliki mention nomor, akan ditampilkan disini

Message Ack​

Event webhook dengan type message_ack akan dikirim ketika ada perubahan status pesan di device. Status pesan ada 5 tipe, yaitu :

  • 0 -> Error
  • 2 -> Pending
  • 3 -> Pesan berhasil dikirim
  • 4 -> Pesan dibaca
  • 5 -> Pesan audio berhasil didengarkan
{
  "type": "message_ack", // Tipe webhook yang dikirim
  "results": { // Kumpulan object dari event message_ack
    "apiKey": "xxxxx", // Alamat API Key dari device 
    "ack": {
      "ack": 2, // Status perubahan pesan 2, 3, 4, 5
      "id": "xxxxx", // ID dari pesan
      "serialized": "[email protected]" // Nomer tujuan
    }
  }
}

Message Ack Browser​

Event webhook dengan type message_ack_browser akan dikirim ketika ada perubahan status pesan di whatsapp web. Object dari event ini sama saja dengan message_ack, hanya saja untuk event ini dikhususkan untuk perubahaan pesan whatsapp web.

Use Case​

  • Menerima pesan teks atau reply secara real-time untuk otomatisasi balasan
  • Memantau reaksi pesan untuk analisis interaksi pengguna
  • Mengetahui status pengiriman pesan agar sistem menindaklanjuti pesan gagal
  • Memantau pesan di WhatsApp Web secara terpisah untuk aplikasi multi-platform

Catatan Teknis​

  • Endpoint webhook harus menerima request POST dengan payload JSON
  • Pastikan autentikasi API valid dan perangkat aktif
  • Tangani ketiga object type reactionMessage, extendedTextMessage, dan conversation secara konsisten

Kesimpulan​

Webhook pesan dan status pesan membantu sistem memproses pesan masuk, reaksi, dan status pengiriman secara real-time di perangkat maupun WhatsApp Web. Integrasi ini memudahkan otomatisasi balasan dan menjaga kualitas komunikasi.