Telekit

Telekit is a declarative, developer-friendly framework for building Telegram bots. It gives developers a dedicated Sender for composing and sending messages and a Chain for handling dialogue between the user and the bot. The framework also handles inline keyboards and callback routing automatically, letting you focus on the bot's behavior instead of repetitive tasks.

import telekit

class MyStartHandler(telekit.Handler):
    @classmethod
    def init_handler(cls):
        cls.on.command('start').invoke(cls.handle_start)

    def handle_start(self):
        self.chain.sender.set_text("Hello!")
        self.chain.sender.set_photo("robot.png")
        self.chain.send()

telekit.Server("BOT_TOKEN").polling()

Send "Hello!" with a photo on /start

Telekit comes with a built-in DSL, allowing developers to create fully interactive bots with minimal code. It also integrates Jinja, giving you loops, conditionals, expressions, and filters to generate dynamic content.

@ main {
    title   = "🎉 Fun Facts Quiz";
    message = "Test your knowledge with 10 fun questions!";

    buttons {
        question_1("Start Quiz");
    }
}

See the full example

Even in its beta stage, Telekit accelerates bot development, offering typed command parameters, text styling via Bold(), Italic(), a built-in declarative calendar picker (!), emoji game results for 🎲 🎯 🏀 ⚽ 🎳 🎰, and much more out of the box. Its declarative design makes bots easier to read, maintain, and extend.

Key features:

• Chains handle complex conversations without state machines
• Ready-to-use DSL for FAQs and interactive scripts
• Automatic message formatting via Sender and callback routing
• Deep Linking with type-checked Command Parameters
• Built-in Permission and Logging system
• Reusable Traits for pluggable behavior modules
• Works with pyTelegramBotAPI

GitHub PyPI Telegram Community

Contents

• 🌟 Tutorial
• 🎆 Gallery
• 👀 Examples
  • Dialogue
  • Risk Game
  • Counter
  • Quiz (DSL)
  • Hotel (DSL)
  • More...

Overview

In Telekit, dialogs read like normal method calls. You point to the next step. Telekit calls it when the user replies.

Entries

No state machines. Just tell Telekit which method should handle the next user message.

def handle(self):
    self.chain.sender.set_text("👋 Hello! What is your name?")
    self.chain.set_entry_text(self.handle_name)
    self.chain.send()

def handle_name(self, name: str):
    self.chain.sender.set_text(f"Nice to meet you, {name}!")
    self.chain.send()

handle sends a message and registers handle_name as the next step with set_entry_text. When the user replies, Telekit calls handle_name and passes the reply as a plain str.

That's it. No enums. No manual state tracking. No boilerplate.

Inline Keyboards

The fastest way to add buttons to a message. Pass a dict where each key is the button label and each value is the callback to run when pressed:

self.chain.set_inline_keyboard(
    {
        "✏️ Change": self.change_name,
        "❌ Delete": self.delete,
    }
)

row_width controls how many buttons appear per row:

self.chain.set_inline_keyboard(
    {
        "One":   self.one,
        "Two":   self.two,
        "Three": self.three,
        "Four":  self.four,
        "Five":  self.five,
    },
    row_width=(3, 2)  # first row: 3 buttons, second row: 2
)

╭──────────┬──────────┬──────────╮
│   One    │   Two    │  Three   │
├──────────┴──┬───────┴──────────┤
│    Four     │       Five       │
╰─────────────┴──────────────────╯

For precise row layout or conditional buttons, use InlineKeyboard, a builder you compose step by step:

self.chain.set_keyboard(
    InlineKeyboard()
        .add_callback("-", self.decrement, style="danger")
        .add_callback("+", self.increment, style="success")
    .row()
        .add_callback("↺ Reset", self.reset)
)

╭──────────┬──────────╮
│    -     │    +     │
├──────────┴──────────┤
│       ↺ Reset       │
╰─────────────────────╯

InlineKeyboard is built by chaining method calls. Just call .row() to start a new row.

Not just callback buttons

Reply Keyboards

