Langsung ke konten utama
GOWA mengirim dokumen JSON melalui POST ke URL Anda untuk setiap event WhatsApp yang diterimanya: pesan, tanda terima, reaksi, pengeditan, penghapusan, indikator mengetik, perubahan grup, label, newsletter, dan panggilan. Tidak ada endpoint pendaftaran webhook. Konfigurasikan webhook saat startup, atau per perangkat melalui /devices/{device_id}/webhook.

Cara kerja pengiriman

Pengiriman ke setiap URL tujuan dilakukan secara independen, dengan secret dan percobaan ulang masing-masing.

Konfigurasi

Flag yang setara: --webhook, --webhook-secret, --webhook-events, --webhook-ignore-jids, --webhook-insecure-skip-verify, dan --webhook-all-device-receipts. Tetapkan kunci penandatanganan privat secara eksplisit. Jika kunci tidak diatur atau menggunakan nilai lama yang dipublikasikan, yaitu secret, GOWA akan membuat kunci acak yang berubah setiap restart dan mencatat peringatan. Penerima memerlukan kunci bersama yang ditetapkan secara eksplisit agar dapat memverifikasi tanda tangan setelah restart. Sertifikat HTTPS diverifikasi secara default.

Event

Nama event dalam daftar yang diizinkan tidak membedakan huruf besar dan kecil.

Payload

Setiap permintaan menggunakan struktur pembungkus yang sama:
Balasan menambahkan replied_to_id dan quoted_body. Tanda terima menggunakan ids (array) dan receipt_type. Event peserta grup menyertakan chat_id, type, dan jids. Perubahan nama grup menggunakan struktur group.info tersendiri. sender_display_name hanya muncul jika from berupa string yang tidak kosong. Untuk pengirim lain, GOWA memprioritaskan nama kontak tersimpan, push name dari event langsung, push name tersimpan, nama bisnis, lalu bagian pengguna dari JID. Untuk akun aktif, GOWA memprioritaskan push name akun, lalu identitas JID-nya. Penentuan nama dilakukan sebisa mungkin berdasarkan data yang tersedia. Field lama from_name tetap berisi push name dari event pesan. Pesan masuk dapat menyertakan is_business: true, verified_name, dan verified_level jika WhatsApp menyediakan sertifikat nama terverifikasi. Field ini tidak disertakan jika sertifikat tidak tersedia. Ketiadaannya tidak menentukan apakah pengirim merupakan bisnis, dan verified_level adalah nilai mentah dari upstream, bukan jaminan adanya lencana resmi.

Media

Dengan WHATSAPP_AUTO_DOWNLOAD_MEDIA=true (default), media disimpan di statics/media/ dan field media berisi path-nya:
Jika ada keterangan, field berubah menjadi {"path": "...", "caption": "..."} dan keterangannya juga berada di body. Jika unduhan otomatis dinonaktifkan, nilainya adalah {"url": "https://mmg.whatsapp.net/...", "caption": "..."}; ambil file nanti dengan GET /message/{message_id}/download?phone=<chat>. Katalog payload lengkap (polling, lokasi, kontak, sekali lihat, rujukan iklan, dan lainnya) tersedia di referensi payload webhook upstream.

Album dan pesan terstruktur

Album diterima sebagai beberapa event message. Header tidak memiliki isi pesan dan menyertakan jumlah item yang diharapkan:
Setiap foto atau video diterima sebagai event media biasa tersendiri dengan album_id: "ALBUM_HEADER_ID". Kelompokkan item berdasarkan ID tersebut. Header bukan item media yang dapat diunduh dan tidak diteruskan ke Chatwoot. Pembuatan polling, pemberian suara, pengeditan, dan penambahan opsi juga menggunakan message. Periksa objek poll terstruktur alih-alih hanya mengandalkan body. Hash opsi adalah hash SHA-256 heksadesimal huruf kecil dari nama opsi yang persis sama. Langganan WHATSAPP_WEBHOOK_EVENTS=message yang sudah ada menerima interaksi ini.

Presence online dan offline

Berlangganan untuk setiap kontak individual menggunakan perangkat yang sama dengan penerima event:
Respons berhasil berisi results.subscribed: true dan results.jid. JID grup dan newsletter ditolak. Langganan tidak menggantikan pengaturan presence perangkat Anda. Untuk pembaruan terus-menerus, jalankan GOWA dengan:
Pulse presence default diakhiri dengan menandai perangkat sebagai tidak tersedia, sehingga pembaruan presence kontak berhenti. Menandai perangkat sebagai tersedia akan menonaktifkan notifikasi push WhatsApp di ponsel selama status tersebut aktif. Pertimbangkan konsekuensi ini sebelum mengaktifkan pemantauan terus-menerus.
state bernilai available atau unavailable. last_seen tidak disertakan jika tidak diketahui atau disembunyikan oleh pengaturan privasi kontak. from_lid disertakan jika berlaku. Aktivitas mengetik dan merekam tetap menggunakan event chat_presence terpisah dan tidak menggunakan langganan ini.

Perubahan nama grup

name_set_by dikonversi dari LID ke JID nomor telepon jika memungkinkan dan tidak disertakan jika WhatsApp tidak mengidentifikasi pelakunya. Berlangganan group.info secara eksplisit jika daftar event yang diizinkan mengecualikan event lain.

Pembaruan penghitung newsletter

newsletter.message melaporkan penghitung secara langsung, bukan jaminan isi postingan baru. Setiap entri selalu menyertakan server_id. message_id, type, dan timestamp tidak disertakan jika WhatsApp tidak menyediakannya. Penghitung yang bernilai nol atau tidak tersedia mungkin tidak disertakan.
Jika tersedia, reaction_counts berisi jumlah reaksi dari WhatsApp. Proses pembaruan berdasarkan ID newsletter dan ID server. Jangan anggap penghitung yang tidak disertakan sebagai pengaturan ulang ke nol.

