WAHA / WhatsApp Gateway

Tutorial Admin Bot WhatsApp

Panduan Indonesia dan English untuk login, connect WAHA, membuat bot/menu/helpdesk, dan mengirim pesan dari Laravel.

Back to AdminIndonesiaEnglishAPI Keys

Current Deployment Status

This gateway is a Node.js/Express admin and API layer that talks to your existing WAHA service.

  • Admin GUI: /admin
  • Public health check: /health
  • WAHA webhook URL: /webhook/waha
  • External send API: POST /api/send
  • External blast API: POST /api/blast
Important: This gateway is not WAHA itself. It connects to WAHA using WAHA_BASE_URL and optional WAHA_API_KEY configured in the gateway .env.

API Key Difference / Perbedaan API Key

KeyWhere it is usedWho should know it
ADMIN_API_KEYTyped into the Admin GUI login box. Used for admin actions: bots, menus, helpdesk groups, WAHA session helpers, ticket management.Only trusted admins.
EXTERNAL_API_KEYSUsed by Laravel/other apps in X-Api-Key header to send messages/reminders/blasts through this gateway.Each connected project/app.
WAHA_API_KEYUsed internally by this gateway when calling WAHA. Do not type this in the Admin GUI unless it is intentionally the same value.Server/gateway only.
Answer: In the Admin API Key field, input ADMIN_API_KEY from this bot gateway's .env, not the WAHA reverse proxy/API key. The WAHA key belongs in WAHA_API_KEY inside .env.

Panduan Indonesia

1. Login Admin

  1. Buka https://domain-bot-anda/admin.
  2. Masukkan nilai ADMIN_API_KEY dari file .env gateway ini.
  3. Klik Save & Load.

2. Connect nomor WhatsApp

  1. Pastikan WAHA hidup dan WAHA_BASE_URL benar, misalnya http://127.0.0.1:3000.
  2. Isi Session Name, misalnya default.
  3. Klik Create/Start WAHA Session.
  4. Klik Get QR.
  5. Scan QR dari WhatsApp yang akan dijadikan bot.

3. Atur Bot Settings

  1. Isi Name, misalnya Customer Service Bot.
  2. Isi WAHA Session sesuai session WAHA, misalnya default.
  3. Centang Bot enabled.
  4. Isi Trigger Keyword, misalnya menu.
  5. Klik Save Bot.

4. Buat menu dan response

  1. Pada bagian Bot Menu / Responses, pilih bot.
  2. Isi keyword, contoh menu, 1, 2, status.
  3. Isi response yang akan dibalas otomatis.
  4. Jika menu harus diteruskan ke grup helpdesk, pilih helpdesk group.
  5. Klik Save Menu.

5. Helpdesk group

  1. Buat helpdesk group lokal untuk mapping menu ke grup admin.
  2. Isi Group Chat ID jika grup sudah ada.
  3. Atau isi participants dan coba create group melalui WAHA jika versi WAHA mendukung endpoint tersebut.

English Guide

1. Admin login

  1. Open https://your-bot-domain/admin.
  2. Enter the gateway ADMIN_API_KEY from this app's .env.
  3. Click Save & Load.

2. Connect a WhatsApp number

  1. Make sure WAHA is running and WAHA_BASE_URL is correct.
  2. Enter the session name, for example default.
  3. Click Create/Start WAHA Session.
  4. Click Get QR.
  5. Scan the QR using the WhatsApp number that will become the bot.

3. Configure bot behavior

  1. Set the bot name and WAHA session.
  2. Enable the bot.
  3. Set a trigger keyword such as menu.
  4. Set fallback response.
  5. Save the bot.

4. Configure menu responses

  1. Create keywords such as menu, 1, 2, or status.
  2. Write the auto-reply response.
  3. Optionally map the menu to a helpdesk group.
  4. Save and test from another WhatsApp account.

QR Multi Session / Banyak Nomor WhatsApp

Indonesia: Untuk membuat nomor berbeda menjadi bot, gunakan Session Name berbeda. Contoh: default, cs-main, hris-reminder, pos-alert. Klik Create/Start WAHA Session, lalu Get QR. QR akan tampil langsung di halaman admin jika WAHA mengembalikan image/base64/SVG yang bisa dirender.
English: To connect multiple WhatsApp numbers, use a different WAHA session name for each number. Click Create/Start WAHA Session, then Get QR. Scan it from WhatsApp > Linked Devices.
  1. Create/start one session name per WhatsApp number.
  2. Scan the QR from the phone that will become the bot number.
  3. Create a Bot Settings record mapped to that WAHA session.
  4. Use that session name from Laravel when sending notifications.

Sending Safety, Queue, Quota & Anti-Spam Guard

Indonesia: Ini bukan quota resmi WhatsApp. Ini adalah limit internal agar gateway tidak mengirim terlalu cepat atau terlalu banyak.

English: This is not an official WhatsApp quota. It is an internal protection layer to reduce risky sending patterns.

  • Daily/hourly/minute limit: batasi jumlah pesan keluar.
  • Random delay: beri jarak antar pesan.
  • Max batch size: batasi jumlah penerima blast per batch.
  • Quiet hours: tahan pesan non-transactional pada jam malam.
  • Duplicate guard: cegah pesan sama persis ke nomor yang sama dalam waktu pendek.
  • Opt-in/blacklist: tandai nomor yang boleh/tidak boleh dikirimi pesan.
  • Emergency pause: hentikan semua pengiriman sementara.

Laravel projects should call /api/send or /api/blast. The gateway will queue and process safely.

Laravel / External Project Integration

Use one value from EXTERNAL_API_KEYS as the X-Api-Key header.

curl -X POST https://your-bot-domain/api/send \ -H "Content-Type: application/json" \ -H "X-Api-Key: your-project-key" \ -d '{"session":"default","to":"6281234567890","message":"Test message","category":"transactional"}'

Laravel example:

Http::withHeaders([ 'X-Api-Key' => config('services.whatsapp_gateway.key'), ])->post(config('services.whatsapp_gateway.url') . '/api/send', [ 'session' => 'default', 'to' => '6281234567890', 'message' => 'Halo dari Laravel', 'category' => 'transactional', ]);

Troubleshooting

  • Unauthorized in Admin: use ADMIN_API_KEY, not WAHA_API_KEY.
  • Health works locally but domain fails: check CloudPanel reverse proxy URL http://127.0.0.1:3100, DNS, and SSL.
  • WAHA session fails: check curl http://127.0.0.1:3000/api/sessions from the VPS.
  • Message send fails: ensure WhatsApp session is connected/scanned and the phone format starts with country code, for example 628....
  • App stops after reboot: run pm2 save and pm2 startup.