How to Create and Set Up a Telegram Chatbot

Technical writer

Python

12.03.2025

Reading time: 18 min

Chatbots are software programs that simulate communication with users. Today, we use them for a wide range of purposes, from simple directories to complex services integrated with CRM systems and payment platforms.

People create bots for Telegram, Viber, Facebook Messenger, and other messaging platforms. Each platform has its own rules and capabilities—some lack payment integration, while others don't support flexible keyboards. This article focuses on user-friendly Telegram, which has a simple API and an active audience.

In this article, we will cover:

How to create a Telegram bot on your own
When it's convenient to use chatbot builders for development
How to integrate a chatbot with external services and APIs
What is needed for the bot to function smoothly
The key features of Aiogram, a popular Python library for chatbot development

Creating a Telegram Chatbot Without Programming Skills

Chatbot builders are becoming increasingly popular. These services allow you to create a bot using a simple "drag-and-drop" interface. No programming knowledge is required—you just build logic blocks like in a children's game.

However, there are some drawbacks to using chatbot builders:

Limited functionality. Most chatbot builders provide only a portion of Telegram API's capabilities. For example, not all of them allow integration with third-party services via HTTP requests. Those that do often have expensive pricing plans.
Generic scenarios. The minimal flexibility of builders leads to chatbots that look and function similarly.
Dependence on the service. If the platform goes offline or its pricing increases, you may have to migrate your bot elsewhere.

Builders are useful for prototyping and simple use cases—such as a welcome message, answering a few questions, or collecting contact information. However, more complex algorithms require knowledge of variables, data processing logic, and the Telegram API. Even when using a builder, you still need to understand how to address users by name, how inline keyboards work, and how to handle bot states.

Free versions of chatbot builders often come with limitations:

They may include advertising messages.
Some prevent integration with essential APIs.
Others impose limits on the number of users.

These restrictions can reduce audience engagement, making the chatbot ineffective. In the long run, premium versions of these builders can end up costing more than developing a bot from scratch and hosting it on your own server.

If you need a chatbot to handle real business tasks, automate processes, or work with databases, builders are often not sufficient. In such cases, hiring a developer is a better solution. A developer can design a flexible architecture, choose optimal technologies, and eliminate technical constraints that might hinder the project's scalability. If you already have a prototype built with a chatbot builder, you can use its logic as a starting point for technical specifications.

How to Create a Telegram Chatbot

Now, let's discuss how to create a Telegram chatbot using Python. You’ll need basic knowledge of variables, conditional statements, loops, and functions in Python.

To create chatbots, you can use a framework which is a set of tools, libraries, and ready-made solutions that simplify software development. You can work with the raw Telegram API and implement functionality using HTTP requests, but even for simple tasks, this approach requires writing thousands of lines of code.

In this guide, we’ll use Aiogram, one of the most popular frameworks for building Telegram chatbots in Python.

Step 1: Create a Virtual Environment for Your Project

Using a virtual environment in any Python project is considered good practice. Additionally, chatbots are often deployed on cloud servers where dependencies need to be installed. A virtual environment makes it easy to export a list of dependencies specific to your project.

Install the Python virtual environment:

sudo apt install python3-venv -y

Create a virtual Python environment in the working directory:

python -m venv venv

Activate the environment:

source ./venv/bin/activate

Step 2: Install Required Libraries

Install the Aiogram framework using pip:

pip install aiogram

Add a library for working with environment variables. We recommend this method for handling tokens in any project, even if you don’t plan to make it public. This reduces the risk of accidentally exposing confidential data.

pip install python-dotenv

You can also install any other dependencies as needed.

Step 3: Initialize Your Chatbot via BotFather

This is a simple step, but it often causes confusion. We need to interact with a Telegram bot that will generate and provide us with a token for our project.

Open Telegram and start a chat with @BotFather.
Click the Start button.
The bot will send a welcome message. Enter the following command:

/newbot