Reply keyboards replace the system keyboard with buttons at the bottom of the chat. Tapping one sends its text as a message, or triggers a system action like sharing a phone number or location.

self.chain.set_keyboard(
    ReplyKeyboard(one_time_keyboard=True)
        .add_text("Hello!")
        .add_text("Hi")
    .row()
        .add_contact("📱 Share phone")
        .add_location("📍 Share location")
)

Command Parameters

Telekit can parse and validate command parameters for you.

from telekit.parameters import *

class GreetHandler(telekit.Handler):
    @classmethod
    def init_handler(cls) -> None:
        cls.on.command("greet", params=[Int(), Str()]).invoke(cls.handle)

    def handle(self, age: int | None = None, name: str | None = None):
        if age is None or name is None:
            self.chain.sender.set_text("Usage: /greet <age> <name>")
        else:
            self.chain.sender.set_text(f"Hello, {name}! You are {age} years old. Next year you'll turn {age + 1} 😅")
        self.chain.send()

Now /greet 128 Dracula or even /greet 64 "Alice Reingold" are parsed automatically.

Dialogue

Dialogs are built as a chain of steps. Each method waits for the user before continuing.

class DialogueHandler(telekit.Handler):

    @classmethod
    def init_handler(cls) -> None:
        cls.on.text("hello", "hi", "hey").invoke(cls.handle_hello)

    def handle_hello(self) -> None:
        self.chain.sender.set_text("👋 Hello! What is your name?")
        if self.user.first_name:
            self.chain.set_entry_suggestions([self.user.first_name])
        self.chain.set_entry_text(self.handle_name)
        self.chain.send()

    def handle_name(self, name: str) -> None:
        self.user_name = name
        self.chain.sender.set_text("Nice! How are you feeling today?")
        self.chain.set_entry_text(self.handle_feeling)
        self.chain.send()

    def handle_feeling(self, feeling: str) -> None:
        self.chain.sender.set_text(f"Got it, {self.user_name.title()}! You feel: {feeling}")
        self.chain.set_inline_keyboard({"↺ Restart": self.handle_hello})
        self.chain.send()

How it works:

• The handler reacts to "hello", "hi", or "hey" in any case.
• handle_hello asks for the user's name.ч
• set_entry_suggestions attaches the user's Telegram first_name as a suggestion button.
• handle_name stores the name in self.user_name.
• handle_feeling closes the flow and adds a "↺ Restart" button that routes back to the start.

It reads like regular Python because it is regular Python.

Sender

Want to attach an image, document or add an effect in a single line?

self.chain.sender.set_effect(Effect.HEART) # Add effect to message. Use enum or string
self.chain.sender.set_photo("robot.png") # Attach photo. URL, file_id, or path
self.chain.sender.set_document("README.md") # Attach document. URL, file_id, or path
self.chain.sender.set_text_as_document("Hello, this is a text document!") # Convert string to text document
self.chain.sender.send_chat_action(ChatAction.TYPING) # Send chat action. Use enum or string

Styles

Describe formatting as objects instead of writing raw HTML or Markdown.

from telekit.styles import *

def handle(self) -> None:
    self.chain.sender.set_text(
        Bold("Text style examples:\n"),
        Stack(
            Bold("Bold text"),
            Italic("Italic text"),
            Bold(Italic("Bold + italic")),
            Link("Link", url="https://example.com"),
            BotLink("Deep link", username="MyBot", start="promo_42"),
            start="- {{index}}. ",
            sep=".\n",
        )
    )
    self.chain.send()

You describe structure. Telekit turns that structure into HTML or MarkdownV2:

<b>Text style examples:</b>

- 1. <b>Bold text</b>.
- 2. <i>Italic text</i>.
- 3. <b><i>Bold + italic</i></b>.
- 4. <a href="https://example.com">Link</a>.
- 5. <a href="https://t.me/MyBot?start=promo_42">Deep link</a>

You skip manual escaping and the broken formatting one stray character causes.

Telekit DSL

Prefer not to write dialog logic in Python? Use the built-in DSL with Jinja support.

