- Akses API: siapa yang boleh memanggil GOWA. Ini menggunakan HTTP Basic Auth.
- Penautan WhatsApp: menautkan akun WhatsApp ke slot perangkat, seperti saat menautkan WhatsApp Web.
Akses API: Basic Auth
Basic Auth adalah satu-satunya metode autentikasi API. Tidak ada API key atau JWT untuk panggilan REST. Tetapkan satu atau beberapa pasanganuser:password, dipisahkan dengan koma:
APP_HOST=0.0.0.0, menolak dijalankan tanpa kredensial lengkap. Untuk pengembangan lokal tanpa autentikasi, gunakan alamat bind APP_HOST=127.0.0.1.
Jika reverse proxy mengautentikasi setiap pemanggil, APP_ALLOW_UNAUTHENTICATED=true atau --allow-unauthenticated=true secara eksplisit mengizinkan listener non-loopback tanpa Basic Auth. Batasi akses langsung ke listener tersebut.
Kirim kredensial pada setiap permintaan:
401 Unauthorized.
Rute yang tidak dilindungi Basic Auth
Semua rute lainnya, termasuk dasbor di
/, /mcp, dan /ws, memerlukan Basic Auth jika dikonfigurasi.
WebSocket
Browser tidak dapat menetapkan header pada koneksi WebSocket, sehingga/ws menerima kredensial dalam query string:
authorization adalah base64(user:password). Gunakan TLS (wss://) dan samarkan query string dalam log proxy. WebSocket memeriksa origin browser terhadap origin tepercaya yang sama dengan yang digunakan untuk permintaan HTTP pengubah status. Hub WebSocket saat ini menyiarkan peristiwa ke semua socket yang terhubung. Query device_id memilih konteks perangkat untuk koneksi, tetapi tidak mengisolasi pengiriman peristiwa. Gunakan pengenal perangkat pada peristiwa untuk memfilter tampilan dasbor, dan berikan akses API hanya kepada pemanggil yang dipercaya untuk mengakses semua perangkat.
Lihat referensi WebSocket untuk kode peristiwa, payload, dan contoh klien.
CORS
CORS mengizinkan semua origin secara bawaan. Batasi denganAPP_CORS_ALLOWED_ORIGINS=https://ui.example.com (dipisahkan dengan koma). Header permintaan yang diizinkan adalah Origin, Content-Type, Accept, Authorization, dan X-Device-Id.
CORS dan pemeriksaan origin browser merupakan hal terpisah. Origin CORS wildcard tidak memberikan izin untuk permintaan pengubah status atau WebSocket. GOWA mempercayai host permintaan itu sendiri, origin CORS tertentu, APP_TRUSTED_ORIGINS, serta origin yang dikonfigurasi untuk penerbit OAuth dan URL callback Chatwoot. Untuk dasbor terpisah, konfigurasikan origin persisnya:
403 CROSS_SITE_REQUEST_BLOCKED. Ini juga mencakup rute GET yang melakukan login, logout, menghubungkan ulang, atau mereset tautan undangan. Klien seperti curl yang tidak mengirim header origin browser tetap berfungsi.
Origin null tidak pernah dipercaya. Sajikan gowa-ui.html melalui HTTP atau HTTPS alih-alih membukanya sebagai URL file://. Di belakang reverse proxy, pertahankan Host, konfigurasikan proxy tepercaya dengan X-Forwarded-Host, atau cantumkan origin publik dalam APP_TRUSTED_ORIGINS.
Penautan WhatsApp
Setiap akun WhatsApp menempati satu slot perangkat. Buat slot terlebih dahulu, lalu tautkan. Rute di bawah/devices/{device_id} mengambil perangkat dari path. Rute /app/* yang setara menggunakan header X-Device-Id.
Kode QR
qr_link dan pindai dari ponsel: Setelan → Perangkat tertaut → Tautkan perangkat. Minta kode baru setelah qr_duration detik. Dasbor di / menampilkan QR secara langsung dan diperbarui secara real time melalui WebSocket.
Kode penautan
results.pair_code, yaitu kode 8 karakter. Di ponsel, pilih Tautkan dengan nomor telepon saja dan masukkan kode tersebut. phone harus berupa nomor akun yang ditautkan, beserta kode negara.
Passkey
Jika ponsel meminta verifikasi passkey saat login QR, GOWA menyimpan challenge WebAuthn dan menyiarkanPASSKEY_REQUEST melalui WebSocket. Dasbor menangani alur ini. Untuk menjalankannya sendiri:
GET /app/passkeymengembalikan challenge yang menunggu.POST /app/passkey/responsemengirim assertion WebAuthn (formatPublicKeyCredential.toJSON()).- Tunggu
PASSKEY_CONFIRMATION. Saatresult.skip_handoff_uxbernilai true, alur QR aktif mengirim konfirmasi secara otomatis. Jika tidak, bandingkanresult.codedengan kode di ponsel, lalu panggilPOST /app/passkey/confirm.
X-Device-Id pada ketiga panggilan tersebut.
Periksa hasilnya
results.is_connected dan results.is_logged_in sama-sama bernilai true setelah akun tertaut. Sesi disimpan secara persisten di storages/, sehingga penautan ulang tidak diperlukan setelah server dijalankan ulang.
Logout dan menghapus perangkat
Akun yang penautannya diputus dari ponsel (Perangkat tertaut → Keluar) mengalami logout dengan cara yang sama: slot tetap ada dan perlu ditautkan kembali.
Daftar periksa keamanan
- Selalu tetapkan
APP_BASIC_AUTHdengan kata sandi kuat pada layanan apa pun yang dapat diakses melalui jaringan. - Lakukan terminasi TLS pada reverse proxy; kredensial Basic Auth hanya dienkode dengan base64.
- Batasi
APP_CORS_ALLOWED_ORIGINSsaat antarmuka browser memanggil API. - Buat
WHATSAPP_WEBHOOK_SECRETtetap denganopenssl rand -hex 32. Secret kosong atau secret contoh yang dipublikasikan akan diganti dengan kunci acak per proses yang berubah saat server dijalankan ulang. - Perlakukan
storages/sebagai data sensitif. Direktori ini berisi kunci sesi setiap akun tertaut. Berkas SQLite baru menggunakan izin khusus pemilik, dan direktori yang dibuat untuknya menggunakan0700. Lindungi cadangan dengan kehati-hatian yang sama.
