Frappe WhatsApp

Features

Installation

Prerequisites

• Frappe Framework v13 or higher
• Python 3.7+
• WhatsApp Business API access
• Valid Meta Business account

Install the App

Get the app from the GitHub repository:

bench get-app https://github.com/shridarpatil/frappe_whatsapp.git

Install the app on your site:

bench --site your-site.com install-app frappe_whatsapp

Run migrations:

bench --site your-site.com migrate

Restart bench to load the new app:

bench restart

Configuration

WhatsApp Business API Setup

1. Create a WhatsApp Business account at Meta Business
2. Set up a WhatsApp Business API application in the Meta Developer Portal
3. Obtain your Phone Number ID, Business Account ID, and Access Token from the Meta dashboard
4. Configure webhook URL in the Meta Business platform

WhatsApp Account Setup

Navigate to WhatsApp Account in your Frappe site and create a new account with the following settings:

Multi-Account Support

You can configure multiple WhatsApp accounts for different purposes:

• Is Default Outgoing: Use this account as the default for sending messages
• Is Default Incoming: Use this account as the default for receiving messages
• Allow Auto Read Receipt: Automatically send read receipts for incoming messages

Webhook Configuration

Set up your webhook URL in the Meta Business platform:

https://your-site.com/api/method/frappe_whatsapp.utils.webhook.webhook

Subscribe to the following webhook fields:

• messages - To receive incoming messages
• message_template_status_update - For template approval status updates

WhatsApp Notifications

WhatsApp Notifications allow you to automatically send WhatsApp messages based on events in your Frappe/ERPNext system. This is similar to Email Alerts but for WhatsApp.

Creating a Notification

Navigate to WhatsApp Notification and create a new notification with the following settings:

Basic Settings

Supported DocType Events

• Before/After Insert - When a new document is created
• Before/After Save - When a document is saved
• Before/After Submit - When a document is submitted
• Before/After Cancel - When a document is cancelled
• Before Delete - When a document is deleted
• Days Before/After - Based on a date field (e.g., 3 days before delivery date)

Scheduler Events

For scheduled notifications, choose from these frequencies:

• All (every minute)
• Hourly / Hourly Long
• Daily / Daily Long
• Weekly / Weekly Long
• Monthly / Monthly Long
• Yearly

Template Parameters

Map template placeholders to DocType fields using the Fields table:

Template: "Hello {{1}}, your order {{2}} is ready for delivery on {{3}}."

Field Mapping:
- Parameter 1 → customer_name
- Parameter 2 → name (document name/ID)
- Parameter 3 → delivery_date

Conditions

Add Python conditions to control when notifications are sent:

# Only send if order total is above 10000
doc.grand_total > 10000

# Only send for specific customer group
doc.customer_group == "Retail"

# Only send if not already notified
not doc.whatsapp_notified

Attachments

You can attach files to your WhatsApp notifications:

• Attach Document Print - Attach the document as a PDF
• Custom Attachment - Attach a specific file or use a field containing a file URL

Post-Send Actions

Update a field after the notification is sent (useful for tracking):

Interactive Buttons

Map DocType fields to dynamic button URLs in your templates:

Button URL Template: https://yoursite.com/orders/{{1}}
Button Field Mapping: name (document ID)

Custom Data List

For advanced use cases, you can send templates using custom data instead of DocType fields by setting _data_list:

# In your condition or server script
doc.set("_data_list", [
    {
        "phone": "+1234567890",
        "customer_name": "John Doe",
        "order_id": "ORD-001"
    },
    {
        "phone": "+0987654321",
        "customer_name": "Jane Smith",
        "order_id": "ORD-002"
    }
])

Bulk WhatsApp Messaging

Send WhatsApp messages to multiple recipients at once using templates. Ideal for marketing campaigns, announcements, and batch notifications.

Creating a Bulk Message

Navigate to Bulk WhatsApp Message and create a new document:

Basic Settings

Recipient Types

1. Individual Recipients

