Integrating WhatsApp with ERPNext 15 using the open-source Evolution API and the frappe_whatsapp app allows you to establish a cost-effective communication system without relying on official APIs. Below is a comprehensive guide to set up this integration in a self-hosted environment.
Prerequisites
- A self-hosted ERPNext 15 instance
- Linux-based server (e.g., Ubuntu 20.04+)
- Node.js (v16 or higher) and npm installed
- MongoDB and Redis installed
- Optional: Cloudflare Tunnel for secure remote access
1. 
Install Evolution API
a. Clone the Repository
git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api
b. Install Dependencies
npm install
c. Configure Environment Variables
Create a .env file in the root directory with the following content:
PORT=3000
MONGODB_URI=mongodb://localhost:27017/evolutionapi
REDIS_URI=redis://localhost:6379
d. Start the Server
npm run start
The Evolution API should now be running on http://localhost:3000.
2. 
Install frappe_whatsapp App in ERPNext
a. Get the App
cd ~/frappe-bench/apps
git clone https://github.com/shridarpatil/frappe_whatsapp.git
b. Install the App
cd ~/frappe-bench
bench --site your-site-name install-app frappe_whatsapp
c. Restart Bench
bench restart
3. 
Create a Custom Provider for Evolution API
a. Create Provider File
Create a new file at frappe_whatsapp/frappe_whatsapp/providers/evolution.py with the following content:
import frappe
import requests
from frappe_whatsapp.providers.base import BaseProvider
class EvolutionProvider(BaseProvider):
def __init__(self, settings):
super().__init__(settings)
self.api_base = settings.get("evolution_api_base")
self.token = settings.get("evolution_api_token")
def send_message(self, to_number, message, **kwargs):
url = f"{self.api_base}/messages"
payload = {
"to": to_number,
"text": message
}
headers = {
"Authorization": f"Bearer {self.token}",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
return response.json()
def parse_incoming(self, data):
return {
"from": data["from"],
"body": data["text"],
"message_id": data["id"],
"timestamp": data["timestamp"]
}
b. Register the Provider
In frappe_whatsapp/frappe_whatsapp/providers/__init__.py, add:
from .evolution import EvolutionProvider
PROVIDERS = {
# ... existing providers
"Evolution": EvolutionProvider,
}
4. 
Configure WhatsApp Settings in ERPNext
a. Access WhatsApp Settings
Navigate to WhatsApp Settings in the ERPNext UI.
b. Set Provider and Credentials
- Provider:
Evolution - Evolution API Base URL:
https://evolution.example.com - Evolution API Token: Your Evolution API token(easypanel.io)
c. Save Settings
Click Save to apply the settings.
5. 
Set Up Webhook for Incoming Messages
a. Create Webhook Handler
In frappe_whatsapp/frappe_whatsapp/providers/evolution.py, add:
@frappe.whitelist(allow_guest=True)
def handle_webhook():
data = frappe.local.request.get_json()
provider = EvolutionProvider(frappe.get_single("WhatsApp Settings").as_dict())
msg = provider.parse_incoming(data)
from frappe_whatsapp.incoming import handle_incoming_message
handle_incoming_message(msg)
return "OK"
b. Expose Webhook Endpoint
In hooks.py, add:
override_whatsapp_webhook = {
"Evolution": "frappe_whatsapp.providers.evolution.handle_webhook"
}
c. Configure Webhook in Evolution API
Set the webhook URL in Evolution API to:
https://your-erpnext-domain.com/api/method/frappe_whatsapp.providers.evolution.handle_webhook
6. 
Test the Integration
a. Send a Message
Use the ERPNext UI to send a WhatsApp message to a test number.
b. Receive a Message
Reply from the test number and verify that the message appears in ERPNext.
Additional Tips
- Security: Ensure that your webhook endpoint is secured and only accessible by trusted sources.
- Logging: Implement logging in your custom provider to monitor message flow and troubleshoot issues.
- Updates: Regularly update both Evolution API and
frappe_whatsappto benefit from new features and security patches.
By following this guide, you can establish a robust and cost-effective WhatsApp integration with ERPNext 15 using Evolution API and frappe_whatsapp in a self-hosted environment.