BotFather will ask for a name for your bot—this is what users will see in their chat list.
Then, enter a username for your bot. It must be unique and end with "bot" (e.g., mycoolbot).
Once completed, BotFather will create your chatbot, assign it a username, and provide you with a token.

Keep your token secret. Anyone with access to it can send messages on behalf of your chatbot. If your token is compromised, immediately generate a new one via BotFather.

Next, open a chat with your newly created bot and configure the following:

Click the Edit button.
Update the profile picture.
Set a welcome message.
Add a description.
Configure default commands.

Step 4: Store Your Token Securely

Create an environment file named .env (this file has no name, only an extension). Add the following line:

BOT_TOKEN = your_generated_token

On Linux and macOS, you can quickly save the token using the following command:

echo "BOT_TOKEN = your_generated_token" > .env

Step 4: Create the Script

In your working directory, create a file called main.py—this will be the main script for your chatbot.

Now, import the following test code, which will send a welcome message to the user when they enter the /start command:

import asyncio  # Library for handling asynchronous code
import os  # Module for working with environment variables
from dotenv import load_dotenv  # Function to load environment variables from the .env file
from aiogram import Bot, Dispatcher, Router  # Import necessary classes from aiogram
from aiogram.types import Message  # Import Message class for handling incoming messages
from aiogram.filters import CommandStart  # Import filter for handling the /start command
 
# Create a router to store message handlers
router = Router()
 
# Load environment variables from .env
load_dotenv()
 
# Handler for the /start command
@router.message(CommandStart())  # Filter to check if the message is the /start command
async def cmd_start(message: Message) -> None:
    # Retrieve the user's first name and last name (if available)
    first_name = message.from_user.first_name
    last_name = message.from_user.last_name or ""  # If no last name, use an empty string
 
    # Send a welcome message to the user
    await message.answer(f"Hello, {first_name} {last_name}!")
 
# Main asynchronous function to start the bot
async def main():
    # Create a bot instance using the token from environment variables
    bot = Bot(token=os.getenv("BOT_TOKEN"))
 
    # Create a dispatcher to handle messages
    dp = Dispatcher()
 
    # Include the router with command handlers
    dp.include_router(router)
 
    # Start the bot in polling mode
    await dp.start_polling(bot)
 
# If the script is run directly (not imported as a module),
# execute the main() function
if __name__ == "__main__":
    asyncio.run(main())

The script is well-commented to help you understand the essential parts.If you don't want to dive deep, you can simply use Dispatcher and Router as standard components in Aiogram. We will explore their functionality later in this guide.

This ready-made structure can serve as a solid starting point for any chatbot project. As you continue development, you will add more handlers, keyboards, and states.

Step 5: Run and Test the Chatbot

Now, launch your script using the following command:

python main.py

Now you can open a chat with your bot in Telegram and start interacting with it.

Aiogram Framework v3.x Features Overview

You only need to understand a few key components and functions of Aiogram to create a Telegram chatbot.

This section covers Aiogram v3.x, which was released on September 1, 2023. Any version starting with 3.x will work. While older projects using Aiogram 2.x still exist, version 2.x is now considered outdated.

Key Components of Aiogram

Bot

The Bot class serves as the interface to the Telegram API. It allows you to send messages, images, and other data to users.

bot = Bot(token=os.getenv("TOKEN"))

You can pass the token directly when initializing the Bot class, but it's recommended to use environment variables to prevent accidental exposure of your bot token.

Dispatcher

The Dispatcher is the core of the framework. It receives updates (incoming messages and events) and routes them to the appropriate handlers.

dp = Dispatcher()

In Aiogram v3, a new structure with Router is used (see below), but the Dispatcher is still required for initialization and launching the bot.

Router

In Aiogram v3, handlers are grouped within a Router. This is a separate entity that stores the bot's logic—command handlers, message handlers, callback handlers, and more.

from aiogram import Router
router = Router()

