/devices/{device_id}/webhook.
Cara kerja pengiriman
Pengiriman ke setiap URL tujuan dilakukan secara independen, dengan secret dan percobaan ulang masing-masing.Konfigurasi
--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
DenganWHATSAPP_AUTO_DOWNLOAD_MEDIA=true (default), media disimpan di statics/media/ dan field media berisi path-nya:
{"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 eventmessage. Header tidak memiliki isi pesan dan menyertakan jumlah item yang diharapkan:
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: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:
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.
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 menyertakansession_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 menyertakanX-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.
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 terimaread 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: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 (misalnyangrok 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 /chatsdanGET /chat/{chat_jid}/messagesmembaca penyimpanan chat lokal GOWA. Lihat Menerima pesan.
