> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrasi Chatwoot

> Salin percakapan WhatsApp ke inbox Chatwoot dan izinkan agen membalas dari Chatwoot.

Saat Chatwoot aktif, GOWA meneruskan pesan WhatsApp (pesan masuk dan pesan keluar yang dikirim dari ponsel) ke inbox **saluran API** Chatwoot, serta mengirim balasan agen dari Chatwoot ke WhatsApp. Teks, gambar, audio, video, dokumen, stiker, lokasi, dan kontak didukung; chat grup ditampilkan sebagai satu percakapan per grup, dengan nama pengirim di awal pesan.

```mermaid theme={null}
flowchart LR
  WA[WhatsApp] -- messages --> G[GOWA]
  G -- Chatwoot REST API --> CW[Chatwoot inbox]
  CW -- webhook /chatwoot/webhook --> G
  G -- agent reply --> WA
```

## 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](#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**

```bash .env theme={null}
CHATWOOT_ENABLED=true
CHATWOOT_URL=https://chatwoot.example.com
CHATWOOT_API_TOKEN=your_user_access_token
CHATWOOT_ACCOUNT_ID=1
CHATWOOT_INBOX_ID=3
CHATWOOT_DEVICE_ID=my-device              # required with more than one device
CHATWOOT_WEBHOOK_SECRET=secret-shown-by-chatwoot
CHATWOOT_WEBHOOK_URL=https://gowa.example.com/chatwoot/webhook
```

Mulai ulang GOWA: rute Chatwoot didaftarkan saat startup.

**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

| Variabel | Default | Deskripsi |
| - | - | - |
| `CHATWOOT_ENABLED` | `false` | Sakelar utama. |
| `CHATWOOT_URL` | — | URL dasar Chatwoot, tanpa garis miring di akhir. |
| `CHATWOOT_API_TOKEN` | — | Token akses API pengguna. |
| `CHATWOOT_ACCOUNT_ID` | — | ID akun numerik. |
| `CHATWOOT_INBOX_ID` | — | ID inbox numerik. Opsional dengan `CHATWOOT_AUTO_CREATE=true`; jika diatur, nilai ini selalu diutamakan. |
| `CHATWOOT_DEVICE_ID` | — | Perangkat (ID slot atau JID) yang mengirim balasan agen. Wajib jika ada lebih dari satu perangkat. |
| `CHATWOOT_WEBHOOK_URL` | — | URL webhook publik GOWA; digunakan saat membuat inbox secara otomatis. |
| `CHATWOOT_WEBHOOK_SECRET` | — | Memverifikasi webhook masuk dari Chatwoot. Secret efektif yang kosong menyebabkan pemanggilan ditolak kecuali pengaturan eksplisit untuk mengizinkan permintaan tanpa tanda tangan diaktifkan. |
| `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED` | `false` | Terima permintaan tanpa secret efektif. Batasi penggunaan ini pada jaringan tepercaya. |
| `CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE` | `5m` | Usia maksimum / selisih waktu jam untuk `X-Chatwoot-Timestamp`. |
| `CHATWOOT_AUTO_CREATE` | `false` | Gunakan kembali atau buat inbox API bernama `CHATWOOT_INBOX_NAME` saat startup. |
| `CHATWOOT_INBOX_NAME` | `WhatsApp` | Nama inbox untuk penyediaan otomatis. |
| `CHATWOOT_IMPORT_MESSAGES` | `false` | Impor riwayat secara otomatis saat perangkat terhubung. |
| `CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES` | `3` | Jumlah hari riwayat yang diimpor. |
| `CHATWOOT_IMPORT_DB_URI` | — | URI PostgreSQL Chatwoot untuk impor riwayat langsung (mempertahankan timestamp asli). |
| `CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE` | `true` | Impor langsung: sisipkan placeholder seperti `[image]` untuk media yang tidak dapat diunduh. |
| `CHATWOOT_IMPORT_MEDIA_WITH_REST` | `false` | Impor langsung: unggah media melalui REST API agar lampiran dibuat. |
| `CHATWOOT_REOPEN_CONVERSATION` | `true` | Buka kembali percakapan yang telah diselesaikan saat kontak mengirim pesan lagi. |
| `CHATWOOT_CONVERSATION_PENDING` | `false` | Buat percakapan baru dengan status `pending`, bukan `open`. |
| `CHATWOOT_IGNORE_JIDS` | — | JID atau wildcard (`@g.us`, `@s.whatsapp.net`, `@lid`) yang dipisahkan koma dan tidak pernah disalin. |
| `CHATWOOT_SIGN_MSG` | `false` | Tambahkan nama agen di awal balasan agen. |
| `CHATWOOT_SIGN_DELIMITER` | `\n\n` | Pemisah antara tanda tangan dan pesan. |
| `CHATWOOT_FORWARD_EDITS` | `true` | Salin pengeditan WhatsApp sebagai catatan pribadi. |
| `CHATWOOT_FORWARD_DELETES` | `true` | Salin tindakan hapus untuk semua orang sebagai catatan pribadi. |
| `CHATWOOT_EVENTS` | Mengikuti `WHATSAPP_WEBHOOK_EVENTS` | Event yang dipisahkan koma untuk diteruskan ke Chatwoot. |
| `CHATWOOT_MESSAGE_READ` | `false` | Sinkronkan status dibaca dalam dua arah. |
| `CHATWOOT_MESSAGE_DELETE` | `false` | Hapus pesan tertaut di sisi lainnya. |
| `CHATWOOT_REVOKE_ON_DELETE` | `false` | Tarik pesan WhatsApp keluar yang tertaut saat agen menghapus pesannya di Chatwoot. |
| `CHATWOOT_ALLOWED_HOSTS` | — | Daftar host yang diizinkan sebagai tujuan `chatwoot_url` per perangkat. |

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](https://gowa-docs.mintlify.site/id/configuration.md).

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:

1. **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.
2. HMAC body pada `X-Hub-Signature-256`.
3. Secret dalam header `X-Chatwoot-Webhook-Secret` atau `X-Gowa-Chatwoot-Secret`.
4. `?secret=` dalam URL webhook, hanya untuk versi Chatwoot yang tidak dapat menandatangani atau menambahkan header. Secret kemudian akan muncul di log akses.

Kegagalan mengembalikan `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

Dengan `CHATWOOT_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):