After defining handlers inside the router, developers register it with the Dispatcher:

dp.include_router(router)

Handling Commands

The most common scenario is responding to commands like /start or /help.

from aiogram import F
from aiogram.types import Message

@router.message(F.text == "/start")
async def cmd_start(message: Message):
    await message.answer("Hello! I'm a bot running on Aiogram.")

F.text == "/start" is a new filtering method in Aiogram v3.
message.answer(...) sends a reply to the user.

Handling Regular Messages

To react to any message, simply remove the filter or define a different condition:

@router.message()
async def echo_all(message: Message):
    await message.answer(f"You wrote: {message.text}")

In this example, the bot echoes whatever text the user sends.

Inline Buttons and Keyboards

from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup

inline_kb = InlineKeyboardMarkup(
    inline_keyboard=[
        [InlineKeyboardButton(text="Click me!", callback_data="press_button")]
    ]
)

@router.message(F.text == "/buttons")
async def show_buttons(message: Message):
    await message.answer("Here are my buttons:", reply_markup=inline_kb)

When the user clicks the button, the bot receives callback_data="press_button", which can be handled separately:

from aiogram.types import CallbackQuery

@router.callback_query(F.data == "press_button")
async def handle_press_button(callback: CallbackQuery):
    await callback.message.answer("You clicked the button!")
    await callback.answer()  # Removes the "loading" animation in the chat

Regular Buttons (Reply Keyboard)

Regular buttons differ from inline buttons in that they replace the keyboard. The user immediately sees a list of available response options. These buttons are tracked by the message text, not callback_data.

from aiogram.types import ReplyKeyboardMarkup, KeyboardButton, ReplyKeyboardRemove

# Creating a reply keyboard
reply_kb = ReplyKeyboardMarkup(
    keyboard=[
        [
            KeyboardButton(text="View Menu"),
            KeyboardButton(text="Place Order")
        ]
    ],
    resize_keyboard=True  # Automatically adjusts button size
)

# Handling the /start command and showing the reply keyboard
@router.message(F.text == "/start")
async def start_cmd(message: Message):
    await message.answer(
        "Welcome! Choose an action:",
        reply_markup=reply_kb
    )

# Handling "View Menu" button press
@router.message(F.text == "View Menu")
async def show_menu(message: Message):
    await message.answer("We have pizza and drinks.")

# Handling "Place Order" button press
@router.message(F.text == "Place Order")
async def make_order(message: Message):
    await message.answer("What would you like to order?")

# Command to hide the keyboard
@router.message(F.text == "/hide")
async def hide_keyboard(message: Message):
    await message.answer("Hiding the keyboard", reply_markup=ReplyKeyboardRemove())

Filters and Middlewares

Filters

Filters help define which messages should be processed. You can also create custom filters.

from aiogram.filters import Filter

# Custom filter to check if a user is an admin
class IsAdmin(Filter):
    def __init__(self, admin_id: int):
        self.admin_id = admin_id

    async def __call__(self, message: Message) -> bool:
        return message.from_user.id == self.admin_id

# Using the filter to restrict a command to the admin
@router.message(IsAdmin(admin_id=12345678), F.text == "/admin")
async def admin_cmd(message: Message):
    await message.answer("Hello, Admin! You have special privileges.")

Middlewares

Middlewares act as intermediary layers between an incoming request and its handler. You can use them to intercept, modify, validate, or log messages before they reach their respective handlers.

import logging
from aiogram.types import CallbackQuery, Message
from aiogram.dispatcher.middlewares.base import BaseMiddleware

# Custom middleware to log incoming messages and callbacks
class LoggingMiddleware(BaseMiddleware):
    async def __call__(self, handler, event, data):
        if isinstance(event, Message):
            logging.info(f"[Message] from {event.from_user.id}: {event.text}")
        elif isinstance(event, CallbackQuery):
            logging.info(f"[CallbackQuery] from {event.from_user.id}: {event.data}")

        # Pass the event to the next handler
        return await handler(event, data)

