Skip to content

Installation

Jump to bottom
Manaa-Soft edited this page Jul 19, 2026 · 7 revisions

Installation Guide

Prerequisites

  • Frappe Framework v15+ / ERPNext v15+
  • frappe_whatsapp app installed and configured
  • Node.js 18+ and npm
  • A server with SSH access (or local machine)

Step 1: Install OpenWA Gateway

Option A: Global Install (Quick)

npm install -g @open-wa/wa-automate
openwa --port 2785

Option B: Local Install (Production Recommended)

cd ~
git clone https://github.com/rmyndharis/OpenWA.git OpenWA
cd OpenWA
npm install
npm run build

Configure OpenWA Environment

Create or edit ~/OpenWA/.env:

AUTO_START_SESSIONS=true
PORT=2785
SSRF_ALLOWED_HOSTS=your-site-name,your-server-ip,localhost,127.0.0.1,minio
# your-site-name = your Frappe/ERPNext site name (e.g., my-site)
# your-server-ip = the IP used to connect from VM to host (e.g., 192.168.1.15)
# minio = MinIO service hostname (if used for file storage)
CORS_ORIGINS=http://192.168.1.15
CSP_UPGRADE_INSECURE_REQUESTS=false

Important: If ~/OpenWA/data/.env.generated exists, delete it — it overrides your .env settings.

rm ~/OpenWA/data/.env.generated

Start with systemd (Production)

systemd keeps OpenWA running across server reboots and auto-restarts on crash:

sudo tee /etc/systemd/system/openwa.service << 'EOF'
[Unit]
Description=OpenWA WhatsApp API
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/home/Manaa-soft/OpenWA
ExecStart=/usr/bin/node dist/main
Restart=always
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable openwa
sudo systemctl restart openwa
sudo systemctl status openwa

Important: If Puppeteer can't find Chrome, change User=root to your username:

sudo sed -i 's/User=root/User=Manaa-soft/' /etc/systemd/system/openwa.service
sudo systemctl daemon-reload
sudo systemctl restart openwa

Boot chain: [VM Boots] → [systemd launches OpenWA] → [sessions auto-start]

Verify OpenWA is Running

curl http://localhost:2785/api/sessions

You should see a JSON response with an empty array or existing sessions.

Step 2: Connect WhatsApp

Option A: QR Code Scan

  1. Open the OpenWA dashboard: http://localhost:2886
  2. Scan the QR code with your phone
  3. Or start manually: cd ~/OpenWA && npm run start

Option B: Pairing Code (Alternative)

If you can't scan QR codes, use pairing code from the Frappe Desk (see Configuration).

Step 3: Get Session Info

# List sessions
curl http://localhost:2785/api/sessions

# Copy the sessionId (UUID) from the response
# Get the API key from the OpenWA dashboard (localhost:2886)

Step 4: Install OpenWA Bridge

Get the App

cd ~/frappe-bench
bench get-app https://github.com/Manaa-Soft/openwa_bridge.git --branch develop

Install on Site

bench --site your-site.local install-app openwa_bridge
bench --site your-site.local migrate
bench restart

Install Optional Dependencies

bench pip install PyMuPDF  # For dynamic image headers

Step 5: Enable Scheduler

The auto-reconnect feature requires the Frappe scheduler:

bench --site your-site.local scheduler enable
bench restart

Step 6: Configure WhatsApp Account

  1. Go to WhatsApp > WhatsApp Account in Frappe Desk
  2. Open your account (or create one)
  3. Check OpenWA Enabled
  4. Fill in:
    • OpenWA Base URL: http://localhost:2785
    • OpenWA API Key: <your-api-key> (from OpenWA dashboard)
    • OpenWA Webhook Secret: <your-shared-secret>
  5. Click Setup OpenWA — this creates a session and displays a QR code
  6. Scan the QR code with your phone

See Configuration for detailed field descriptions.

Step 7: Create Webhook in OpenWA

The webhook auto-syncs when you save the WhatsApp Account. But you can also create it manually:

  • URL: https://your-site.local/api/method/openwa_bridge.inbound.receive_openwa_message
  • Method: POST
  • Events: message.received, message.sent, message.ack, message.failed, message.revoked, message.reaction, session.status, session.qr, session.authenticated, session.disconnected

Full Git Deploy (Updating After Code Changes)

# On server
cd ~/frappe-bench/apps/openwa_bridge

# Discard local changes
git checkout -- .
git clean -fd openwa_bridge/public/

# Pull latest
git pull --no-rebase origin develop

# Migrate + build + restart
bench migrate --site your-site.local
bench build --app openwa_bridge
bench restart

Testing Checklist

After installation, verify each item:

  • OpenWA is running: curl http://localhost:2785/api/sessions
  • WhatsApp Account shows "Connected" in Frappe Desk
  • Send a test text message from Desk → received on phone
  • Send a test image from Desk → received on phone
  • Send a message from phone → appears in Frappe as incoming
  • Create a WhatsApp Template → check "Synced to OpenWA"
  • Configure a notification → submit a doc → message sent

Next Steps

Clone this wiki locally