Sesi Provider WAHA

WAHA adalah provider WhatsApp untuk workspace. Satu workspace dapat mengelola banyak nomor WhatsApp: setiap nomor direpresentasikan oleh satu WAHA session dan diarahkan ke satu inbox. Owner harus menyelesaikan konfigurasi, mengikat setiap session ke inbox yang benar, lalu membuktikan outbound dan inbound sebelum dipakai untuk percakapan nyata.

Tujuan

Satu atau lebih WAHA session terhubung ke workspace dan inbox yang benar, terautentikasi melalui QR bila diperlukan, dan memiliki hasil delivery yang dapat diverifikasi.

Untuk siapa

Workspace owner yang mengelola pengaturan integrasi.

Prasyarat

• Sudah masuk ke workspace yang benar sebagai owner.
• Siapkan Base URL WAHA yang dapat dijangkau API, API key, dan webhook secret. Jangan menaruh nilai rahasia di artikel, tiket, chat, atau screenshot.
• Inbox WhatsApp tujuan sudah ada, atau siapkan nama untuk inbox baru.

Model multi-session dalam satu workspace

Istilah dan relasinya adalah sebagai berikut:

Workspace / tenant (database: accounts)
├── Provider connection WAHA (database: account_waha_settings)
│   ├── Base URL
│   ├── API key terenkripsi
│   └── Webhook secret terenkripsi
├── Inbox Helpdesk ─── WAHA session HELP-DESK ─── nomor WhatsApp A
├── Inbox Sales ────── WAHA session SALES ─────── nomor WhatsApp B
└── Inbox Marketing ─ WAHA session MARKETING ─── nomor WhatsApp C

Kontrak yang berlaku:

• Satu workspace memiliki satu konfigurasi koneksi WAHA dan dapat memiliki banyak WAHA session.
• Satu WAHA session mewakili satu nomor/koneksi WhatsApp dan diikat ke tepat satu inbox dalam workspace.
• Satu inbox WhatsApp memakai tepat satu WAHA session. Buat inbox terpisah jika nomor, fungsi, team, SLA, atau akses agent berbeda.
• Pesan inbound dirutekan berdasarkan session ke inbox terikat. Pesan outbound dari percakapan memakai session milik inbox tersebut.
• User dan team hanya melihat inbox yang diberikan kepadanya; memiliki akses ke workspace tidak otomatis memberi akses ke seluruh inbox.
• Credential WAHA, inbox, kontak, percakapan, pesan, dan binding session selalu berada dalam batas workspace (account_id).

Contoh yang dianjurkan untuk kebutuhan tiga nomor:

Fungsi	Inbox	WAHA session	Akses umum
Layanan pelanggan	Helpdesk	helpdesk	Support agent dan supervisor
Penjualan	Sales	sales	Sales agent dan sales lead
Kampanye/engagement	Marketing	marketing	Marketing team

Nama di atas hanya contoh. Session yang dibuat melalui Custelio diberi identitas workspace pada nama fisiknya agar routing inbound tidak ambigu.

Batas tenant: satu session WAHA tidak boleh diikat ke dua workspace. Berbagi satu session di antara banyak user/team dalam workspace yang sama didukung melalui akses inbox. Berbagi session lintas-workspace belum didukung karena akan membuat kepemilikan, HMAC, routing inbound, audit, dan hak akses data menjadi ambigu.

Alur setup WAHA Provider

1. Buka Settings → WAHA settings sebagai owner.
2. Isi Base URL, API key, dan Webhook secret. Gunakan Generate secret bila organisasi belum memiliki secret, simpan nilainya di secret manager, lalu pilih Save settings.
3. Setelah tersimpan, field API key dan Webhook secret tetap kosong/masked. Kosong berarti mempertahankan secret tersimpan, bukan menghapusnya.
4. Pada WhatsApp sessions, pilih Add session.
5. Pilih Create WAHA session untuk nomor baru, atau Connect existing WAHA session untuk session yang tersedia melalui API key workspace. Ulangi langkah ini untuk setiap nomor yang dibutuhkan workspace.
6. Pada Inbox, pilih inbox WhatsApp yang ada atau biarkan Create a new WhatsApp inbox, lalu isi New inbox name.
7. Untuk session baru, masukkan WAHA session name yang singkat dan menunjukkan fungsi, misalnya helpdesk, sales, atau marketing. Untuk session existing, pilih WAHA session dari daftar, lalu pilih Connect session atau Create session sesuai mode.
8. Jika QR muncul, buka WhatsApp pada perangkat: Settings → Linked devices → Link a device, lalu pindai QR. Jangan membagikan QR atau payload-nya.
9. Tunggu status sesi WORKING, running, atau connected dan pastikan baris sesi menunjukkan Connected inbox. Jika belum terikat, gunakan Bind inbox atau Change inbox.
10. Pilih Test send, gunakan nomor uji yang menyetujui pengujian, isi pesan, lalu minta penerima uji mengonfirmasi bahwa pesan benar-benar diterima. UI hanya menampilkan “Test message sent”; keberhasilan UI saja bukan bukti delivery.
11. Kirim pesan dari nomor uji ke nomor WhatsApp yang terhubung. Pastikan percakapan inbound masuk ke inbox yang dipilih.

Keamanan: API key, webhook secret, dan QR memberi akses ke koneksi WhatsApp. Jangan masukkan nilainya ke tiket, chat, screenshot publik, atau dokumentasi. Ganti secret bila terpapar.

