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
3. Obtain your Phone Number ID and Access Token from the Meta dashboard
4. Configure webhook URL in the Meta Business platform

Frappe Configuration

Navigate to WhatsApp Settings in your Frappe site and configure the following:

Webhook Configuration

Set up your webhook URL in the Meta Business platform:

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

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.