Skip to content

Home

Jump to bottom
Manaa-Soft edited this page Oct 22, 2026 · 11 revisions

OpenWA Bridge Wiki

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 — no Meta Business verification, no per-message fees.

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 at a Glance

Outbound Messages

Text, images, videos, audio, documents, stickers, locations, contacts, polls, reactions, replies, templates, bulk messaging, message forwarding, message deletion, message editing, @mentions, typing indicators. Scheduled send (openwa_scheduled_at), base64 media payloads, send-as-PDF (render any open document as a PDF via send-document), media-reply workaround (media unquoted + quoted text follow-up), and per-message idempotency keys (Idempotency-Key) so retries never double-send.

Message Actions (v0.19+)

Vote on polls, pin/unpin messages, star messages, download stored message media (get_chat_media)

Status/Stories

Post text, image, video, and voice-note status updates. List visible statuses. Get statuses from a specific contact. Stream stored status media. Delete your own statuses. Webhook events: status.received

Inbound Messages

Text, media downloads, locations, status tracking (sent/delivered/read), per-participant receipts (message.receipt), profile auto-creation, group message support, @lid JID handling, reaction persistence (openwa_reactions), edited message handling, call event logging, kind field discriminator (individual/group/channel/status/broadcast)

Event Log & Reliability

OpenWA Event Log DocType persists non-message webhook events (group.join/leave/update, call.received, status.received, message.reaction, message.receipt, webhook.delivery_failure); daily webhook DLQ check + replay via replay_webhooks()

Groups

List groups, create groups, add/remove participants, promote/demote admins, set group name, leave group, approve/reject pending membership requests (v0.19+). Webhook events: group.join, group.leave, group.update

Labels (Business)

List WhatsApp Business labels, add/remove labels from chats

Call Handling

Reject incoming WhatsApp calls. Webhook events: call.received

Chat Management

Mark chat read/unread (per-message messageIds on v0.23), get live chat history, full-text message search, archive/mute/pin chats, clear chat history, per-session egress proxy (get/set)

Profile Management

Set display name, about text, profile picture

Channels

List WhatsApp Channels, fetch channel messages, subscribe via invite code, unsubscribe from channels, create channels, mute/unmute, demote channel admins, transfer channel ownership (v0.19+)

Message Reactions

Get reactions for a specific message

Batch Management

Cancel running bulk message batches

Global Statistics

Cross-session aggregate stats, message stats with time series (admin-only)

Notification System

Jinja template rendering, OpenWA template sending, dynamic image headers (Print Format → PNG), send type control (Jinja/Template/auto-fallback), condition-based triggers

Enterprise Reliability

Async outbox queue, exponential backoff retry (100 attempts), circuit breaker, scheduler safety-net, HMAC-SHA256 verification, idempotent message handling, rate limiting, auto-sync webhook secret, credential encryption, SSRF protection, role-based access, stale session recovery, pre-send session verification

Wiki Pages

Page Description
Installation Step-by-step setup guide for OpenWA + Frappe app
OpenWA Production Setup Deploy OpenWA Gateway in production (Docker or Bare Metal)
Configuration Account setup, webhook configuration, per-account settings
Architecture System design, override mechanism, credential flow, key decisions
API Reference OpenWA REST endpoints, Frappe whitelisted methods, webhook events
Message Flows Detailed flow diagrams for all message paths
Custom Fields All custom fields across WhatsApp Account, Templates, Notification
Troubleshooting Common issues and their fixes
Changelog Version history and notable changes

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 (optional, for dynamic image headers): bench pip install PyMuPDF

Quick Start

# 1. Install OpenWA Gateway
npm install -g @open-wa/wa-automate
openwa --port 2785

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

# 3. Configure in Desk
# WhatsApp > WhatsApp Account → Check "OpenWA Enabled" → Click "Setup OpenWA"
# Scan QR code with phone → Done!

Architecture Overview

┌─────────────────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│   Frappe / ERPNext      │────▶│   OpenWA Gateway     │────▶│  WhatsApp Web   │
│                         │     │   (localhost:2785)   │     │  (Your Phone)   │
│  openwa_bridge app      │◀────│   REST API + Webhooks│◀────│                 │
│  (Override Classes)     │     │                      │     │                 │
└─────────────────────────┘     └──────────────────────┘     └─────────────────┘

Source Code

Clone this wiki locally