async def main():
    load_dotenv()
    logging.basicConfig(level=logging.INFO)

    bot = Bot(token=os.getenv("BOT_TOKEN"))
    dp = Dispatcher()

    # Attaching the middleware
    dp.update.middleware(LoggingMiddleware())

    dp.include_router(router)
    await dp.start_polling(bot)

Working with States (FSM) in Aiogram 3

Aiogram 3 supports Finite State Machine (FSM), which is useful for step-by-step data collection (e.g., user registration, order processing). FSM is crucial for implementing multi-step workflows where users must complete one step before moving to the next.

For example, in a pizza ordering bot, we need to ask the user for pizza size and delivery address, ensuring the process is sequential. We must save each step's data until the order is complete.

Step 1: Declare States

from aiogram.fsm.state import State, StatesGroup

class OrderPizza(StatesGroup):
    waiting_for_size = State()
    waiting_for_address = State()

These states define different stages in the ordering process.

Step 2: Switch between states

from aiogram.fsm.context import FSMContext

@router.message(F.text == "/order")
async def cmd_order(message: Message, state: FSMContext):
    # Create inline buttons for selecting pizza size
    size_keyboard = InlineKeyboardMarkup(
        inline_keyboard=[
            [
                InlineKeyboardButton(text="Large", callback_data="size_big"),
                InlineKeyboardButton(text="Medium", callback_data="size_medium"),
                InlineKeyboardButton(text="Small", callback_data="size_small")
            ]
        ]
    )

    await message.answer(
        "What size pizza would you like? Click one of the buttons:",
        reply_markup=size_keyboard
    )
    # Set the state to wait for the user to choose a size
    await state.set_state(OrderPizza.waiting_for_size)

# Step 2: Handle button click for size selection
@router.callback_query(OrderPizza.waiting_for_size, F.data.startswith("size_"))
async def choose_size_callback(callback: CallbackQuery, state: FSMContext):
    # Callback data can be size_big / size_medium / size_small
    size_data = callback.data.split("_")[1]  # e.g., "big", "medium", or "small"

    # Save the selected pizza size in the temporary state storage
    await state.update_data(pizza_size=size_data)

    # Confirm the button press (removes "loading clock" in Telegram's UI)
    await callback.answer()

    await callback.message.answer("Please enter your delivery address:")
    await state.set_state(OrderPizza.waiting_for_address)

# Step 2a: If the user sends a message instead of clicking a button (in waiting_for_size state),
# we can handle it separately. For example, prompt them to use the buttons.
@router.message(OrderPizza.waiting_for_size)
async def handle_text_during_waiting_for_size(message: Message, state: FSMContext):
    await message.answer(
        "Please select a pizza size using the buttons above. "
        "We cannot proceed without this information."
    )

# Step 3: User sends the delivery address
@router.message(OrderPizza.waiting_for_address)
async def set_address(message: Message, state: FSMContext):
    address = message.text
    user_data = await state.get_data()
    pizza_size = user_data["pizza_size"]

    size_text = {
        "big": "large",
        "medium": "medium",
        "small": "small"
    }.get(pizza_size, "undefined")

    await message.answer(f"You have ordered a {size_text} pizza to be delivered at: {address}")
    # Clear the state — the process is complete
    await state.clear()

Notice how the temporary storage keeps track of user responses at each step. This storage is user-specific and does not require a database.

The user progresses through a chain of questions, and at the end, the order details can be sent to an internal API.

Deploying the Bot: Running on a Server

Let's go through two main deployment methods.

Quick Method: Docker + Hostman App Platform

This method does not require any system administration knowledge; the entire deployment process is automated. Additionally, it helps save costs. Follow these steps:

Export all project dependencies to a requirements.txt file. Using a virtual environment is recommended to avoid pulling in libraries from the entire system. Run the following command in the project directory terminal:

