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__.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_unicom-20.tar.gz (100.2 kB view details)

Uploaded Jun 14, 2025 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

django_unicom-20-py3-none-any.whl (130.2 kB view details)

Uploaded Jun 14, 2025 Python 3

File details

Details for the file django_unicom-20.tar.gz.

File metadata

Download URL: django_unicom-20.tar.gz
Upload date: Jun 14, 2025
Size: 100.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.9.5

File hashes

Hashes for django_unicom-20.tar.gz
Algorithm	Hash digest
SHA256	`89d217fc3009a24e5f86c7039cb82d24e7c3ba661eaab7a40e7c8fdab07b6c90`
MD5	`8a49e707f91eb67bede2c9d435650c6d`
BLAKE2b-256	`2eca3c851503ec8229667f14dd514cda333806be77aac5c76e4a3995a1901da5`

See more details on using hashes here.

File details

Details for the file django_unicom-20-py3-none-any.whl.

File metadata

Download URL: django_unicom-20-py3-none-any.whl
Upload date: Jun 14, 2025
Size: 130.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.9.5

File hashes

Hashes for django_unicom-20-py3-none-any.whl
Algorithm	Hash digest
SHA256	`a9b18231bc2990998ae90fb8d8a45c689dad1476131d5891f6371d30b6ece4da`
MD5	`cd93d7162d71b922ae11efe0e4f5f04a`
BLAKE2b-256	`bd1c58d77d88867b81bc69a51c0c7ad77a2598518c69d6baa040fd8a3b1c6ade`