POST https://api.telegram.org/bot<TOKEN>/sendMessage

bot.send_message(chat_id, "سلام!")

from telebot import TeleBot

bot = TeleBot("BOT_TOKEN")

@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "سلام! به ربات خوش آمدید.")

bot.infinity_polling()

pip install pyTelegramBotAPI

import telebot

bot = telebot.TeleBot("BOT_TOKEN")

from telebot import TeleBot

bot = TeleBot("BOT_TOKEN")

import os
import telebot

TOKEN = os.environ["BOT_TOKEN"]

bot = telebot.TeleBot(TOKEN)

export BOT_TOKEN="123456:ABC..."

import os
import telebot

bot = telebot.TeleBot(os.environ["BOT_TOKEN"])


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(
        message,
        "سلام 👋\nبه ربات ما خوش آمدید."
    )


bot.infinity_polling()

@bot.message_handler(commands=["start"])

@bot.message_handler(content_types=["text"])
def handle_text(message):
    print(message.text)

    bot.reply_to(
        message,
        f"شما نوشتید: {message.text}"
    )

سلام

شما نوشتید: سلام

@bot.message_handler(content_types=["text"])
def handle_text(message):
    print(message.text)
    print(message.chat.id)
    print(message.from_user.id)
    print(message.from_user.first_name)

bot.send_message(
    message.chat.id,
    "سلام!"
)

bot.reply_to(
    message,
    "سلام!"
)

/start
/help
/about

@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "ربات شروع به کار کرد.")


@bot.message_handler(commands=["help"])
def help_command(message):
    bot.reply_to(
        message,
        "دستورهای موجود:\n"
        "/start - شروع\n"
        "/help - راهنما\n"
        "/about - درباره ربات"
    )


@bot.message_handler(commands=["about"])
def about(message):
    bot.reply_to(
        message,
        "این ربات با Python ساخته شده است."
    )

@bot.message_handler(content_types=["text"])
def handle_message(message):

    if message.text == "سلام":
        bot.reply_to(message, "سلام! 👋")

    elif message.text == "خداحافظ":
        bot.reply_to(message, "خداحافظ!")

    else:
        bot.reply_to(
            message,
            "متوجه پیام شما نشدم."
        )

def process_text(text):
    if text == "سلام":
        return "سلام! 👋"

    if text == "خداحافظ":
        return "خداحافظ!"

    return "پیام نامشخص."


@bot.message_handler(content_types=["text"])
def handle_message(message):
    response = process_text(message.text)
    bot.reply_to(message, response)

from telebot import types

keyboard = types.ReplyKeyboardMarkup(
    resize_keyboard=True
)

keyboard.add("درباره ما")
keyboard.add("تماس با ما")

bot.send_message(
    message.chat.id,
    "یک گزینه را انتخاب کنید:",
    reply_markup=keyboard
)

keyboard = types.InlineKeyboardMarkup()

button = types.InlineKeyboardButton(
    "وب‌سایت",
    url="https://example.com"
)

keyboard.add(button)

bot.send_message(
    message.chat.id,
    "برای ورود کلیک کنید:",
    reply_markup=keyboard
)

keyboard = types.InlineKeyboardMarkup()

button = types.InlineKeyboardButton(
    "نمایش اطلاعات",
    callback_data="show_info"
)

keyboard.add(button)

bot.send_message(
    message.chat.id,
    "یک گزینه را انتخاب کنید:",
    reply_markup=keyboard
)

@bot.callback_query_handler(
    func=lambda call: call.data == "show_info"
)
def show_info(call):

    bot.answer_callback_query(call.id)

    bot.send_message(
        call.message.chat.id,
        "این اطلاعات توسط ربات تولید شده است."
    )

callback_data="show_info"

import os
import telebot
from telebot import types

bot = telebot.TeleBot(os.environ["BOT_TOKEN"])


def main_menu():
    keyboard = types.InlineKeyboardMarkup()

    keyboard.add(
        types.InlineKeyboardButton(
            "📚 راهنما",
            callback_data="help"
        )
    )

    keyboard.add(
        types.InlineKeyboardButton(
            "ℹ️ درباره ما",
            callback_data="about"
        )
    )

    return keyboard


@bot.message_handler(commands=["start"])
def start(message):
    bot.send_message(
        message.chat.id,
        "به ربات خوش آمدید.",
        reply_markup=main_menu()
    )