Verifikasi: Status sesi terhubung dan pesan “Test message sent” hanya membuktikan koneksi atau permintaan berhasil. Setup selesai setelah penerima uji mengonfirmasi pesan outbound diterima dan pesan inbound masuk ke inbox yang benar.

Memutus session dari Custelio

Pada Settings → WAHA settings, pilih aksi sesuai hasil yang diinginkan:

• Change inbox: memindahkan routing session ke inbox lain dalam workspace yang sama. Nomor tetap login dan pesan berikutnya masuk ke inbox baru.
• Unbind: menghapus routing session dari Custelio tanpa logout dari WhatsApp. Session tetap hidup di WAHA, tetapi Custelio tidak lagi menerima atau mengirim percakapan melalui binding tersebut sampai session diikat kembali.
• Logout & delete: meminta WAHA logout dan menghapus session, lalu menghapus binding Custelio. Nomor harus ditautkan kembali menggunakan QR sebelum dapat digunakan lagi.

Unbind maupun logout tidak menghapus kontak, percakapan, atau pesan historis di workspace. Penghapusan data historis merupakan operasi tata kelola yang terpisah.

Peringatan: gunakan Unbind bila hanya ingin mengganti routing atau menghentikan pemakaian sementara. Gunakan Logout & delete hanya ketika benar-benar ingin memutus perangkat WhatsApp dari WAHA.

Tanda berhasil

• WAHA settings tersimpan dan indikator API key serta Webhook secret menunjukkan Configured.
• WhatsApp sessions menampilkan status WORKING, running, atau connected.
• Routing menampilkan nama inbox dan Connected inbox, bukan Not bound.
• Penerima nomor uji mengonfirmasi pesan outbound diterima; status sukses di UI saja tidak cukup.
• Pesan balasan dari nomor uji muncul sebagai percakapan inbound di inbox tersebut.
• Jika workspace memiliki beberapa session, setiap nomor uji masuk ke inboxnya sendiri dan tidak berpindah ke inbox lain.

Troubleshooting berdasarkan UI

Gejala di UI	Pemeriksaan aman pertama	Tindakan berikutnya
Add session nonaktif atau muncul “Save API key and webhook secret before adding a session.”	Kembali ke WAHA settings; pastikan indikator API key dan Webhook secret Configured setelah Save settings.	Pastikan Base URL, API key, dan webhook secret benar; simpan ulang tanpa mengosongkan field yang ingin dipertahankan.
Daftar WAHA session pada Connect existing WAHA session kosong.	Periksa Base URL dan keterjangkauan API WAHA dengan API key workspace yang tersimpan.	Pastikan sesi memang ada pada provider tersebut; jangan membuat ulang sesi existing secara sembarang.
QR kedaluwarsa atau pemindaian gagal.	Pilih Done, tutup dialog, lalu buka kembali Add session atau Bind inbox. Pilih sesi/inbox dan kirim ulang koneksi untuk mengambil QR baru; pastikan perangkat memakai Settings → Linked devices → Link a device.	Jangan gunakan QR lama atau membagikannya; pindai QR baru dan periksa health provider bila gagal lagi.
Status connected tetapi routing menampilkan Not bound.	Periksa inbox yang dipilih pada dialog dan status binding sesi.	Buka baris sesi, pilih Bind inbox atau Change inbox, pilih inbox yang benar, lalu verifikasi Connected inbox.
Test send gagal atau penerima tidak menerima pesan.	Periksa status sesi/provider health; UI “Test message sent” hanya mengonfirmasi permintaan, bukan receipt.	Periksa Base URL/API key reachability, nomor uji yang menyetujui, webhook/dispatcher, minta penerima mengonfirmasi receipt, lalu ulangi setelah penyebab diperbaiki.
Pesan inbound tidak muncul di inbox.	Pastikan sesi terikat ke inbox yang dipilih dan provider health tetap aktif.	Periksa konfigurasi webhook secret serta penerimaan webhook; jangan mengklaim pesan diterima sebelum event inbound terlihat.
Dashboard hanya menampilkan satu session padahal workspace memiliki beberapa session.	Buka Settings → WAHA settings dan periksa seluruh baris session serta inbox routing.	Ringkasan dashboard saat ini dapat menampilkan satu health entry; daftar session pada settings adalah rujukan operasional untuk binding multi-session.

Batasan dan invariants delivery

• Jangan menganggap status connected atau “Test message sent” sebagai bukti pesan terkirim atau diterima; minta penerima uji mengonfirmasi receipt.
• Jangan menghapus secret dengan mengosongkan field; field kosong mempertahankan nilai tersimpan. Ganti secret hanya melalui input baru yang aman.
• QR bersifat kredensial koneksi; perlakukan sebagai rahasia sekali pakai.
• Hentikan pengiriman bila sesi logout, disconnected, atau health provider gagal. Autentikasi ulang lewat QR dan verifikasi binding sebelum melanjutkan.
• Endpoint dan payload mengikuti OpenAPI runtime; halaman ini mendokumentasikan alur UI WAHA Provider, bukan kontrak API.
• Satu session lintas-workspace tidak didukung. Gunakan credential/session terpisah per workspace; jangan mendaftarkan nama session fisik yang sama pada dua workspace.

Tugas terkait

• Pengguna, Peran, Tim, dan Inbox
• Storage dan Platform