Managing notifications in Django applications can often be a complex and cumbersome task. Django Magic Notifier (DMN) simplifies this by consolidating all your notification needs into a single, powerful API: notify(). Whether you need to send emails, SMS, WhatsApp messages, Telegram notifications, or push notifications, DMN handles it all seamlessly.
- Unified Notification API: One function
notify()to handle all notification types. - Multi-Channel Support: Email, SMS, WhatsApp, Telegram, and push notifications.
- Gateway Flexibility: Configure multiple gateways per channel with ease.
- Template-Based Messages: Use templates for consistent and professional notifications.
- File Attachments: Include files in your notifications.
- Asynchronous Notifications: Threaded support for background processing.
- Extensibility: Add custom gateways or notification types.
- MJML Support: Use modern, responsive email designs.
Install Django Magic Notifier using pip:
pip install --upgrade django-magic-notifierAdd the NOTIFIER configuration to your Django settings.py file. Below is an example of a complete configuration:
NOTIFIER = {
"EMAIL": {
"default": {
"HOST": "localhost",
"PORT": 587,
"USE_TLS": True,
"USE_SSL": False,
"USER": "root@localhost",
"FROM": "Root <root@localhost>",
"PASSWORD": "password",
"CLIENT": "magic_notifier.email_clients.django_email.DjangoEmailClient",
}
},
"WHATSAPP": {
"DEFAULT_GATEWAY": "waha",
"GATEWAYS": {
"waha": {
"BASE_URL": "http://localhost:3000"
}
}
},
"TELEGRAM": {
"DEFAULT_GATEWAY": "default",
"GATEWAYS": {
"default": {
"API_ID": "xxxxxx",
"API_HASH": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
},
"SMS": {
"DEFAULT_GATEWAY": "TWILIO",
"GATEWAYS": {
"TWILIO": {
"CLIENT": "magic_notifier.sms_clients.twilio_client.TwilioClient",
"ACCOUNT": "account_sid",
"TOKEN": "auth_token",
"FROM_NUMBER": "+1234567890"
}
}
},
"USER_FROM_WS_TOKEN_FUNCTION": "magic_notifier.utils.get_user_from_ws_token",
"GET_USER_NUMBER": "magic_notifier.utils.get_user_number",
"THREADED": True
}- EMAIL: Configure your email gateway, including host, port, and credentials.
- WHATSAPP: Define the WhatsApp gateway with its base URL.
- TELEGRAM: Configure Telegram with API credentials.
- SMS: Specify SMS gateways such as Twilio, Nexa, or others.
- THREADED: Enable background processing for notifications.
The notify() function is your gateway to all notification types.
from magic_notifier.notifier import notify
user = User.objects.get(email="testuser@localhost")
subject = "Welcome!"
notify(["email"], subject, [user], final_message="Welcome to our platform!")notify(["sms"], "Account Alert", [user], template="account_alert")notify(["email", "sms"], "System Update", [user], final_message="The system will be down for maintenance.")notify(["whatsapp"], "Welcome", [user], final_message="Hello! This is a WhatsApp test message.")notify(["telegram"], "Welcome", [user], final_message="Hello! This is a Telegram test message.")You can pass additional context to your templates via the context argument, note that the user
object is automatically passed:
context = {
"discount": 20
}
notify(["email"], "Special Offer", [user], template="special_offer", context=context)In the template:
{% block content %}
<p>Hi {{ user.first_name }},</p>
<p>We are excited to offer you a {{ discount }}% discount on your next purchase!</p>
{% endblock %}You can override default gateways directly when sending notifications:
notify(["email"], "Custom Email Gateway", [user], final_message="This uses a custom email gateway.", email_gateway="custom_gateway")notify(["sms"], "Custom SMS Gateway", [user], final_message="This uses a custom SMS gateway.", sms_gateway="custom_sms_gateway")notify(["whatsapp"], "Custom WhatsApp Gateway", [user], final_message="This uses a custom WhatsApp gateway.", whatsapp_gateway="custom_whatsapp_gateway")notify(["telegram"], "Custom Telegram Gateway", [user], final_message="This uses a custom Telegram gateway.", telegram_gateway="custom_telegram_gateway")When using templates, Django Magic Notifier looks for specific files depending on the notification channels. The template value designates a folder, not a file. Files are checked in the following order for each channel:
- Email:
email.mjml->email.html->email.txt - SMS:
sms.txt - WhatsApp:
whatsapp.txt->sms.txt - Telegram:
telegram.txt->sms.txt
If a file is not found, the next file in the sequence is checked. If no files are found, an error is raised.
Suppose notify() is called as follows:
notify(["telegram"], "Welcome", [user], template="welcome")The following files will be checked in order:
notifier/welcome/telegram.txtnotifier/welcome/sms.txt
Ensure that at least one of these files exists in your templates directory.
Attach files to your notifications:
files = ["/path/to/file.pdf"]
notify(["email"], "Invoice", [user], final_message="Your invoice is attached.", files=files)The notify() function supports predefined values for the receivers argument to target specific user groups:
notify(["email"], "Admin Alert", "admins", final_message="This is a message for all admin users.")notify(["email"], "Staff Notification", "staff", final_message="This message is for all staff members.")notify(["email"], "Global Announcement", "all", final_message="This is a message for all users.")notify(["email"], "Non-Staff Update", "all-staff", final_message="This message is for users who are not staff.")notify(["email"], "User Alert", "all-admins", final_message="This is a message for all users except admins.")Enable threaded notifications for better performance:
notify(["sms"], "Alert", [user], final_message="This is a test.", threaded=True)DMN includes comprehensive test cases for all features. To run tests:
python manage.py test- Extend support for additional messaging platforms.
We welcome contributions! To get started, fork the repository, make your changes, and submit a pull request. Refer to our contributing guidelines for more details.
This project is licensed under the MIT License. See the LICENSE file for details.
File an issue on GitHub.