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.

django-meta-whatsapp emits four Django signals you can connect to in your host application to react to WhatsApp events — inbound messages, sent messages, campaign completions, and In-App Signup subscriptions. All four signals are defined in django_meta_whatsapp.signals and follow standard Django signal conventions.

​
Available Signals

​
whatsapp_message_received

Fired when an inbound message arrives and is processed by the webhook engine. The signal is sent after the message is persisted to the database. Provided kwargs: message — a WhatsAppMessage instance with direction="inbound".
myapp/handlers.py
from django.dispatch import receiver
from django_meta_whatsapp.signals import whatsapp_message_received
from django_meta_whatsapp.models import WhatsAppMessage

@receiver(whatsapp_message_received)
def handle_inbound_message(sender, message: WhatsAppMessage, **kwargs):
    print(f"New message from {message.phone_number}: {message.message_body}")
    # Trigger a CRM workflow, auto-reply, etc.

​
whatsapp_message_sent

Defined in django_meta_whatsapp.signals for use by host-application code. Connect a receiver to this signal and dispatch it yourself whenever your application sends an outbound message to track or log sent messages. Provided kwargs: message — a WhatsAppMessage instance with direction="outbound".
myapp/handlers.py
from django.dispatch import receiver
from django_meta_whatsapp.signals import whatsapp_message_sent

@receiver(whatsapp_message_sent)
def log_sent_message(sender, message, **kwargs):
    # Log to your analytics system
    analytics.track("whatsapp_message_sent", {
        "phone": message.phone_number,
        "type": message.message_type,
    })
whatsapp_message_sent is provided as a hook for your own application code to dispatch — the library itself does not fire it automatically. Call whatsapp_message_sent.send(sender=..., message=msg_instance) from your own views or utilities after a successful send.

​
whatsapp_campaign_completed

Defined in django_meta_whatsapp.signals for use by host-application code. Dispatch this signal from your own campaign post-processing logic to notify other parts of your application when a campaign finishes. Provided kwargs:
  • campaign — a WhatsAppCampaign instance
  • sent — integer count of successfully sent messages
  • failed — integer count of failed sends
myapp/handlers.py
from django.dispatch import receiver
from django_meta_whatsapp.signals import whatsapp_campaign_completed

@receiver(whatsapp_campaign_completed)
def notify_on_campaign_done(sender, campaign, sent, failed, **kwargs):
    send_slack_notification(
        f"Campaign '{campaign.name}' done: {sent} sent, {failed} failed."
    )
whatsapp_campaign_completed is provided as a hook for your own application code to dispatch — the library itself does not fire it automatically after run_campaign() completes. Dispatch it manually in a post-campaign hook if you need cross-component notifications.

​
whatsapp_user_subscribed

Fired when a user subscribes via an In-App Signup deep link (wa.me/PHONE/signup/ID). The webhook engine creates or updates the WhatsAppContact record before firing this signal. Provided kwargs:
  • contact — a WhatsAppContact instance (newly created or updated)
  • signup — the WhatsAppSignup instance the user subscribed through
myapp/handlers.py
from django.dispatch import receiver
from django_meta_whatsapp.signals import whatsapp_user_subscribed

@receiver(whatsapp_user_subscribed)
def on_user_subscribed(sender, contact, signup, **kwargs):
    # Send welcome email, create CRM record, etc.
    welcome_email.send(to=contact.email, name=contact.display_name)

​
Connecting Signals

Decorate receivers with @receiver and ensure the module containing them is imported at Django startup. The canonical place to do this is in your app’s AppConfig.ready() method:
myapp/apps.py
from django.apps import AppConfig

class MyAppConfig(AppConfig):
    name = "myapp"

    def ready(self):
        import myapp.handlers  # noqa — registers all @receiver decorators
Make sure your AppConfig is referenced in INSTALLED_APPS (either as the dotted path or via default_app_config):
settings.py
INSTALLED_APPS = [
    # ...
    "myapp.apps.MyAppConfig",  # explicit reference ensures ready() is called
]
Signal receivers run synchronously in the same request/response cycle as the webhook handler. The webhook view must return a response to Meta within a few seconds or Meta will retry the delivery. Keep your receivers fast — offload any heavy work (database writes, HTTP calls, email sends) to Celery tasks queued from inside the receiver.

​
Signal Reference

SignalDispatched byKey kwargs
whatsapp_message_receivedWebhookView (automatically)message: WhatsAppMessage
whatsapp_message_sentyour application codemessage: WhatsAppMessage
whatsapp_campaign_completedyour application codecampaign: WhatsAppCampaign, sent: int, failed: int
whatsapp_user_subscribedWebhookView (automatically)contact: WhatsAppContact, signup: WhatsAppSignup
Import path for all signals: 
from django_meta_whatsapp.signals import (
    whatsapp_message_received,
    whatsapp_message_sent,
    whatsapp_campaign_completed,
    whatsapp_user_subscribed,
)

Build docs developers (and LLMs) love

Get started for freeTalk to us