Whatsapp Gateway

bench get-app https://github.com/b0yx/whatsapp_gateway

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=b0yx%2Fwhatsapp_gateway)](https://frappegems.com/gems/apps/b0yx/whatsapp_gateway)

--- ## 🚀 Overview **WhatsApp Gateway** is an open-source Frappe application that connects ERPNext directly to your self-hosted [OpenWA](https://github.com/openwa) WhatsApp API server. Whether you need automated sales order notifications, payment reminders, delivery alerts, or custom CRM messaging, this app enables full WhatsApp automation inside Frappe without costly third-party SaaS middle-men. --- ## ✨ Features - ⚡ **Auto Session Discovery**: Intelligently resolves human-readable session names (e.g., `khalid-main-1`) to internal OpenWA session UUIDs automatically. - 🔒 **Enterprise-Grade Credential Protection**: Native integration with Frappe’s encrypted `__Auth` vault (`get_password`) ensures your OpenWA API keys are never stored or exposed in plaintext. - 📱 **Smart Phone Normalization**: Automatically strips spaces, dashes, leading `+` signs, and formats numbers to the WhatsApp JID standard (`{number}@c.us` or `{group}@g.us`). - 📜 **Full Message Auditing (`WA Message Log`)**: Every outbound message is logged with delivery status (`Sent` or `Failed`), WhatsApp Message IDs, timestamps, and full error logs. - 🔄 **One-Click Retry**: Failed messages can be re-triggered directly from the `WA Message Log` Desk view with a single click. - 🧪 **Desk Connection Diagnostics**: Built-in "Test Connection" button inside `WA Gateway Settings` verifies your server URL, API key, and active session status in real-time. - 🔌 **Developer-Friendly API**: Seamlessly trigger messages from Python hooks, Server Scripts, Client Scripts, or REST APIs. --- ## 🏗 Architecture ```mermaid flowchart LR A["🏢 ERPNext / Frappe
(Sales Order, Invoice, etc.)"] -->|"send_message()"| B["⚙️ WhatsApp Gateway App
(Session Resolver & Formatter)"] B -->|"REST API (X-API-Key)"| C["🐳 OpenWA Server
(Docker / Self-Hosted)"] C -->|"Multi-Device Protocol"| D["📱 WhatsApp Network"] D --> E["👤 Customer / Client"] ``` --- ## 📦 Installation Install this app into your Frappe Bench: ```bash # 1. Navigate to your bench directory cd ~/frappe-bench # 2. Get the app from GitHub bench get-app https://github.com/b0yx/whatsapp_gateway.git # 3. Install it onto your site bench --site your-site.local install-app whatsapp_gateway # 4. Migrate and clear cache bench --site your-site.local migrate bench --site your-site.local clear-cache ``` --- ## ⚙️ Configuration 1. In Frappe Desk, search for **WA Gateway Settings**. 2. Configure the following fields: - **OpenWA Server URL**: E.g., `http://127.0.0.1:2785` or your hosted domain. - **API Key**: The `X-API-Key` configured on your OpenWA server. - **Session Name / ID**: Enter your session name (e.g., `khalid-main-1`) or leave blank to auto-detect the active session. 3. Click the **Test Connection** button in the top bar to verify connectivity. You will see a success badge displaying your active session phone number and engine status! --- ## 💻 Usage & Code Examples ### 1. From Python (Server Scripts / Custom App Hooks) ```python import frappe from whatsapp_gateway.whatsapp_gateway.utils import send_message # Send message to an individual or group response = send_message( receiver="967779280777", message="Hello! Your payment has been received successfully. Thank you!" ) if response.get("status") != "error": frappe.msgprint("WhatsApp message dispatched successfully!") ``` ### 2. ERPNext DocEvent Notification (e.g., Sales Invoice Submission) Add this hook in your custom app's `hooks.py`: ```python doc_events = { "Sales Invoice": { "on_submit": "your_app.notifications.send_invoice_whatsapp" } } ``` Then in `your_app/notifications.py`: ```python import frappe from whatsapp_gateway.whatsapp_gateway.utils import send_message def send_invoice_whatsapp(doc, method): if not doc.contact_mobile: return text = ( f"Hello {doc.customer_name},\n\n" f"Your Invoice *{doc.name}* for *{doc.currency} {doc.grand_total}* " f"has been generated.\n\nThank you for your business!" ) send_message(receiver=doc.contact_mobile, message=text) ``` ### 3. From Client Scripts (JavaScript) ```javascript frappe.ui.form.on("Sales Order", { custom_send_whatsapp(frm) { frappe.call({ method: "whatsapp_gateway.whatsapp_gateway.utils.send_message", args: { receiver: frm.doc.contact_mobile, message: `Hi ${frm.doc.customer_name}, your order #${frm.doc.name} is on its way!` }, freeze: true, freeze_message: __("Sending WhatsApp notification..."), callback(r) { if (r.message && r.message.status !== "error") { frappe.show_alert({ message: __("Message sent!"), indicator: "green" }); } } }); } }); ``` --- ## 🗂 Included DocTypes | DocType | Type | Description | | :--- | :--- | :--- | | **WA Gateway Settings** | Single | Manages server URL, encrypted API key, session discovery, and diagnostics. | | **WA Message Log** | Standard | Audit log capturing receiver, body, delivery status (`Sent` / `Failed`), and error details with retry support. | --- ## 🛠 Prerequisites: Running OpenWA To run OpenWA alongside your bench via Docker: ```bash docker run -d \ --name openwa-api \ -p 127.0.0.1:2785:2785 \ -v ./data:/app/data \ openwa/openwa:latest ``` --- ## 🤝 Contributing Contributions, issues, and feature requests are welcome! 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'feat: Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request --- ## 📝 License Distributed under the **MIT License**. See `LICENSE` for more information. --- ## 👨‍💻 Author **Khalid Alabsi** - **GitHub**: [@b0yx](https://github.com/b0yx) - **Email**: khaled.s.alabsi@gmail.com - **LinkedIn**: [Connect on LinkedIn](https://www.linkedin.com/in/khaled-alabsi)