@bot.callback_query_handler(func=lambda call: True)
def callback(call):

    if call.data == "help":
        text = "راهنمای ربات در این قسمت قرار می‌گیرد."

    elif call.data == "about":
        text = "این ربات با Python نوشته شده است."

    else:
        text = "گزینه نامعتبر است."

    bot.answer_callback_query(call.id)

    bot.send_message(
        call.message.chat.id,
        text
    )


bot.infinity_polling()

@bot.message_handler(
    content_types=["document"]
)
def handle_document(message):

    file_info = bot.get_file(
        message.document.file_id
    )

    downloaded_file = bot.download_file(
        file_info.file_path
    )

    with open(
        "received_file",
        "wb"
    ) as file:
        file.write(downloaded_file)

    bot.reply_to(
        message,
        "فایل دریافت شد."
    )

User
  │
  │ ارسال فایل
  ▼
Telegram API
  │
  ▼
TeleBot
  │
  ├── get_file()
  │
  └── download_file()
  │
  ▼
Python Application

import pandas as pd
from io import BytesIO


@bot.message_handler(
    content_types=["document"]
)
def handle_csv(message):

    file_info = bot.get_file(
        message.document.file_id
    )

    data = bot.download_file(
        file_info.file_path
    )

    df = pd.read_csv(
        BytesIO(data)
    )

    rows = len(df)

    bot.reply_to(
        message,
        f"فایل دریافت شد.\nتعداد ردیف‌ها: {rows}"
    )

@bot.message_handler(
    content_types=["photo"]
)
def handle_photo(message):

    photo = message.photo[-1]

    file_info = bot.get_file(
        photo.file_id
    )

    image = bot.download_file(
        file_info.file_path
    )

    with open(
        "image.jpg",
        "wb"
    ) as file:
        file.write(image)

    bot.reply_to(
        message,
        "تصویر دریافت شد."
    )

message.photo[-1]

with open("image.jpg", "rb") as photo:
    bot.send_photo(
        message.chat.id,
        photo
    )

with open("report.pdf", "rb") as document:
    bot.send_document(
        message.chat.id,
        document
    )

نام خود را وارد کنید:

شماره تلفن خود را وارد کنید:

شهر خود را وارد کنید:

START
  │
  ▼
WAITING_FOR_NAME
  │
  ▼
WAITING_FOR_PHONE
  │
  ▼
WAITING_FOR_CITY
  │
  ▼
COMPLETED

user_states = {}

user_states[12345] = "WAITING_FOR_NAME"

user_id = message.from_user.id

state = user_states.get(user_id)

if state == "WAITING_FOR_NAME":
    ...

bot.py

project/
│
├── bot.py
├── config.py
│
├── handlers/
│   ├── start.py
│   ├── messages.py
│   ├── callbacks.py
│   └── files.py
│
├── services/
│   ├── user_service.py
│   └── file_service.py
│
├── database/
│   ├── models.py
│   └── repository.py
│
└── requirements.txt

bot = Bot(TOKEN)

bot.send_message(...)

@bot.message_handler(...)
def handler(message):
    ...

                    ┌──────────────┐
                    │ Business     │
                    │ Logic        │
                    └──────┬───────┘
                           │
              ┌────────────┴────────────┐
              │                         │
       ┌──────▼──────┐           ┌──────▼──────┐
       │ Telegram    │           │ Bale        │
       │ Adapter     │           │ Adapter     │
       └──────┬──────┘           └──────┬──────┘
              │                         │
       Telegram API                Bale API

def calculate_order_total(order):
    ...

@bot.message_handler(commands=["price"])
def price(message):

    product = get_product("laptop")

    bot.reply_to(
        message,
        f"قیمت: {product.price}"
    )

def get_product_price(product_id):
    product = product_repository.get(product_id)

    return product.price

@bot.message_handler(commands=["price"])
def price(message):

    price = get_product_price("laptop")

    bot.reply_to(
        message,
        f"قیمت محصول: {price}"
    )

TOKEN = "123456789:ABCDEF..."

import os

TOKEN = os.getenv("BOT_TOKEN")

export BOT_TOKEN="..."

.env

