Panduan Instalasi • DjB MultiWA

Baca sebelum upload: aplikasi terdiri dari dashboard PHP/MySQL dan gateway Node.js/Chromium. Hosting cPanel yang hanya mendukung PHP tidak cukup untuk mesin koneksi WhatsApp. Dashboard tetap dapat di cPanel; gateway dapat dipasang pada VPS terpisah. Paket ini belum diinstal pada hosting Anda dan belum diuji dengan nomor WhatsApp asli.

1. Fitur yang disiapkan

Percakapan

Hingga 8 slot nomor, tampilan fokus/2/4/8 panel, chat pribadi, balasan grup, kutip pesan, gambar, dokumen, lihat/unduh media, dan chat ke nomor baru.

Akses tim

Admin dan anggota, akses semua nomor atau nomor tertentu, tanda tangan username otomatis, ubah password, penonaktifan user, dan log aktivitas.

Contoh pesan yang diterima pelanggan:

Selamat pagi, kami bantu cek jaringan Bapak.

— darwin

Tanda tangan disisipkan oleh server setiap kali mengirim melalui dashboard. Username tidak bisa diganti lewat isian browser. Untuk gambar/dokumen, tanda tangan berada di caption. Audio dikirim sebagai dokumen agar memiliki caption.

Ini adalah inbox tim khusus berbasis whatsapp-web.js, bukan tampilan asli web.whatsapp.com di dalam delapan iframe. Integrasi tidak resmi dapat terganggu akibat perubahan WhatsApp dan berisiko pembatasan akun. Tidak ada jaminan seluruh fitur WhatsApp Web.

Tersedia	Batas versi 1.0
Chat, grup, balasan kutipan, gambar, dokumen, pratinjau dan unduh media	Lampiran maksimal 16 MiB. Video/ audio bergantung format dan codec. Tidak ada perekam voice note.
Riwayat dari sesi WhatsApp Web	60 pesan awal; muat lebih lama hingga 500 per percakapan. Bergantung sinkronisasi; bukan arsip lengkap semua chat lama.
Update chat saat dashboard terbuka	Polling sekitar 5 detik, bukan push notification aplikasi mobile.
Hak akses per nomor	Semua kontak dan grup pada nomor yang diberikan dapat diakses. Belum ada pembatasan per kontak.
Signature pada pesan dari dashboard	Pesan dari ponsel/perangkat lain tidak otomatis diberi signature.
Nomor yang sudah ditautkan	Panggilan, status, broadcast, pengelolaan anggota grup, edit/hapus pesan dan ekspor arsip lengkap belum tersedia.

2. Pilih tempat menjalankan gateway

Kondisi hosting	Penempatan
cPanel hanya PHP/MySQL	Dashboard di cPanel, gateway di VPS Linux dengan HTTPS.
cPanel menyediakan Node.js tetapi membatasi browser/proses latar belakang	Tetap gunakan VPS untuk gateway. Menu Node.js saja belum menjamin kompatibilitas.
cPanel mengizinkan Node.js 22.12+, Chromium, proses selalu aktif, disk persisten, RAM/CPU cukup	Gateway dapat dipasang pada server cPanel yang sama dengan bantuan provider. Satu proses gateway saja.

Pertanyaan untuk provider hosting:

Apakah Node.js 22.12 atau lebih baru, Terminal/SSH, dan npm ci tersedia?
Apakah Chromium/Puppeteer beserta dependency Linux dan sandbox dapat dijalankan?
Apakah proses gateway boleh hidup terus tanpa idle shutdown, serta hanya satu instance?
Berapa limit RAM, CPU, proses, PHP workers dan request timeout? Apakah 8 profil browser diizinkan?
Apakah koneksi keluar HTTPS ke WhatsApp, npm dan unduhan browser diizinkan?

Perkiraan awal kapasitas VPS: 4 vCPU / RAM 8 GB / SSD 40 GB untuk memulai evaluasi 8 sesi. Ini perkiraan teknik, bukan kebutuhan baku atau hasil benchmark. Beban chat, media dan jumlah user dapat memerlukan lebih besar. Uji terlebih dahulu dengan 1–2 nomor lalu tingkatkan sambil memantau RAM/CPU.

3. Kebutuhan teknis

Dashboard cPanel	Gateway
PHP 8.2+; ekstensi PDO MySQL, cURL, mbstring, fileinfo dan sessions; MySQL 8 atau MariaDB 10.6+; HTTPS; InnoDB dan utf8mb4.	Node.js 22.12+; npm; Chromium/Puppeteer; dependency Linux untuk browser; user OS biasa; disk yang persisten; proses tunggal berkelanjutan; HTTPS reverse proxy jika berbeda server.
Upload 16M, post_max_size 20M, memory_limit 256M, max_execution_time 100. File `.user.ini` disediakan; periksa provider apakah nilai diizinkan.	Request JSON 24 MB, upload media 16 MiB, timeout reverse proxy minimal 100 detik. Jangan membuka port gateway langsung ke internet tanpa TLS dan token.

4. Pasang dashboard di cPanel

Buat subdomain, misalnya wa.domainanda.com, lalu aktifkan SSL/HTTPS.
Buat database dan user lewat MySQL Database Wizard. Beri user database hak untuk database aplikasi tersebut saja. Catat nama lengkap berprefiks cPanel.
Upload dan ekstrak paket di folder privat, misalnya /home/CPANELUSER/apps/DjB_MultiWA_cPanel. Jangan menaruh seluruh ZIP di document root publik.
Arahkan document root subdomain ke /home/CPANELUSER/apps/DjB_MultiWA_cPanel/cpanel/public. Hanya isi folder public yang boleh diakses web.
Salin cpanel/app/config.example.php menjadi cpanel/app/config.php. Isi database, URL gateway HTTPS, gateway_token dan install_token. Jangan menonaktifkan require_https pada server publik.
Buat dua token berbeda. Jalankan perintah ini dua kali di Terminal; satu untuk gateway dan satu untuk instalasi:

openssl rand -hex 32

Alternatif jika OpenSSL CLI tidak tersedia:

php -r 'echo bin2hex(random_bytes(32)), PHP_EOL;'

Atur file config hanya bisa dibaca user hosting dan proses PHP yang semestinya, umumnya mode 600 jika PHP berjalan sebagai user akun. Jangan gunakan 777.
Buka https://wa.domainanda.com/install.php. Masukkan token instalasi, username admin, dan password minimal 12 karakter. Installer membuat tabel dan akun admin pertama.
Setelah berhasil, hapus install.php lalu kosongkan install_token di config. Tidak ada username/password bawaan.
Masuk ke halaman utama. Dashboard dapat terbuka meskipun gateway belum siap; statusnya menunjukkan gateway belum tersambung.

Jika document root harus berada di public_html

Tetap simpan app dan database di folder privat. Salin isi cpanel/public ke document root yang diizinkan, misalnya /home/CPANELUSER/public_html/multiwa. Tambahkan pada .htaccess di folder publik:

SetEnv MULTIWA_BOOTSTRAP /home/CPANELUSER/apps/DjB_MultiWA_cPanel/cpanel/app/bootstrap.php

Ganti path sesuai akun. Apabila SetEnv tidak diizinkan provider, ubah baris require paling atas di api.php dan install.php menjadi path absolut ke app/bootstrap.php privat. Bootstrap otomatis menemukan config dan skema database di struktur privat.

5. Pasang gateway di VPS / server pendukung

Bagian ini dilakukan oleh pengelola server. Node.js 22.12+ dan dependency Linux Chromium harus tersedia terlebih dahulu. Jalankan gateway sebagai user biasa, bukan root. Folder gateway dan data tidak boleh menjadi direktori web.

Salin folder gateway ke server, misalnya /opt/multiwa/gateway, dengan kepemilikan user service.
Salin .env.example menjadi .env. Isi GATEWAY_TOKEN sama persis dengan config PHP; gunakan DATA_DIR yang persisten. HOST=127.0.0.1 membatasi akses langsung ke server lokal.
Instal dependency dari lockfile:

cd /opt/multiwa/gateway
npm ci
npx puppeteer browsers install chrome
npm test
node app.js

Jika memakai Chrome/Chromium yang telah disediakan provider, isi CHROME_PATH dengan path executable yang kompatibel. Instalasi browser memerlukan dependency Linux yang sesuai distribusi; panduan resminya ada di bagian referensi. Mode sandbox aktif secara default. CHROME_NO_SANDBOX=1 hanya untuk lingkungan container terisolasi yang memang membutuhkan dan dikelola administrator, bukan setelan umum.

Buat hostname gateway, misalnya wa-gateway.domainanda.com. Pasang reverse proxy HTTPS menuju 127.0.0.1:3100. Contoh Nginx ada pada gateway/nginx.example.conf; sesuaikan sertifikat TLS dan hostname sebelum digunakan.
Masukkan URL HTTPS tersebut ke gateway_url config PHP. Bila gateway dan PHP benar-benar di host yang sama, http://127.0.0.1:3100 diizinkan untuk koneksi lokal.
Jika memungkinkan, batasi reverse proxy gateway hanya untuk IP keluar server cPanel. Token rahasia tetap wajib. Browser user tidak menerima token gateway.
Atur proses selalu hidup menggunakan salah satu: systemd, PM2, atau Application Manager provider. Jangan menjalankan lebih dari satu metode bersamaan.

Contoh PM2

pm2 start ecosystem.config.cjs
pm2 save
pm2 startup

PM2 harus telah terpasang; ikuti perintah startup yang ditampilkan sesuai OS. Konfigurasi sudah memakai satu instance dalam mode fork. Jangan mengganti ke cluster. Contoh systemd tersedia sebagai gateway/multiwa.service.example; ganti user dan path.