Pembatasan akun dan logout

Event perangkat selalu menyertakan session_id, sehingga slot yang menggunakan nomor WhatsApp sama tetap dapat dibedakan. Event menggunakan konfigurasi webhook slot yang mengirimkannya. Logout jarak jauh mempertahankan slot agar dapat dipasangkan ulang dan melaporkan identitas sebelum logout. Pengaturan webhook slot tetap tersimpan setelah pemasangan ulang. Event ini tidak dikirim ke Chatwoot.
Kode diteruskan tanpa perubahan dan teks alasan berasal dari whatsmeow. Kode yang tidak dikenal tetap diterima. Kode logout 403 dan 406 saja tidak menunjukkan penyebab pastinya. Durasi pemblokiran sementara bernilai nol berarti WhatsApp tidak memberikan waktu berakhir. Reach-out timelock membatasi dimulainya chat baru dan dapat menyebabkan error pengiriman 463.

Memverifikasi tanda tangan

Setiap permintaan menyertakan X-Hub-Signature-256: sha256=<hex>, yaitu HMAC-SHA256 dari isi permintaan mentah dengan secret webhook sebagai kuncinya. Hitung berdasarkan byte yang diterima secara persis, sebelum mem-parsing JSON.

Pengiriman dan percobaan ulang

  • Setiap percobaan memiliki batas waktu 10 detik.
  • Respons non-2xx atau error jaringan akan dicoba ulang. GOWA melakukan hingga 5 percobaan, dengan jeda 1 dtk, 2 dtk, 4 dtk, dan 8 dtk di antaranya. Tenggat konteks handler event dapat menghentikan pengiriman sebelum semua percobaan selesai.
  • Setelah kegagalan terakhir, event dibuang dan dicatat di log. Tidak ada antrean persisten atau penyimpanan dead-letter.
  • Pengiriman ke beberapa URL dilakukan secara independen.
Berikan respons 2xx setelah menerima event ke dalam antrean pemrosesan persisten Anda sendiri. Buat handler yang idempoten karena event yang dicoba ulang dapat tiba lebih dari sekali.

Tanda terima perangkat tertaut

Secara default, GOWA hanya meneruskan konfirmasi kontak dari perangkat utama untuk mengurangi duplikasi. Tanda terima read dan read-self milik akun saat ini tetap diteruskan dari semua perangkatnya. Untuk tanda terima milik akun sendiri ini, payload.from adalah JID akun dan payload.ids mengidentifikasi pesan masuk yang telah dibaca. Tetapkan WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true atau --webhook-all-device-receipts=true agar juga menerima tanda terima kontak dari perangkat tertaut, termasuk saat ponsel kontak offline. Flag CLI menggantikan nilai dari environment, termasuk nilai false yang ditetapkan secara eksplisit. Opsi ini dapat menghasilkan konfirmasi duplikat atau tidak berurutan. Terapkan pembaruan secara idempoten berdasarkan akun, chat, dan ID pesan. Jangan pernah menurunkan status pesan yang sudah dibaca menjadi terkirim saat tanda terima lama tiba. ID pesan dan JID pengirim mempertahankan bentuk kanonisnya tanpa akhiran perangkat.

Memfilter event

Berdasarkan jenis: WHATSAPP_WEBHOOK_EVENTS=message,message.ack hanya meneruskan event tersebut. Berdasarkan chat atau pengirim: WHATSAPP_WEBHOOK_IGNORE_JIDS mencocokkan chat_id, from, chat_lid, dan from_lid. Entri yang diawali @ adalah wildcard untuk seluruh ruang alamat (@g.us, @s.whatsapp.net, @lid); entri lainnya harus cocok persis dengan JID.
@s.whatsapp.net juga cocok dengan pesan grup karena from-nya adalah JID pengguna. Gunakan @g.us untuk membisukan grup. Kedua filter diterapkan bersama: event hanya dikirim jika jenisnya diizinkan dan JID-nya tidak diabaikan.

Webhook per perangkat

Berikan webhook, secret, dan daftar event yang diizinkan khusus untuk suatu slot:
Field yang sama juga diterima oleh POST /devices. Baca pengaturan saat ini dengan GET /devices/{device_id}/webhook. Kirim "webhook_url": "" untuk menghapusnya. Jika webhook_secret atau webhook_events perangkat kosong, pengaturan global terkait akan digunakan. Nilai boolean webhook_insecure_skip_verify perangkat yang tersimpan menggantikan pengaturan TLS global. Secara khusus, false mempertahankan verifikasi sertifikat meskipun pengabaian verifikasi global diaktifkan. Secara default, URL per perangkat menggantikan WHATSAPP_WEBHOOK global untuk slot tersebut. Dengan WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true, URL tersebut ditambahkan ke URL global: URL perangkat menggunakan secret dan daftar event yang diizinkan milik perangkat, URL global tetap menggunakan pengaturan global, dan URL yang terdapat di keduanya menerima event satu kali. Aturan pengabaian JID berlaku untuk keduanya.

Menguji secara lokal

Publikasikan penerima lokal melalui tunnel (misalnya ngrok http 8080) dan tetapkan WHATSAPP_WEBHOOK ke URL tunnel. Dengan --debug=true, GOWA mencatat setiap percobaan pengiriman dan kegagalan.

Cara lain menerima event

  • WebSocket di /ws?device_id=<id> mengirim event pemasangan dan status ke klien dashboard. Gunakan webhook untuk pengiriman pesan.
  • Polling: GET /chats dan GET /chat/{chat_jid}/messages membaca penyimpanan chat lokal GOWA. Lihat Menerima pesan.