Django Unicom

Unified communication layer for Django — easily integrate Telegram bots, WhatsApp bots, and Email bots with a consistent API across all platforms.

🚀 Quick Start

Install the package:
```
pip install django-unicom
```

Add required apps to your Django settings:

INSTALLED_APPS = [
    ...
    'django_ace',  # Required for the JSON configuration editor
    'unicom',
]

Include unicom URLs in your project's urls.py:

This is required so that webhook URLs can be constructed correctly.

from django.urls import path, include

urlpatterns = [
    ...
    path('unicom/', include('unicom.urls')),
]

Define your public origin: In your Django settings.py:

DJANGO_PUBLIC_ORIGIN = "https://yourdomain.com"

Or via environment variable:

DJANGO_PUBLIC_ORIGIN=https://yourdomain.com

(Optional, but recommended) Set your TinyMCE Cloud API key — required if you plan to compose Email messages from the Django admin UI.

Obtain a free key at https://www.tiny.cloud, then add it to your settings.py:
```
UNICOM_TINYMCE_API_KEY = "your-tinymce-api-key"
```
Or via environment variable:
```
UNICOM_TINYMCE_API_KEY=your-tinymce-api-key
```
and then you would still have to load it in settings.py
```
UNICOM_TINYMCE_API_KEY = os.getenv('UNICOM_TINYMCE_API_KEY', '')
```
(Optional) Set your OpenAI API key — required if you plan to use the AI-powered template population service.

Obtain a key from https://platform.openai.com/api-keys, then set it as an environment variable:
```
OPENAI_API_KEY="your-openai-api-key"
```
The application will automatically pick it up from the environment.

That's it! Unicom can now register and manage public-facing webhooks (e.g., for Telegram bots) based on your defined base URL and can automatically sync with email clients.

📝 Features & Usage

Channel Configuration

Each communication channel (Email, Telegram, WhatsApp) requires minimal configuration:

Email Channel

# Basic configuration - SMTP/IMAP settings are auto-discovered
email_config = {
    "EMAIL_ADDRESS": "your-email@example.com",
    "EMAIL_PASSWORD": "your-password"
}

# Optional: Override auto-discovered settings if needed
email_config_with_custom_settings = {
    "EMAIL_ADDRESS": "your-email@example.com",
    "EMAIL_PASSWORD": "your-password",
    "IMAP": {  # Optional - will be auto-discovered if not provided
        "host": "imap.example.com",
        "port": 993,
        "use_ssl": True,
        "protocol": "IMAP"
    },
    "SMTP": {  # Optional - will be auto-discovered if not provided
        "host": "smtp.example.com",
        "port": 587,
        "use_ssl": True,
        "protocol": "SMTP"
    },
    # Optional: Add a custom tracking parameter to all redirected links
    "TRACKING_PARAMETER_ID": "unicom_tid",  # Default is 'unicom_tid', omit to disable
    # Optional: Control when emails are marked as seen in IMAP. Options: 'on_save', 'on_request_completed', 'on_request_completed' (default)
    "MARK_SEEN_WHEN": "on_request_completed"
}

channel = Channel.objects.create(
    name="My Email Channel",
    platform="Email",
    config=email_config
)

Telegram Channel

# Only API token is required - webhook secret is auto-generated
telegram_config = {
    "API_TOKEN": "your-telegram-bot-token"
}

channel = Channel.objects.create(
    name="My Telegram Bot",
    platform="Telegram",
    config=telegram_config
)

Message Handling

Sending Messages

# Send an email
channel.send_message({
    'to': ['recipient@example.com'],
    'subject': 'Hello',
    'html': '<h1>Hello World</h1>'
})

# Send a Telegram message
channel.send_message({
    'chat_id': '123456789',
    'text': 'Hello Telegram!'
})

# Reply to a message
message.reply_with({
    'text': 'This is a reply'
})

Using Templates

from unicom.models import MessageTemplate

template = MessageTemplate.objects.create(
    title='Welcome Email',
    content='<h1>Welcome {{name}}!</h1>',
    category='Onboarding'
)

# Make template available for specific channels
template.channels.add(email_channel)

Scheduling Messages

from unicom.models import DraftMessage
from django.utils import timezone

draft = DraftMessage.objects.create(
    channel=channel,
    to=['recipient@example.com'],
    subject='Scheduled Email',
    html='<h1>This is scheduled</h1>',
    send_at=timezone.now() + timezone.timedelta(hours=24),
    is_approved=True,
    status='scheduled'
)

🧑‍💻 Contributing

We ❤️ contributors!

Requirements:

Docker & Docker Compose installed

Getting Started:

Clone the repo:

git clone https://github.com/meena-erian/unicom.git
cd unicom

Create a db.env file in the root:

POSTGRES_DB=unicom_test
POSTGRES_USER=unicom
POSTGRES_PASSWORD=unicom
DJANGO_PUBLIC_ORIGIN=https://yourdomain.com
# Needed if you want to use the rich-text email composer in the admin
UNICOM_TINYMCE_API_KEY=your-tinymce-api-key
# Needed if you want to use the AI template population service
OPENAI_API_KEY=your-openai-api-key

Start the dev environment:
```
docker-compose up --build
```
Run tests:
```
docker-compose exec app pytest
```
or just
```
pytest
```
Note: To run test_telegram_live tests you need to create telegram_credentials.py in the tests folder and define in it TELEGRAM_API_TOKEN and TELEGRAM_SECRET_TOKEN and to run test_email_live you need to create email_credentials.py in the tests folder and define in it EMAIL_CONFIG dict with the properties EMAIL_ADDRESS: str, EMAIL_PASSWORD: str, and IMAP: dict, and SMTP: dict, each of IMAP and SMTP contains host:str ,port:int, use_ssl:bool, protocol: (IMAP | SMTP)

No need to modify settings.py — everything is pre-wired to read from db.env.

📄 License

MIT License © Meena (Menas) Erian

📦 Release Automation

To release a new version to PyPI:

Ensure your changes are committed and pushed.
Run:
```
make release VERSION=1.2.3
```
This will:
- Tag the release as v1.2.3 in Git
- Push the tag
- Build the package
- Upload to PyPI using your .pypirc
For an auto-generated version based on date/time, just run:
```
make release
```
This will use the current date/time as the version (e.g., 2024.06.13.1530).

The version is automatically managed by setuptools_scm from Git tags and is available at runtime as unicom.__version__.

Metadata

Release files for django-unicom 20

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-unicom 20
File	Size	Uploaded
django_unicom-20.tar.gz	100.2 kB	Jun 14, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for django-unicom 20
File	Interpreter	ABI	Platform	Reset
django_unicom-20-py3-none-any.whl 130.2 kB Jun 14, 2025	Python 3	none	any	Details

Total release size: 230.5 kB

Release files / django_unicom-20.tar.gz

Download URL	django_unicom-20.tar.gz
Size	100.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`89d217fc3009a24e5f86c7039cb82d24e7c3ba661eaab7a40e7c8fdab07b6c90`
BLAKE2b-256 checksum How to use checksums	`2eca3c851503ec8229667f14dd514cda333806be77aac5c76e4a3995a1901da5`
Upload date	Jun 14, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.5`

Release files / django_unicom-20-py3-none-any.whl

Download URL	django_unicom-20-py3-none-any.whl
Size	130.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a9b18231bc2990998ae90fb8d8a45c689dad1476131d5891f6371d30b6ece4da`
BLAKE2b-256 checksum How to use checksums	`bd1c58d77d88867b81bc69a51c0c7ad77a2598518c69d6baa040fd8a3b1c6ade`
Upload date	Jun 14, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.5`