Add recipients directly in the document. Each recipient can have:

• Mobile Number - The WhatsApp number (with country code)
• Recipient Name - Display name for reference
• Recipient Data - JSON data for template variables

2. Recipient List

Use a pre-configured WhatsApp Recipient List that can be reused across campaigns.

Creating a Recipient List

Navigate to WhatsApp Recipient List to create reusable recipient groups:

Import from DocType

Import recipients from any DocType (Customer, Contact, Lead, etc.):

1. Click "Import from DocType"
2. Select the DocType (e.g., "Customer")
3. Map the phone field (e.g., "mobile_no")
4. Optionally add filters and additional data fields

Example: Import all retail customers
DocType: Customer
Phone Field: mobile_no
Name Field: customer_name
Filters: {"customer_group": "Retail"}
Data Fields: ["customer_name", "territory"]

Template Variables

Variable Types

Using Unique Variables

Store recipient-specific data in the recipient_data JSON field:

{
    "customer_name": "John Doe",
    "order_id": "ORD-001",
    "delivery_date": "2024-01-15"
}

Message Workflow

1. Draft - Configure recipients and template
2. Submit - Messages are queued for background processing
3. In Progress - Messages are being sent
4. Completed - All messages sent successfully
5. Partially Failed - Some messages failed (can retry)

Progress Tracking

Monitor your bulk message progress:

• Recipient Count - Total recipients
• Sent Count - Successfully sent messages
• Status - Overall campaign status

Retrying Failed Messages

If some messages fail, you can retry them:

1. Open the Bulk WhatsApp Message document
2. Click "Retry Failed" button
3. Failed messages will be requeued for sending

Attachments

Attach media files to your bulk messages:

• Images (JPG, PNG)
• Documents (PDF)
• Videos (MP4)

Template Management

WhatsApp templates are pre-approved message formats required for initiating conversations outside the 24-hour window.

Creating Templates

Navigate to WhatsApp Templates to create and manage templates:

Template Components

Button Types

• Quick Reply - Pre-defined response buttons
• Call Phone - Click-to-call button
• Visit Website - URL button (can include dynamic parameters)

Syncing Templates

Fetch templates from Meta to sync approval status:

1. Open WhatsApp Templates list
2. Click "Fetch Templates" button
3. Templates will be synced from all active WhatsApp accounts

Template Status

• PENDING - Submitted for approval
• APPROVED - Ready to use
• REJECTED - Not approved (check rejection reason)

Interactive Messages

Send interactive button and list messages for quick user responses and improved engagement.

Button Messages

Button messages allow users to respond with a single tap:

• Up to 3 quick reply buttons per message
• Users tap to respond instantly
• Great for confirmations, options, and CTAs

List Messages

List messages provide a menu-style interface:

• Up to 10 items organized in sections
• Users select from a scrollable menu
• Ideal for product catalogs, service menus, FAQs

Sending Interactive Messages

Set the content_type field when creating a WhatsApp Message:

# Button message
message = frappe.get_doc({
    "doctype": "WhatsApp Message",
    "to": "+1234567890",
    "content_type": "button",
    "message": "Please choose an option:",
    "buttons": [
        {"type": "button", "title": "Option 1", "id": "btn_1"},
        {"type": "button", "title": "Option 2", "id": "btn_2"},
        {"type": "button", "title": "Option 3", "id": "btn_3"}
    ]
})
message.insert()

WhatsApp Flows

Build interactive forms using WhatsApp's native Flow Builder. Flows provide a rich UI experience for collecting structured data from users.

Features

• Visual form builder with multiple screens
• Support for text inputs, dropdowns, date pickers, and more
• Client-only flows (no endpoint required)
• Publish and manage flows directly from Frappe
• Send flow messages and receive responses via webhook

Creating a Flow

Navigate to WhatsApp Flow to create a new flow:

1. Enter a Flow Name
2. Select the WhatsApp Account
3. Choose a Category (e.g., APPOINTMENT_BOOKING, LEAD_GENERATION)
4. Add Screens to define the flow structure
5. Add Fields for each screen