@bot.message_handler(commands=["calculate"])
def calculate(message):

    try:
        result = 100 / 0

        bot.reply_to(
            message,
            str(result)
        )

    except Exception:
        bot.reply_to(
            message,
            "در پردازش درخواست خطایی رخ داد."
        )

import logging

logging.basicConfig(
    level=logging.INFO
)

logger = logging.getLogger(__name__)

try:
    ...
except Exception:
    logger.exception(
        "Error while processing message"
    )

Polling
Webhook

آیا پیام جدیدی آمده؟
        ↓
      بله/خیر
        ↓
دوباره بررسی کن

bot.infinity_polling()

User
  │
  ▼
Telegram/Bale
  │
  │ HTTP POST
  ▼
Our Server
  │
  ▼
Bot Application

bot.infinity_polling()

                ┌──────────────┐
                │ Telegram/Bale│
                └───────┬──────┘
                        │
                        ▼
                ┌──────────────┐
                │ Bot Handlers │
                └───────┬──────┘
                        │
                        ▼
                ┌──────────────┐
                │ Application  │
                │ Services     │
                └───────┬──────┘
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
        ┌──────────┐        ┌──────────┐
        │ Database │        │ External │
        │          │        │ APIs     │
        └──────────┘        └──────────┘

@bot.message_handler(commands=["start"])
def start(message):

    bot.send_message(
        message.chat.id,
        "لطفاً نام خود را وارد کنید."
    )

user_state = {}

user_state[message.from_user.id] = {
    "step": "name"
}

@bot.message_handler(content_types=["text"])
def handle_text(message):

    user_id = message.from_user.id

    state = user_state.get(user_id)

    if not state:
        bot.reply_to(
            message,
            "لطفاً ابتدا /start را ارسال کنید."
        )
        return

    if state["step"] == "name":

        state["name"] = message.text
        state["step"] = "city"

        bot.reply_to(
            message,
            "نام ثبت شد. حالا شهر خود را وارد کنید."
        )

    elif state["step"] == "city":

        state["city"] = message.text

        bot.reply_to(
            message,
            "اطلاعات شما با موفقیت دریافت شد."
        )

        del user_state[user_id]

user_state = {}

PostgreSQL
Redis
SQLite
MongoDB

def calculate_discount(price, percent):
    return price * (1 - percent / 100)

def test_calculate_discount():
    assert calculate_discount(
        1000,
        20
    ) == 800

telegram_bot/
│
├── app/
│   ├── handlers/
│   │   ├── start.py
│   │   ├── user.py
│   │   ├── admin.py
│   │   └── callbacks.py
│   │
│   ├── services/
│   │   ├── users.py
│   │   ├── orders.py
│   │   └── payments.py
│   │
│   ├── repositories/
│   │   ├── users.py
│   │   └── orders.py
│   │
│   ├── models/
│   │   └── user.py
│   │
│   └── config.py
│
├── tests/
│
├── bot.py
├── requirements.txt
└── .env

TOKEN = "REAL_TOKEN"

TOKEN = os.environ["BOT_TOKEN"]

@bot.message_handler(...)
def handler(message):

    # database
    # business logic
    # API request
    # calculations
    # formatting
    # response

@bot.message_handler(...)
def handler(message):

    result = service.process(
        message.text
    )

    bot.reply_to(
        message,
        result
    )

for user in users:
    bot.send_message(...)

                    Load Balancer
                         │
             ┌───────────┼───────────┐
             ▼           ▼           ▼
           Bot 1       Bot 2       Bot 3
             │           │           │
             └───────────┼───────────┘
                         ▼
                       Redis
                         │
                         ▼
                    Message Queue
                         │
             ┌───────────┴───────────┐
             ▼                       ▼
         Worker 1                 Worker 2
             │                       │
             └───────────┬───────────┘
                         ▼
                     PostgreSQL

Message
   ↓
Handler
   ↓
Business Logic
   ↓
Response

import os
import telebot

bot = telebot.TeleBot(
    os.environ["BOT_TOKEN"]
)


@bot.message_handler(
    commands=["start"]
)
def start(message):

    bot.reply_to(
        message,
        "سلام! 👋"
    )


@bot.message_handler(
    content_types=["text"]
)
def text(message):

    bot.reply_to(
        message,
        f"شما گفتید: {message.text}"
    )


bot.infinity_polling()