import telekit

class QuizHandler(telekit.DSLHandler):
    @classmethod
    def init_handler(cls) -> None:
        cls.analyze_string(script)
        cls.on.command("start").invoke(cls.start_script)

script = """
$ timeout {
    time = 20; // 20 sec.
}

@ main {
    title   = "🎉 Fun Facts Quiz";
    message = "Test your knowledge with 10 fun questions!";

    buttons {
        next("Start Quiz");
    }
}

@ question_1 {
    title   = "🐶 Question 1";
    message = "Which animal is the fastest on land?";
    buttons {
        _lose("Elephant");
        next("Cheetah");       // correct answer
        _lose("Horse");
        _lose("Lion");
    }
}

/* ... */
"""

telekit.Server(BOT_TOKEN).polling()

Key features of the Telekit DSL:

• Scene-based architecture
• Anonymous scenes
• Automatic navigation stack management
• Input handling
• Images support and link buttons
• Template variables
• Custom variables
• Hooks (Python API integration)
• Jinja template engine

🎆 Click to see what you can do with the DSL

Traits

Traits are reusable behavior modules you can mix into any handler.

Here's the built-in CalendarPick trait: a user picks a date from an inline calendar, and a callback handles the result.

from telekit.traits import CalendarPick

class CalendarHandler(CalendarPick, telekit.Handler):

    @classmethod
    def init_handler(cls) -> None:
        cls.on.command("calendar").invoke(cls.handle)

    def handle(self) -> None:
        self.chain.sender.set_title("📅 Choose a date")
        self.chain.sender.set_message("Select any date — past or future:")
        self.chain.sender.set_remove_text(False)

        self.calendar_pick(self.handle_date) # HERE

    def handle_date(self, date: datetime.date) -> None:
        self.chain.sender.set_text(f"You picked: {date}")
        self.chain.send()

Result

Example Bot

Run this to launch an example bot:

import telekit

telekit.example(YOUR_BOT_TOKEN)

It includes example commands, dialogs, keyboards, and style usage.

Why Telekit

• Chains instead of an FSM.
• Declarative, behavior-focused bot logic with minimal boilerplate.
• Automatic callback routing and input handling.
• A Styles API for rich text (Bold, Italic, links) with automatic escaping.
• Deep linking and typed command parameters.
• A built-in DSL for menus, FAQs, and simple bots.
• Reusable Traits for composable behavior, including a built-in calendar picker.
• Zero-code mode Obsidian Canvas mode.
• Works with pyTelegramBotAPI.

Telekit focuses on one job: making Telegram bot development easier.

Changes in version 2.6.0a5

v2.6.0 a4

• Added handle_handoff() to Handler: a shortcut for handoff(handler).handle() that takes the target handler as an argument, so it can be passed to add_callback() without an extra closure
• Added handle_handoff_back_or() to TrackHandoffOrigin: a closure-free counterpart of handoff_back_or()
• Reworked handoff_back_or() as a thin functools.partial wrapper around handle_handoff_back_or()
• Fixed the handoff_back_or() docstring: the returned callable forwards its arguments to handle() instead of being zero-argument
• Converted the handoff() docstring to reST

v2.6.0 a3

• Added support for Rich HTML messages (Bot API 10.1+)
• Added the _rich.py module for Rich HTML parsing and serialization
• Added new rich tags to styles.py for enhanced text formatting
• Added the rich.py example handler demonstrating Rich HTML: inline styles, blocks, lists, tables, media, and sender integration

v2.6.0 a2

• Reworked .env and token/canvas file reading in utils
• Added full .env syntax support: comments, export, quotes and escapes, multi-line values, $VAR interpolation
• Added the cache parameter (default True) and clear_cache()
• Added detailed errors with fix suggestions and creation commands, and new Env*Error exceptions
• Changed load_env() to raise EnvFileNotFoundError for a missing file instead of returning {}

v2.6.0 a1

• Added a module-loading utility to utils

v2.6.0 a0

• Improved formatting in _on.py