Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rahul-baberwal/django-meta-whatsapp/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide you’ll have django-meta-whatsapp installed, wired up to your Django project, and ready to receive and send WhatsApp messages through the Meta Cloud API v22.0. The whole process takes less than 5 minutes.
1

Install the package

Install django-meta-whatsapp from PyPI using your preferred package manager.
pip install django-meta-whatsapp
2

Add to INSTALLED_APPS

Add django_meta_whatsapp to your INSTALLED_APPS list in settings.py.
settings.py
INSTALLED_APPS = [
    # ... your existing apps ...
    "django_meta_whatsapp",
]
3

Mount URLs

Include the package URLs in your project’s root urls.py. The namespace argument is required.
urls.py
from django.urls import path, include

urlpatterns = [
    # ... your existing URL patterns ...
    path("whatsapp/", include("django_meta_whatsapp.urls", namespace="django_meta_whatsapp")),
]
4

Configure credentials

Add the WHATSAPP settings dict to settings.py. At minimum you need your Meta access token, the phone number ID, and a webhook verification token.
settings.py
WHATSAPP = {
    "ACCESS_TOKEN": "EAA...",               # Meta system-user permanent access token
    "PHONE_NUMBER_ID": "1234567890",         # From the Meta developer dashboard
    "VERIFY_TOKEN": "your_secure_random_string",
}
ACCESS_TOKEN is the permanent (system-user) access token generated in the Meta Business Suite — not a short-lived user token. VERIFY_TOKEN is any secure random string you choose; Meta will send it back on webhook verification so your endpoint can confirm the request is genuine.
5

Run migrations

Apply the package’s database migrations. A single clean migration (0001_initial) creates all required tables.
python manage.py migrate
6

Open the dashboard

Start your development server and navigate to the dashboard:
python manage.py runserver
  1. Visit http://127.0.0.1:8000/whatsapp/ in your browser.
  2. If no WhatsApp Account exists yet, the UI will prompt you to add one under Settings → Accounts.
  3. In your Meta App dashboard, set the webhook URL to: 
    https://yourdomain.com/whatsapp/webhook/
    Use your VERIFY_TOKEN as the verification token when prompted by Meta.
  4. Head to the Templates tab and click Sync from Meta to import your approved message templates.
  5. Open the Inbox — you’re live!

​
Send your first message

Once configured, you can send a WhatsApp text message from anywhere in your Django codebase using the send_text_message utility: 
from django_meta_whatsapp.utils import send_text_message

send_text_message("919876543210", "Hello from django-meta-whatsapp!")
The phone number should include the country code (e.g. 91 for India). The function normalises formatting automatically — leading + signs, spaces, and dashes are all stripped.
In a production multi-account setup, pass a WhatsAppAccount model instance as the account keyword argument instead of relying on global settings. This lets you route messages through the correct Business Account:
from django_meta_whatsapp.models import WhatsAppAccount
from django_meta_whatsapp.utils import send_text_message

account = WhatsAppAccount.objects.get(name="My Brand")
send_text_message("919876543210", "Hello!", account=account)
Accounts are managed through the dashboard UI at /whatsapp/settings/accounts/. See Multi-Account Support for details.

​
Next steps

Configuration

Explore every option in the WHATSAPP settings dict — UI customisation, audience providers, Celery, and more.

Inbox

Learn how the live unified inbox works, including reply threading and media handling.

Campaigns

Set up bulk marketing campaigns with approved templates and audience targeting.

REST API

Authenticate with API keys and integrate WhatsApp messaging into external services.

Build docs developers (and LLMs) love

Get started for freeTalk to us