pip freeze > requirements.txt

Add a deployment file to the project directory — Dockerfile. This file has no extension, just the name. Insert the following content:

FROM python:3.11
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 9999
CMD ["python", "main.py"]

Create a Git repository and push it to GitHub. You can use a minimal set of Git commands from our guide by running these commands in sequence. Add the environment variables file (.env) to .gitignore to prevent it from being exposed publicly.
Go to the Hostman control panel, select the App platform section, and click Create app. Go to the Docker tab and select Dockerfile.

Link your GitHub account or connect your Git repository via URL.
Select the repository from the list after linking your GitHub account.
Choose a configuration. Hostman Apps offers a configuration of 1 CPU x 3.3GHz, 1GB RAM, NVMe storage, which is ideal for simple text-based bots, projects with small inline keyboards, basic FSM logic, low-demand API requests, working with SQLite, or lightweight JSON files. This configuration can handle 50-100 users per minute.
Add the bot token to environment variables. In the App settings, click + Add, enter BOT_TOKEN as the key, and paste the token obtained from BotFather as the value.
Start the deployment and wait for it to complete. Once finished, the bot will be up and running.

Standard Method: Ubuntu + systemd

Export all project dependencies to the requirements.txt file. Run the following command in the Terminal while in the project directory:

pip freeze > requirements.txt

Create a cloud server in the Hostman panel with the desired configuration and Ubuntu OS.

Transfer project files to the directory on the remote server. The easiest way to do this is using the rsync utility if you're using Ubuntu/MacOS:

rsync -av --exclude="venv" --exclude=".idea" --exclude=".git" ./ root@176.53.160.13:/root/project

Don’t forget to replace the server IP and correct the destination directory.

Windows users can use FileZilla to transfer files.

Connect to the server via SSH.
Install the package for virtual environments:

sudo apt install python3.10-venv

Navigate to the project directory where you transferred the files. Create a virtual environment and install the dependencies:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Test the bot functionality by running it:

python main.py

If everything works, proceed to the next step.

Create the unit file /etc/systemd/system/telegram-bot.service:

sudo nano /etc/systemd/system/telegram-bot.service

Add the following content to the file:

[Unit]
Description=Telegram Bot Service
After=network.target

[Service]
User=root
WorkingDirectory=/root/project
ExecStart=/root/proj/venv/bin/python /root/proj/main.py
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target

WorkingDirectory — the project directory
ExecStart — the command to start the chatbot in the format <interpreter> <full path to the file>.

If using a virtual environment, the path to the interpreter will be as in the example. If working without venv, use /usr/local/bin/python3.

Reload systemd and enable the service:

sudo systemctl daemon-reload
sudo systemctl enable telegram-bot.service
sudo systemctl start telegram-bot.service

Check the status of the service and view logs if necessary:

sudo systemctl status telegram-bot.service

If the bot is running correctly, the Active field should show active (running).

View bot logs:

sudo journalctl -u telegram-bot.service -f

Manage the service with the following commands:

Restart the bot:

sudo systemctl restart telegram-bot.service

Stop the bot:

sudo systemctl stop telegram-bot.service

Remove the service (if needed):

sudo systemctl disable telegram-bot.service
sudo rm /etc/systemd/system/telegram-bot.service
sudo systemctl daemon-reload

Conclusion

Creating a Telegram chatbot in Python is a task that can be accomplished even without programming experience using bot builders. However, if you need flexibility and more options, it's better to master the aiogram framework and deploy your own project. This gives you full control over the code, the ability to enhance functionality, manage integrations, and avoid the limitations of paid plans.

To run the bot in production, simply choose an appropriate configuration on the Hostman App Platform and set up automatic deployment. Pay attention to security by storing the token in an environment variable and encrypting sensitive data. In the future, you can scale the bot, add webhook support, integrate payment systems and analytics systems, and work with ML models if AI features are required.