kajenn-bot-application

Document version: 0.3 · Last updated: 2026-10-08 · Status: 🔴 UNDER REVIEW

Run Telegram and WhatsApp bots as kajenn applications. Receive centrally, send from local services, and keep each bot's configuration and conversations separate.

Use it for developer notifications, review conversations, administrator-approved access, announcements and scheduled follow-ups. Bot behavior lives in ordinary RoutingClass methods; configuration uses class-owned grammars.

Read the documentation · Getting started · API reference

What it provides

BotBaseApplication owns shared registration, conversation and task behavior. TelegramBotApplication and WhatsAppBotApplication preserve each provider's capabilities and constraints. Persistence is delegated to one route per application; encrypted filesystem providers are included in the examples.

Install

Python 3.11–3.14 is tested. kajenn>=0.3.0 is installed as a dependency. Bot versions and releases are independent from the server.

Install the published package in a virtual environment:

python -m venv .venv
source .venv/bin/activate
python -m pip install kajenn-bot-application

To run the included examples or contribute, clone the repository and install it:

git clone https://github.com/kajenn-org/kajenn-bot-application.git
cd kajenn-bot-application
python -m pip install .

On Windows, activate the environment with .venv\Scripts\Activate.ps1. The distribution is named kajenn-bot-application; Python imports use kajenn_bot_application. No kajenn source checkout is needed.

from kajenn_bot_application import TelegramBotApplication, WhatsAppBotApplication

Run your first bot

The getting started guide walks through credentials, persistent storage, the public webhook and the first /hello reply. From the repository root, after configuring that environment:

kajenn serve examples/telegram_bot/config.py --port 8000
# Or run the WhatsApp example:
kajenn serve examples/whatsapp_bot/config.py --port 8000

Both examples provide /hello and /echo. Each has a local_config.py recipe that sends directly without replacing the central webhook. Within an initialized application, a local job can notify a user:

telegram = server.applications["telegram"]
await telegram.send_message("alpha", mario_chat_id, "You have a new PR")

The bot must already be registered, and Mario must have started a private chat with it. The local service needs the bot token, not only the chat ID. Replies go to the central webhook. WhatsApp notifications use approved templates outside the known customer service window.

Learn and deploy

Scope and delivery guarantees

This package uses official bot/business APIs. It does not provide personal-account sessions, group history imports, automatic application-user provisioning, or a public bot-management API. Admission does not grant kajenn router permissions.

The filesystem examples support one receiving process per registry. Webhook acknowledgement means work has been staged, not that a reply was delivered. Provider sends and persistence writes are separate operations; delivery is not exactly once. See the operations guide before replaying failed or uncertain work.

Contributing

python -m pip install -e ".[dev,docs]"
git config core.hooksPath hooks
pytest -q
ruff check src tests examples tools
python tools/check_boundary.py
sphinx-build -W -b html docs docs/_build/html

CI installs the built wheel, runs the integration suite on Python 3.11–3.14, checks the minimum kajenn version, uploads coverage to Codecov and builds the documentation with warnings treated as errors. Provider HTTP is mocked; routing, tasks and encrypted persistence use the real server services.

Changes go through pull requests to develop. See development and releases for the package boundary and checks.

Apache-2.0 · Copyright Softwell S.r.l. · Based on genropy history and genro-modules.