```bash theme={null}
curl -u admin:changeme -X PUT http://localhost:3000/devices/sales/chatwoot/config \
  -H "Content-Type: application/json" \
  -d '{
    "chatwoot_url": "https://chatwoot.example.com",
    "account_id": 1,
    "inbox_id": 7,
    "api_token": "token-for-this-inbox",
    "webhook_secret": "secret-of-this-api-channel",
    "enabled": true
  }'
```

Respons menyertakan `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`.

> [!WARNING]
>
> Begitu **ada** konfigurasi per perangkat, tujuan `CHATWOOT_*` tidak lagi digunakan sebagai fallback. Pesan dari perangkat tanpa konfigurasi tidak disalin.

* `api_token` disimpan di database GOWA dan disamarkan saat dibaca; `webhook_secret` tidak pernah dikembalikan.
* `chatwoot_url` harus menggunakan HTTP atau HTTPS tanpa kredensial. Tanpa `CHATWOOT_ALLOWED_HOSTS`, alamat privat, loopback, link-local, dan metadata ditolak. Host eksplisit yang cocok dalam `CHATWOOT_ALLOWED_HOSTS` dipercaya 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`, atau `inbox_id` setelah percakapan ditautkan mengembalikan `409`; 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 mencari `in_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 GOWA `main` setelah v9.9.0, Chatwoot menyalin pembuatan polling, pengeditan, dan penambahan opsi. Untuk memproses suara individual, berlangganan `message` pada [webhook WhatsApp](https://gowa-docs.mintlify.site/id/concepts/webhooks.md#album-dan-pesan-terstruktur) 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

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/chatwoot/sync \
  -H "Content-Type: application/json" \
  -d '{"device_id": "my-device", "days_limit": 7, "include_media": true, "include_groups": true}'

curl -u admin:changeme "http://localhost:3000/chatwoot/sync/status?device_id=my-device"
```

Nilai default adalah `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

| Gejala | Pemeriksaan |
| - | - |
| Balasan agen tidak terkirim | `CHATWOOT_DEVICE_ID` sudah diatur dan perangkat sudah login; URL webhook benar dan publik; `DEVICE_NOT_AVAILABLE` dalam log berarti tidak ada perangkat yang dapat digunakan. |
| `401` pada `/chatwoot/webhook` | Secret tidak cocok atau ada penyimpangan waktu jam (lihat di atas). |
| Pesan WhatsApp tidak muncul di Chatwoot | Periksa `CHATWOOT_ENABLED`, token pengguna, ID akun dan inbox, serta konektivitas ke `CHATWOOT_URL`. Pada build yang lebih baru, periksa apakah filter event efektif menyertakan `message`. |
| `CHATWOOT_NOT_CONFIGURED` | URL, token, ID akun, atau ID inbox belum diisi. |

Jalankan dengan `APP_DEBUG=true` dan cari baris log yang diawali `Chatwoot:` dan `Chatwoot Webhook:`. [Panduan Chatwoot](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/chatwoot.md) upstream membahas impor database langsung dan aturan pemformatan secara lebih mendalam.


## Related topics

- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/id/index.md)
- [Referensi Konfigurasi](https://gowa-docs.mintlify.site/id/configuration.md)
- [Ambil metadata server](https://gowa-docs.mintlify.site/id/api-reference/app/ambil-metadata-server.md)
- [Endpoint webhook Chatwoot](https://gowa-docs.mintlify.site/id/api-reference/chatwoot/endpoint-webhook-chatwoot.md)
- [Hapus konfigurasi Chatwoot perangkat](https://gowa-docs.mintlify.site/id/api-reference/chatwoot/hapus-konfigurasi-chatwoot-perangkat.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.