Persyaratan
- GOWA dapat dijangkau dari Chatwoot melalui URL publik (untuk webhook balasan agen).
- Akun Chatwoot dengan akses admin dan token akses API pengguna.
- Setidaknya satu perangkat WhatsApp yang sudah login.
Penyiapan
1
Buat inbox saluran API
Di Chatwoot, buka Settings → Inboxes → Add Inbox → API. Catat ID inbox numerik dari URL inbox, serta secret webhook yang ditampilkan Chatwoot untuk saluran tersebut. Anda juga dapat membiarkan GOWA membuat inbox (lihat Penyediaan otomatis).
2
Kumpulkan ID dan token
ID akun adalah angka pada
/app/accounts/<id>/.... Salin token akses pengguna dari Profile Settings. Kedua ID harus berupa ID numerik, bukan identifier saluran atau hmac_token.3
Konfigurasikan GOWA
.env
4
Arahkan Chatwoot ke GOWA
Atur URL webhook saluran API ke
https://gowa.example.com/chatwoot/webhook (jika menggunakan APP_BASE_PATH, sertakan base path). Rute ini bersifat publik: rute dilindungi secret webhook, bukan Basic Auth.5
Uji
Kirim pesan ke nomor WhatsApp dari ponsel lain; pesan seharusnya muncul di inbox. Balas dari Chatwoot dan periksa apakah balasan diterima di WhatsApp.
Konfigurasi
Sebagian besar pengaturan juga memiliki flag
--chatwoot-*; CHATWOOT_URL, CHATWOOT_API_TOKEN, CHATWOOT_ACCOUNT_ID, dan CHATWOOT_INBOX_ID hanya tersedia melalui variabel lingkungan. Lihat referensi konfigurasi.
Pada GOWA main setelah v9.9.0, atur CHATWOOT_EVENTS=message agar pesan tetap disalin ke Chatwoot sambil memfilter pengiriman webhook biasa secara terpisah. Selektor message juga mengizinkan reaksi, tanda terima, pengeditan, dan penghapusan melewati filter Chatwoot. Pengaturan terpisah untuk pembacaan, pengeditan, dan penghapusan tetap berlaku.
Biarkan CHATWOOT_EVENTS kosong untuk mewarisi WHATSAPP_WEBHOOK_EVENTS. Jika filter efektif kosong, semua event yang didukung diizinkan. Jika filter mengecualikan message, GOWA mencatat peringatan saat startup dan berhenti menyalin pesan WhatsApp ke Chatwoot.
Pada build tersebut, GOWA mengirim token pengguna Chatwoot dalam header api-access-token agar nginx dapat meneruskannya dengan pengaturan header default.
Secret webhook
Secret webhook efektif yang kosong menyebabkan pengiriman ditolak.CHATWOOT_WEBHOOK_ALLOW_UNSIGNED=true secara eksplisit mengizinkan pengiriman tanpa tanda tangan saat secret efektif kosong. Jika secret dikonfigurasi, setiap permintaan harus membuktikannya melalui salah satu cara berikut:
- Tanda tangan Chatwoot (
X-Chatwoot-Signature+X-Chatwoot-Timestamp), direkomendasikan. Gunakan secret webhook milik saluran API itu sendiri. GOWA memeriksa HMAC-SHA256 dari<timestamp>.<raw body>dan menolak timestamp di luar toleransi yang dikonfigurasi. - HMAC body pada
X-Hub-Signature-256. - Secret dalam header
X-Chatwoot-Webhook-SecretatauX-Gowa-Chatwoot-Secret. ?secret=dalam URL webhook, hanya untuk versi Chatwoot yang tidak dapat menandatangani atau menambahkan header. Secret kemudian akan muncul di log akses.
401; GOWA mencatat penyebabnya (signature does not match berarti secret salah, timestamp outside the tolerance window berarti ada penyimpangan waktu jam).
webhook_secret perangkat menggantikan secret global untuk perangkat tersebut pada endpoint bersama maupun endpoint per perangkat. Tanpa secret perangkat, secret global berlaku. GOWA memverifikasi secret untuk perangkat tujuan sebelum mengirim, menghapus, menandai dibaca, atau menulis data. Utamakan URL callback per perangkat saat beberapa perangkat menggunakan ID akun dan inbox yang sama.
Permintaan berulang bertanda tangan Chatwoot yang telah menerima 2xx akan diakui dengan 200 dan dilewati selama masih dalam jendela timestamp. Permintaan yang gagal tetap dapat dicoba ulang. Permintaan identik yang masih diproses dapat mengembalikan 503 setelah menunggu hingga 30 detik. Memori pendeteksi pengulangan bersifat lokal pada proses, hilang saat restart, dan dibatasi hingga 65,536 permintaan yang diterima. Memori ini tidak dibagikan antarinstans GOWA. Dua pengiriman pesan Chatwoot yang sama dengan tanda tangan terpisah masih dapat menyebabkan pengiriman dua kali. HMAC yang hanya mencakup body, header secret, dan secret pada kueri tidak menyediakan deduplikasi pengiriman ini.
Penyediaan otomatis
DenganCHATWOOT_AUTO_CREATE=true dan tanpa CHATWOOT_INBOX_ID, saat startup GOWA mencari inbox API bernama CHATWOOT_INBOX_NAME dan menggunakannya kembali, atau membuat inbox dengan CHATWOOT_WEBHOOK_URL sebagai webhook-nya.
Satu inbox per perangkat
Variabel lingkungan mengonfigurasi satu tujuan bersama untuk semua perangkat. Untuk merutekan setiap perangkat ke inbox, akun, atau server Chatwoot masing-masing, simpan konfigurasi per perangkat (Basic Auth berlaku):webhook_url (<base>/chatwoot/webhook/<device_id>); atur sebagai webhook inbox tersebut. Rute lainnya: GET /chatwoot/configs, GET dan DELETE /devices/{device_id}/chatwoot/config.
api_tokendisimpan di database GOWA dan disamarkan saat dibaca;webhook_secrettidak pernah dikembalikan.chatwoot_urlharus menggunakan HTTP atau HTTPS tanpa kredensial. TanpaCHATWOOT_ALLOWED_HOSTS, alamat privat, loopback, link-local, dan metadata ditolak. Host eksplisit yang cocok dalamCHATWOOT_ALLOWED_HOSTSdipercaya dan dapat mengarah ke Chatwoot yang dihosting sendiri pada jaringan privat. Isi daftar izin ini hanya dengan host yang Anda kendalikan.- Mengubah
chatwoot_url,account_id, atauinbox_idsetelah percakapan ditautkan mengembalikan409; hapus dan buat ulang konfigurasinya. - Konfigurasi dapat dibuat sebelum perangkat dipasangkan.
- Impor database langsung hanya berfungsi dalam mode konfigurasi tunggal (lingkungan).
Balasan dan pemformatan
Saat agen menggunakan Reply di Chatwoot, GOWA mengutip pesan WhatsApp asli jika pesan dapat ditemukan dalam penyimpanan lokal perangkat pengirim dan chat yang sama. Ini berlaku untuk teks dan setiap lampiran, termasuk fallback audio sebagai file. Caption hanya disertakan pada lampiran pertama. Untuk pesan WhatsApp masuk, GOWA mencariin_reply_to_external_id dengan awalan WAID:<id>. Untuk balasan agen sebelumnya, in_reply_to numerik dicari melalui tautan pesan persisten pada perangkat, percakapan, akun, inbox, dan konfigurasi yang sama. Pesan dengan beberapa lampiran mengutip file pertamanya. Jika target tidak ditemukan, balasan dikirim tanpa kutipan.
Balasan dan reaksi WhatsApp masuk ditautkan ke pesan yang dirujuk di Chatwoot. Tautan dan penekanan Markdown pada balasan agen dikonversi menjadi teks WhatsApp yang mudah dibaca. Daftar, pergantian baris, dan kode dipertahankan. Pemisah tanda tangan yang kosong dihapus. CHATWOOT_SIGN_MSG menambahkan nama agen di awal setelah konversi ini.
Hanya pesan keluar publik dari agen yang memenuhi syarat yang dikirim. Catatan pribadi dan chat yang dikecualikan tidak diteruskan. GOWA menggunakan perangkat dan identitas akun/inbox yang dikonfigurasi untuk merutekan callback bersama. Callback per perangkat menyediakan rute yang tidak ambigu.
Polling dan penghapusan oleh agen
Pada GOWAmain setelah v9.9.0, Chatwoot menyalin pembuatan polling, pengeditan, dan penambahan opsi. Untuk memproses suara individual, berlangganan message pada webhook WhatsApp dan baca data polling terstruktur.
Pada build tersebut, atur CHATWOOT_REVOKE_ON_DELETE=true untuk menyinkronkan penghapusan hanya dari Chatwoot ke WhatsApp. Penghapusan harus cocok dengan tautan persisten ke pesan keluar pada konfigurasi Chatwoot yang aktif. GOWA menarik setiap pesan WhatsApp tertaut, termasuk lampiran yang dikirim terpisah. Dengan CHATWOOT_FORWARD_DELETES=true, penghapusan dari WhatsApp tetap muncul sebagai catatan pribadi. Gunakan CHATWOOT_MESSAGE_DELETE=true untuk menghapus pesan tertaut dalam dua arah.
Impor riwayat
days_limit=3, include_media=true, dan include_groups=true. Sinkronisasi membaca penyimpanan chat lokal GOWA dan berjalan di latar belakang. Setiap perangkat dapat menjalankan satu sinkronisasi pada satu waktu.
Pada GOWA main setelah v9.9.0, sinkronisasi riwayat dapat meminta ponsel mengunggah ulang media yang kedaluwarsa. Ponsel harus online dan masih memiliki file tersebut. Jika ponsel tidak merespons dalam 30 detik, sinkronisasi melewati permintaan unggah ulang berikutnya untuk proses tersebut dan melanjutkan impor pesan. Pesan yang filenya tetap tidak tersedia diimpor tanpa lampiran.
Jalur REST tidak dapat menetapkan timestamp asli; pesan yang diimpor mendapatkan waktu impor. Untuk Chatwoot yang dihosting sendiri, CHATWOOT_IMPORT_DB_URI menulis langsung ke PostgreSQL Chatwoot dan mempertahankan timestamp asli.
Dengan CHATWOOT_REOPEN_CONVERSATION=true pada GOWA main setelah v9.9.0, sinkronisasi riwayat hanya membuka kembali percakapan yang telah diselesaikan jika ada pesan baru untuk diimpor. Sinkronisasi REST membuka kembali percakapan sebelum mengirim pesan dan mencoba ulang chat pada sinkronisasi berikutnya jika pembukaan kembali gagal. Impor PostgreSQL langsung membuka kembali percakapan dalam transaksi yang sama dengan penulisan pesan. Saat pengaturan ini nonaktif, sinkronisasi REST membuat percakapan baru untuk pesan baru, sedangkan impor langsung tetap menggunakan percakapan yang telah diselesaikan.
Pengiriman dan percobaan ulang
Pesan langsung yang mengalami error Chatwoot sementara (error jaringan, HTTP 429, atau 5xx) dimasukkan ke antrean di penyimpanan lokal dan dicoba ulang di latar belakang dengan jeda eksponensial yang dibatasi. Error 4xx lainnya dicatat dan pesannya dibuang.Pemecahan masalah
Jalankan dengan
APP_DEBUG=true dan cari baris log yang diawali Chatwoot: dan Chatwoot Webhook:. Panduan Chatwoot upstream membahas impor database langsung dan aturan pemformatan secara lebih mendalam.