Supported Field Types

Flow Actions

Available actions from the WhatsApp Flow form:

• Create on WhatsApp - Push the flow to Meta
• Upload Flow JSON - Update the flow definition
• Publish - Make the flow available to all users
• Deprecate - Mark the flow as deprecated
• Send Test - Test draft flows with registered test numbers
• Sync from Meta - Import flow data back from Meta
• Delete from WhatsApp - Remove the flow from Meta

Sending Flow Messages

# Send a flow message
message = frappe.get_doc({
    "doctype": "WhatsApp Message",
    "to": "+1234567890",
    "content_type": "flow",
    "flow": "My Booking Flow",  # Link to WhatsApp Flow
    "flow_cta": "Open Booking Form",
    "message": "Please fill out the booking form below"
})
message.insert()

Sync from Meta

Keep your Frappe data synchronized with your Meta Business Account.

Syncing Templates

1. Go to WhatsApp Templates list view
2. Click the Sync from Meta button
3. All templates from active WhatsApp accounts are imported/updated

The sync will:

• Import new templates that don't exist locally
• Update existing templates with latest status and content
• Sync header, body, footer, and button configurations

Syncing Flows

1. Go to WhatsApp Flow list view
2. Click the Sync from Meta button
3. Select the WhatsApp Account to sync from
4. All flows are imported/updated

The sync will:

• Import new flows with their JSON definitions
• Update existing flows with latest status
• Parse flow JSON into screens and fields

API Documentation

{
    "to": "+1234567890",
    "message": "Hello from Frappe WhatsApp!",
    "template": "order_confirmation",  // optional
    "parameters": ["ORD-001", "John Doe"]  // optional
}

Examples

Python API Usage

Send a simple text message:

import frappe
from frappe_whatsapp.api import send_whatsapp_message

# Send a text message
response = send_whatsapp_message(
    to="+1234567890",
    message="Hello! Your order has been confirmed."
)

print(f"Message ID: {response.get('message_id')}")

Send a template message with parameters:

from frappe_whatsapp.api import send_whatsapp_message

# Send template message
response = send_whatsapp_message(
    to="+1234567890",
    template="order_shipped",
    parameters=[
        "ORD-12345",           # Order number
        "John Doe",            # Customer name
        "2024-01-15",         # Delivery date
        "https://track.example.com/ORD-12345"  # Tracking URL
    ]
)

Server Script Example

Automatically send WhatsApp notification on Sales Order submission:

# Server Script - On Submit
if doc.doctype == "Sales Order" and doc.customer_whatsapp:
    from frappe_whatsapp.api import send_whatsapp_message
    
    send_whatsapp_message(
        to=doc.customer_whatsapp,
        template="order_confirmation",
        parameters=[
            doc.name,
            doc.customer_name,
            str(doc.grand_total),
            doc.delivery_date.strftime("%B %d, %Y")
        ]
    )

Handling Incoming Messages

Process incoming WhatsApp messages using hooks:

# In your app's hooks.py
doc_events = {
    "WhatsApp Message": {
        "after_insert": "your_app.utils.process_whatsapp_message"
    }
}

# In your_app/utils.py
def process_whatsapp_message(doc, method):
    if doc.message_type == "received":
        # Process incoming message
        if "order status" in doc.message.lower():
            # Send automated response
            send_order_status(doc.from_number)

Troubleshooting

Common Issues

Webhook Verification Failed

• Ensure your site is accessible over HTTPS
• Check that the webhook verify token matches in both Frappe and Meta Business
• Verify your site is in production mode

Messages Not Sending

• Verify your Access Token is valid and not expired
• Check Phone Number ID is correct
• Ensure the recipient number includes country code
• Check error logs in Error Log doctype

Template Messages Not Working

• Ensure template is approved in Meta Business Manager
• Verify template name matches exactly (case-sensitive)
• Check parameter count matches template placeholders

Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License. See the LICENSE file for details.