Jika gateway dipasang lewat cPanel Application Manager

Pilih application root folder gateway, Node.js 22.12+, startup file app.js, environment production. Jalankan instalasi npm. Minta provider memastikan Chromium dapat berjalan, satu proses saja, tidak dimatikan saat idle, storage persisten, serta reverse proxy request/body/timeout sesuai. Berbeda provider dapat berbeda konfigurasi Passenger; bila tidak dapat dipenuhi, gunakan gateway VPS.

6. Hubungkan nomor dan atur user

Masuk sebagai admin → Nomor WhatsApp → Atur untuk memberi label slot, misalnya DjB CS atau NOC.
Klik QR / Sambungkan. Di ponsel buka WhatsApp → Perangkat tertaut → Tautkan perangkat, lalu scan QR. Tunggu status Terhubung.
Periksa nomor aktual yang ditampilkan. Ulangi untuk nomor lain sampai delapan. Jangan gunakan nomor yang sama pada dua slot.
Buka User & akses → Tambah user. Pilih Anggota tim; centang semua nomor atau nomor tertentu. Admin selalu dapat mengakses semua nomor dan pengaturan.
Masuk menggunakan akun anggota. Verifikasi daftar nomor sesuai otoritasnya, termasuk lampiran dan grup.
Menu Percakapan menyediakan Fokus, 2, 4 dan 8 panel. Pada panel ringkas, pilih percakapan dari dropdown. Di layar sempit panel disusun vertikal agar tetap dapat digunakan.

Isi pesan lalu Enter untuk kirim, Shift+Enter untuk baris baru. Tombol + di kotak pencarian membuka chat baru. Tombol + di composer untuk lampiran. Klik Balas pada pesan untuk mengutip. Klik gambar untuk pratinjau, atau gunakan tautan unduh. Penanda terkirim/diterima/dibaca bergantung ACK WhatsApp.

7. Saat terjadi masalah

Gejala	Pemeriksaan
Gateway belum tersambung	Service Node hidup; URL, DNS, TLS dan token cocok; IP cPanel tidak diblokir; gunakan URL tanpa path tambahan.
QR tidak muncul / status perlu disambungkan	Periksa log gateway, dependency Chromium, sandbox, RAM, akses internet dan folder LocalAuth. Tutup dialog lalu sambungkan ulang. Jika gagal autentikasi, putuskan dan scan ulang.
Node Application Manager tidak ada	Hubungi provider. Fitur ini dapat dinonaktifkan; jangan menganggap shared hosting mendukung Chromium.
HTTP 500	Periksa error_log PHP, ekstensi PDO/cURL/mbstring/fileinfo, database, config dan izin folder. Kredensial tidak ditampilkan ke browser.
Upload gagal	Batas 16 MiB; cek .user.ini, MultiPHP INI Editor, post_max_size 20M, upload_max_filesize 16M, memory 256M, reverse proxy body 24m, timeout 100 detik. Provider dapat menerapkan batas lebih rendah.
Media lama tidak dapat dibuka	Media mungkin belum tersinkron atau tidak tersedia lagi pada WhatsApp. Coba pesan baru; aplikasi bukan arsip media lengkap.
Status pengiriman belum pasti	Gunakan Periksa status dan lihat riwayat chat. Jangan langsung kirim ulang. Aplikasi menahan retry otomatis untuk mengurangi duplikasi. Setelah dicek, form dapat dikosongkan tanpa mengirim.
Nomor/user tidak tampil atau diminta login ulang	Periksa slot aktif dan izin. Perubahan user membatalkan sesi lamanya. Login kembali dengan otoritas terbaru.
Gateway berhenti setelah tidak diakses	Provider harus menyediakan proses selalu aktif. Cron yang hanya memanggil URL tidak menggantikan izin proses persisten/Chromium.
File lock gateway.pid tertinggal	Pastikan tidak ada gateway dengan DATA_DIR yang sama. Sistem otomatis membersihkan PID tidak aktif; jangan menghapus lock saat gateway lain masih hidup.

8. Backup dan verifikasi akhir

Backup database, config.php, .env dan gateway/data secara terenkripsi. Hentikan gateway sebelum menyalin profil browser untuk konsistensi. Batasi akses folder sesi karena dapat memberi akses ke akun WhatsApp. Tentukan retensi log dan data sesuai kebutuhan perusahaan.

Buka docs/CHECKLIST_AKTIVASI.md untuk uji pada nomor asli. Ringkasan pengujian pengembangan ada di docs/HASIL_PENGUJIAN.md: 46 pemeriksaan integrasi, 7 unit test gateway dan 8 pemeriksaan DOM. Pengujian memakai transport WhatsApp simulasi; belum membuktikan kompatibilitas WhatsApp dan hosting produksi.

Delapan nomor.
Satu dashboard untuk tim.