Asynchronous library for Telegram bot API

Key Features

Asyncio and aiohttp based
All Telegram Bot API types and methods supported
Tracks Telegram Bot API 7.2 (released March 31, 2024)
Bot API rate limit support
Both long polling and webhooks supported
Fully type annotated (PEP 484)

Installation

aiotgbot is available on PyPI. Use pip to install it:

pip install aiotgbot

Requirements

Using aiotgbot

from typing import AsyncIterator

from aiotgbot import (
    Bot,
    BotUpdate,
    BotUpdateKey,
    HandlerTable,
    PollBot,
    PrivateChatFilter,
    Runner,
)
from aiotgbot.storage_memory import MemoryStorage

handlers = HandlerTable()


@handlers.message(filters=[PrivateChatFilter()])
async def reply_private_message(bot: Bot, update: BotUpdate) -> None:
    assert update.message is not None
    name = (
        f"{update.message.chat.first_name} "
        f"{update.message.chat.last_name}"
    )
    update["greeting_count"] = update.get("greeting_count", 0) + 1
    await bot.send_message(update.message.chat.id, f"Hello, {name}!")


async def run_context(runner: Runner) -> AsyncIterator[None]:
    storage = MemoryStorage()
    await storage.connect()
    handlers.freeze()
    bot = PollBot(runner["token"], handlers, storage)
    await bot.start()

    yield

    await bot.stop()
    await storage.close()


def main() -> None:
    runner = Runner(run_context)
    runner["token"] = "some:token"
    runner.run()


if __name__ == "__main__":
    main()

Upgrading to 0.18.0

New features:

BotUpdateKey – a dedicated typed key object for items stored on BotUpdate.
BotUpdate exposes get_typed(key), set_typed(key, value), and del_typed(key) helpers for working with BotUpdateKey instances.
Each BotUpdateKey enforces runtime type checking via isinstance() so handlers only see the expected payload.

BotUpdate remains a regular mutable mapping so filters and handlers can stash arbitrary helper objects between each other. To keep data structured, use BotUpdateKey which enforces types per slot:

from dataclasses import dataclass

from aiotgbot import BotUpdateKey


@dataclass
class Session:
    trace_id: str
    retries: int


session_key = BotUpdateKey("session", Session)


async def my_handler(bot: Bot, update: BotUpdate) -> None:
    if session_key.name not in update:
        update.set_typed(session_key, Session(trace_id="abc", retries=0))
    session = update.get_typed(session_key)
    ...

Development

We use Prek as a drop-in pre-commit replacement backed by uv so hook environments resolve quickly and reproducibly. Install it once and run the configured Ruff, mypy --strict, and Basedpyright checks via:

uv tool install prek
prek install
prek run --all-files

prek run reads .pre-commit-config.yaml, so you can still target a subset of hooks or files during local development.

mise.toml at the repo root mirrors the common workflows, so you can rely on mise instead of remembering the raw commands. Trust the config once via mise trust mise.toml and then run, for example:

mise run lint
mise run mypy
mise run basedpyright
mise run test

Metadata

Release files for aiotgbot 0.18.9

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

Source distribution (sdist)

Source distribution for aiotgbot 0.18.9
File	Size	Uploaded
aiotgbot-0.18.9.tar.gz	38.3 kB	Nov 25, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for aiotgbot 0.18.9
File	Interpreter	ABI	Platform	Reset
aiotgbot-0.18.9-py3-none-any.whl 43.4 kB Nov 25, 2025	Python 3	none	any	Details

Total release size: 81.6 kB

Release files / aiotgbot-0.18.9.tar.gz

Download URL	aiotgbot-0.18.9.tar.gz
Size	38.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`36bdaacec4d7efe629a13ddfb2e0623959d01daf86dad6e56e811745600f6415`
BLAKE2b-256 checksum How to use checksums	`752c38eebd6b6e6d6be7f1cb059083c9e6e9427badfba2ba24cd5fab7eb85885`
Upload date	Nov 25, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / aiotgbot-0.18.9-py3-none-any.whl

Download URL	aiotgbot-0.18.9-py3-none-any.whl
Size	43.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`35836b0174a101cfaac2993db3a915d6db8ef1e10309a0873c80b40cb6600408`
BLAKE2b-256 checksum How to use checksums	`3bbacc90d3bab7f3790ef56f3e55af1b27d6a561dacf935203c3fa31e14b18e0`
Upload date	Nov 25, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`