WhatsApp Saudi – Multi-Provider WhatsApp Integration for ERPNext

Introduction

WhatsApp Saudi is a custom ERPNext application built on the Frappe Framework that enables businesses to integrate multiple WhatsApp providers within a single system. It supports automated messaging, invoice delivery, promotional communication, template-based messaging, webhook response handling, and structured logging.

The system is designed to provide flexibility, scalability, and full visibility of message activity.

Supported WhatsApp Providers

The application currently supports three providers:

Whatsa.Net
Rasayel
Bevatel

Each provider has its own authentication structure and messaging workflow, but all are managed centrally through the WhatsApp Saudi Settings DocType.

1. Whatsa.Net Integration Configuration

Whatsa.Net requires the following credentials:

Token
Instance ID
File URL
Message URL

These credentials are configured inside the WhatsApp Saudi Settings page.

Test Message Feature

A "To Number (for testing)" field allows administrators to verify API configuration.

Clicking Send Test Message sends a live WhatsApp message to confirm:

Token validity
Instance activation
API endpoint functionality

Webhook Response Handling (Whatsa.Net)

Whatsa.Net supports webhook-based response tracking.

When customers reply to a WhatsApp message:

Whatsa.Net sends the incoming message to a configured webhook URL.
ERPNext receives the webhook payload.
The system stores the response in the WhatsApp Response DocType.

This allows businesses to:

Track customer replies
Maintain conversation history
Build future automation based on responses

2. Rasayel Integration Configuration

Rasayel is a WhatsApp Business API platform that enables structured, template-based messaging through secure REST APIs. Within the WhatsApp Saudi application, Rasayel is integrated as a template-driven provider for automated transactional and promotional communication from ERPNext.

Rasayel requires:

Authorization Token
Channel ID
Template ID
File Upload URL
Message URL

Important: Rasayel works strictly with approved WhatsApp Business templates.

Inside ERPNext Notification, messages must be configured using only the template ID and variables:

message_template_id=450588
var1={doc.name}
var2={doc.customer}

Do NOT send full message text.
Only the Template ID and variables should be provided.
The message content itself is controlled from Rasayel.

3. Bevatel Integration Configuration

Bevatel is a WhatsApp Business API service provider that enables template-based transactional and promotional messaging through secure API integration. Within WhatsApp Saudi, Bevatel is fully supported for automated WhatsApp notifications directly from ERPNext.

Key capabilities include:

Template-based WhatsApp messaging
Arabic and multi-language template support

Unlike Whatsa.Net (which supports free-text messaging), Bevatel strictly operates using pre-approved templates. All outgoing messages must reference a template created in the Bevatel dashboard.

Bevatel requires:

Access Token
Account ID
Inbox ID
API URL
Template Name
Language
Template Message Format

Example configuration inside Notification:

message_template_id="promo_code2"
language="ar"
var1="{{doc.customer_name}}"

Only template references and variables should be passed. The actual message content is maintained within Bevatel.

API Documentation Reference

For detailed API specifications (endpoints, authentication, request/response schemas), refer to the official documentation:

Bevatel Business Chat API Documentation

Step-by-Step Configuration & Workflow

Step 1: Create a New Notification

Navigate to: ERPNext → Settings → Notification
Click New to create a notification.

Step 2: Select Channel

Set Channel = WhatsApp Saudi. This instructs ERPNext to route the notification via WhatsApp Saudi instead of Email or SMS.

Step 3: Select Document Type

Choose the DocType that should trigger the WhatsApp message.

Examples:

Sales Invoice
Quotation
Delivery Note
Promo Code
Any custom DocType

Step 4: Set Trigger Event

Select when the message should be sent:

On Submit
On Save
On Cancel
On Update
Value Change

Example: Send an invoice message when the Sales Invoice is submitted.

Step 5: Add Condition (Optional)

Example conditions:

doc.status == "Paid"
doc.grand_total > 1000

If the condition evaluates to True, the message will be sent. If no condition is defined, the message triggers on every selected event.

Step 6: Add Recipient (Mobile Number)

In the Recipients section, select or define the mobile number field.

Examples:

doc.customer_mobile
doc.contact_mobile
doc.mobile_no

Ensure that the selected field exists in the chosen DocType.

Step 7: Add Message Content

For Whatsa.Net (Free Text Allowed)

Full message content can be written directly:

Dear {doc.customer_name},
Your invoice {doc.name} has been generated.
Total Amount: {doc.grand_total}
Thank you.

For Rasayel (Template-Based)

message_template_id=450588
var1={doc.name}
var2={doc.customer}

For Bevatel (Template-Based)

message_template_id="promo_code2"
language="ar"
var1="{{doc.customer_name}}"

Only template references and variables should be included.

Step 8: Enable PDF Attachment (Optional)

Enable Attach Print
Select the desired Print Format

If a PDF is not required, do not enable Attach Print.

Step 9: Save & Enable Notification

Click Save
Ensure the Notification is Enabled

System Flow (Internal Process)

Document event occurs (e.g., Sales Invoice Submit)
ERPNext evaluates the notification condition
Channel identified as WhatsApp Saudi
Active provider detected (Whatsa.Net / Rasayel / Bevatel)
Provider credentials fetched from Settings
Payload constructed
API request sent
Response processed

If successful:

An entry is created in the WhatsApp Saudi Success Log.

If an error occurs:

The issue is recorded in the standard ERPNext Error Log.

If Whatsa.Net receives a reply:

The message is stored in the WhatsApp Response DocType.

Error Handling & Logging Architecture

1. Error Logging

The system automatically logs errors such as:

Invalid credentials
API failures
Template mismatches
Network errors
Authentication issues

All errors are stored in the standard ERPNext Error Log, enabling administrators to quickly diagnose issues.

2. Success Logging

Successful messages are recorded in a custom DocType: WhatsApp Saudi Success Log

This includes:

API response
Recipient number
Timestamp
Status

This ensures full auditability of outgoing communication.

3. Incoming Message Storage (Whatsa.Net)

Customer replies are received via webhook
Stored in WhatsApp Response DocType
Enables two-way conversation tracking inside ERPNext

Workflow Summary

Select Channel: WhatsApp Saudi
Select DocType
Add Trigger Event
Add Condition (Optional)
Add Recipient Mobile Field
Add Message or Template Reference
Enable Attach Print (if required)
Save & Enable

The system automatically handles provider selection, payload construction, API communication, response processing, and logging.

Video Demonstration – Complete Workflow

Watch the complete WhatsApp Saudi workflow demonstration below: