bench get-app https://github.com/Manaa-Soft/openwa_bridge

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=Manaa-Soft%2Fopenwa_bridge)](https://frappegems.com/gems/apps/Manaa-Soft/openwa_bridge)

OpenWA Bridge

Seamlessly bridge frappe_whatsapp with OpenWA for self-hosted WhatsApp messaging.

OpenWA Bridge connects the frappe_whatsapp module with the OpenWA WhatsApp Web API Gateway, allowing your Frappe/ERPNext instance to send and receive WhatsApp messages through your own WhatsApp Web session instead of the Meta Cloud API.

---

Why OpenWA Bridge?

	Meta Cloud API (frappe_whatsapp)	OpenWA Bridge
Setup	Meta Business verification required	Connect with QR code
Cost	Per-message fees	Free (self-hosted)
Number	Dedicated WhatsApp Business number	Any WhatsApp number
Templates	Pre-approved Meta templates only	Send free-form messages + templates
Media	Limited by Meta API	Full media support
Hosting	Cloud-dependent	Fully self-hosted

---

Features

Outbound Messages (Desk -> WhatsApp)

• Text messages with full Unicode support (Arabic, English, etc.)
• Media messages: images, videos, audio, documents
• Sticker messages -- send stickers by URL or base64
• Location sharing with latitude, longitude, and address
• Contact cards sharing
• Poll messages with multiple options
• Reply handling -- reply to specific messages with quoted context
• Reaction messages -- react to messages with emojis
• Template messages -- send approved templates for new contacts
• Bulk messaging -- send text to multiple contacts via OpenWA's send-bulk endpoint
• Message forwarding -- forward messages to other chats
• Message deletion -- delete for self or revoke (delete for everyone)
• Message editing -- edit sent message text via POST /messages/edit
• @mention support -- auto-extracts @NNNN@c.us JIDs from text messages
• Contact management -- check WhatsApp number, block/unblock contacts
• Typing indicators -- auto-send typing indicator before each message (non-blocking)
• Note: OpenWA v0.10.9+ has built-in SIMULATE_TYPING=true (anti-ban). To avoid duplicate typing indicators, set SIMULATE_TYPING=false in OpenWA .env when using the bridge's indicator, or disable the bridge's indicator by commenting out the _send_typing_indicator call in whatsapp_message.py.
• Pairing code authentication -- link via phone number (alternative to QR scan)

Inbound Messages (WhatsApp -> Desk)

• Text message reception with automatic Communication and Lead/Contact creation
• Media downloads -- images, videos, audio, documents stored as Frappe File attachments
• Location reception with GPS coordinates
• Message status tracking -- sent, delivered, read, revoked indicators
• Profile auto-creation for new contacts
• Group message support with author extraction
• @lid JID handling -- supports WhatsApp LID-format sender IDs
• Message edit tracking -- message.edited webhook updates WhatsApp Message body
• Reaction logging -- inbound reactions recorded in logs
• Extended webhook events -- message.sent, message.revoked, message.reaction, message.edited, session.qr, session.authenticated, session.disconnected, session.reconnect_loop, group.join, group.leave, group.update, call.received

Status/Stories

• Post text status -- share text updates as WhatsApp status
• Post image status -- share images as WhatsApp status
• Post video status -- share videos as WhatsApp status
• Read statuses -- list all visible status updates
• Custom styling -- custom background colors and font styles

Group Management

• List groups -- enumerate all groups the session belongs to
• Create groups -- create new WhatsApp groups with participants
• Add/remove participants -- manage group membership
• Promote/demote admins -- manage group admin roles
• Set group name -- update group subject
• Leave groups -- exit a WhatsApp group

WhatsApp Business Labels

• List labels -- enumerate all WhatsApp Business labels
• Add label to chat -- tag chats with labels
• Remove label from chat -- untag chats from labels

Chat Management

• Mark chat as read/unread -- update chat read status
• Chat history -- fetch live chat history from WhatsApp client
• Full-text search -- search messages across all sessions
• Batch messaging -- async batch with progress tracking and cancellation

Profile Management

• Set display name -- update WhatsApp profile name
• Set about text -- update WhatsApp status/about
• Set profile picture -- update WhatsApp profile photo

Call Handling

• Incoming call logging -- log call.received webhook events
• Call rejection -- reject incoming WhatsApp calls

Channels/Newsletters

• List channels -- enumerate subscribed WhatsApp Channels
• Channel messages -- fetch messages from a WhatsApp Channel

Notification System

• Jinja template rendering -- write custom message templates with full Frappe Jinja (e.g., Sales Invoice details, Payment reminders)
• OpenWA template sending -- send synced templates with live doc values resolved at send time
• Dynamic image headers -- automatically render docs as images via Print Formats and send before template text
• Send type control -- choose between Jinja code, Template, or auto-fallback per notification
• Condition-based triggers -- set conditions on when notifications send

Template Management

• Auto-sync -- Frappe templates sync to OpenWA on save (name, body, header, footer)
• Stale ID recovery -- if a template is deleted from the OpenWA dashboard, re-syncing automatically recreates it
• Dynamic header support -- mark a template's header as dynamic and link a Print Format for image generation

Enterprise Reliability

• Async outbox queue -- outbound messages are queued via OpenWA Outbox and processed by background workers, eliminating form submission delays
• Exponential backoff retry -- failed sends retry with 30s, 60s, 120s, 300s backoff (capped at 1h), up to configurable max attempts
• Circuit breaker -- after N consecutive failures (configurable per account), the circuit opens for a cooldown period, preventing cascade failures
• Scheduler safety-net -- hourly sweep catches orphaned outbox entries from worker crashes or Redis restarts
• HMAC-SHA256 webhook verification -- cryptographically verified; configurable strict/lenient mode per account
• Idempotent message handling -- duplicate messages are automatically rejected (configurable TTL)
• Rate limiting -- configurable requests/minute per IP on the inbound webhook endpoint
• Auto-sync webhook secret -- saving a WhatsApp Account auto-syncs the secret to OpenWA webhooks
• Credential encryption -- API keys and secrets stored encrypted in Frappe
• Media size limits -- configurable max inbound media size (default 10MB)
• SSRF protection -- URL validation warns on private/internal IPs
• Role-based access -- whitelisted methods check Frappe permissions

---

Architecture

┌─────────────────────────────────────────────┐
│              Frappe / ERPNext                │
│                                             │
│  ┌──────────────┐  ┌─────────────────────┐  │
│  │  WhatsApp     │  │  OpenWA Bridge      │  │
│  │  DocTypes     │──│  (this app)         │  │
│  │  (Messages,   │  │                     │  │
│  │   Templates,  │  │  Override classes:  │  │
│  │   Notifications)│ │  - WhatsApp Message│  │
│  └──────────────┘  │  - WhatsApp Template│  │
│                    │  - WhatsApp Notif.  │  │
│                    └──────────┬──────────┘  │
│                               │              │
└───────────────────────────────┼──────────────┘
                                │
                          Outbound API
                                │
                                ▼
                    ┌───────────────────────┐
                    │   OpenWA Gateway       │
                    │   (localhost:2785)     │
                    │                       │
                    │  - REST API           │
                    │  - Webhook receiver   │
                    │  - WhatsApp Web conn. │
                    └───────────┬───────────┘
                                │
                          Inbound Webhooks
                                │
                                ▼
                    ┌───────────────────────┐
                    │   WhatsApp Web         │
                    │   (Your phone number)  │
                    └───────────────────────┘

---

Requirements

• Frappe Framework v15+ / ERPNext v15+
• frappe_whatsapp app installed
• OpenWA Gateway running and connected
• A WhatsApp account linked to OpenWA via QR code
• PyMuPDF (for dynamic image headers): bench pip install PyMuPDF
• Dedicated Redis instance for OpenWA (if running on the same server as ERPNext — see Redis Isolation)

---

Installation

1. Install OpenWA Gateway

Follow the OpenWA Production Setup guide for a full production deployment (Docker or Bare Metal), or install quickly:

# Quick install (development)
npm install -g @open-wa/wa-automate
openwa --port 2785

Production — use systemd to keep OpenWA running:

cd ~/OpenWA
npm ci && npm run build

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

[Service]
Type=simple
User=root
WorkingDirectory=/home/your-user/OpenWA
ExecStart=/usr/bin/node dist/main
Restart=always
RestartSec=5
Environment=NODE_ENV=production
Environment=PUPPETEER_ARGS="--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage"

[Install]
WantedBy=multi-user.target
EOF

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

> Critical: The PUPPETEER_ARGS line is required. Without it, Chrome's security sandbox is blocked by systemd and the WhatsApp engine silently freezes with "Engine initialization timed out". See Troubleshooting for details.

See OpenWA Production Setup for PostgreSQL, Docker Compose, Nginx, and HTTPS configuration.

2. Connect your WhatsApp number

# Start OpenWA and scan the QR code with your phone
openwa --port 2785
# Or use the Frappe Desk: WhatsApp Account → Setup OpenWA → Scan QR

3. Install OpenWA Bridge

cd ~/frappe-bench
bench get-app https://github.com/Manaa-Soft/openwa_bridge.git --branch develop
bench --site your-site.local install-app openwa_bridge
bench --site your-site.local migrate
bench restart

4. Install PyMuPDF (optional, for dynamic image headers)

bench pip install PyMuPDF

---

Configuration

Auto-Reconnect (Scheduled Tasks)

The app includes scheduled tasks that automatically manage OpenWA sessions:

• Hourly: Checks all OpenWA accounts — force-kills failed sessions (keeps auth, no QR re-scan), then deletes and recreates as last resort
• Daily: Cleanup of old outbox entries

The scheduler is enabled in hooks.py. Frappe's worker must be running for scheduled tasks to execute:

bench --site erp.manaasoft.com scheduler enable
bench restart

Pre-send check: Before every outbound message, the system verifies the session is ready. If not, it automatically attempts a restart and waits for the session to recover. If recovery fails (e.g., requires QR re-scan), the send is blocked with a clear error message.

Status sync: The WhatsApp Account status field (Active/Inactive) is automatically updated to match the O