Botxona

How to deploy an aiogram bot — aiogram bot hosting on Botxona

aiogram is one of the most widely used Python Telegram bot libraries in Uzbekistan, thanks to its async design and clean syntax. This guide shows how to deploy a bot written with aiogram 3 to Botxona correctly.

Does aiogram need extra setup?

No. To provide analytics and isolation, Botxona automatically routes every bot's Telegram requests through its own proxy — there is no need to configure AiohttpSession, TelegramAPIServer or any other custom API address in your code. A plain Bot(token) is enough.

Steps

1. Create the bot object

Create the bot object in main.py:

import os
import asyncio
from aiogram import Bot, Dispatcher

BOT_TOKEN = os.getenv("BOT_TOKEN")

bot = Bot(token=BOT_TOKEN)
dp = Dispatcher()

async def main():
    await dp.start_polling(bot)

if __name__ == "__main__":
    asyncio.run(main())

Note that the token is not hardcoded — it is read from the BOT_TOKEN environment variable, as required by the first rule. The Telegram API address stays at its default — the proxy is automatic.

2. Point your data at DATA_DIR

If your bot stores data in SQLite or other files:

DATA_DIR = os.getenv("DATA_DIR", "./data")
os.makedirs(DATA_DIR, exist_ok=True)
DB_PATH = os.path.join(DATA_DIR, "bot.sqlite3")

If you use aiosqlite or SQLAlchemy (common with aiogram), point the database file at this path too.

3. Write requirements.txt (with pinned versions)

aiogram==3.13.1
aiosqlite==0.20.0
python-dotenv==1.0.1

Pinned versions are required — if you write plain aiogram without a version, the check report shows a yellow mark, and a future release may break your code.

4. Create .env.example

# Admin Telegram IDs, comma-separated
ADMIN_IDS=

Do not add BOT_TOKEN or DATA_DIR to this file — the platform provides them automatically.

5. Zip the folder and upload it

All you need is main.py, requirements.txt and .env.example in one folder (botxona.yaml is optional — main.py is detected automatically). On archiving: Preparing a ZIP. Open the Botxona dashboard and upload it via "New bot".

6. Pass the check and the trial

After upload, an automatic check runs — this page explains the results. If everything is green or yellow, the bot starts in a 15-minute free trial — send it /start in Telegram to test it.

Scheduled tasks (APScheduler)

If you use APScheduler to send daily reports or reminders, Botxona detects it automatically and makes your bot always on (always_on) — otherwise a scheduled task could be missed while the bot is asleep. More: Sleep and wake-up.

Common errors

  • ModuleNotFoundError — the library is missing from requirements.txt or misspelled. Check the name and version.
  • The bot doesn't respond, but there are no errors in the logs — the token may be wrong; see Getting a token.
  • sqlite3.OperationalError: unable to open database file — the DATA_DIR folder wasn't created; don't forget the os.makedirs(DATA_DIR, exist_ok=True) line.

Faster with AI

If your codebase is large, instead of adapting it by hand you can give the "Standardize" prompt from the Prompt library to an AI (ChatGPT, Claude) — it applies all the changes above in seconds.

Next steps

Once the bot is running: Dashboard tour, Keeping your bot running 24/7.