ساخت ربات تلگرام: آموزش قدم‌به‌قدم از BotFather تا اولین پیام با Python

به‌روزرسانی: ۷ آبان ۱۴۰۵ · 7 دقیقه مطالعه

برای ساخت ربات تلگرام کافی است به ‎@BotFather پیام بدهید، دستور ‎/newbot را بفرستید، یک نام و یک نام کاربری که به bot ختم می‌شود انتخاب کنید و توکنی را که دریافت می‌کنید نگه دارید. با همین توکن هر متد Bot API را از طریق HTTPS صدا می‌زنید. در این آموزش ساخت ربات تلگرام، ربات را قدم‌به‌قدم می‌سازیم، توکن را تست می‌کنیم و اولین پیام را با curl و Python می‌فرستیم.

پیش‌نیازها

• یک حساب تلگرام (اپ موبایل، دسکتاپ یا نسخه وب).
• ترمینال با curl، یا Python 3 همراه کتابخانه requests (pip install requests).
• برای اجرای دائمی ربات، سروری که به api.telegram.org دسترسی داشته باشد. برای تست‌های این آموزش سرور لازم نیست.

ساخت ربات تلگرام در BotFather

BotFather ربات رسمی خود تلگرام برای ساخت و مدیریت ربات‌هاست؛ اگر دنبال «ربات ساز تلگرام» هستید، نقطه شروع همین‌جاست:

1. ‎@BotFather را باز کنید و Start را بزنید. دقت کنید نام کاربری دقیقاً همین باشد، نه ربات جعلی با اسم مشابه.
2. دستور ‎/newbot را بفرستید.
3. نام (name) را وارد کنید. این نام در لیست چت‌ها و پروفایل دیده می‌شود، می‌تواند فارسی باشد و بعداً با ‎/setname عوض می‌شود.
4. نام کاربری (username) را انتخاب کنید: 5 تا 32 کاراکتر، فقط حروف لاتین، عدد و زیرخط، و حتماً با bot تمام شود؛ مثل tetris_bot یا TetrisBot. برخلاف نام، نام کاربری بعداً قابل تغییر نیست.
5. BotFather پیامی با لینک ربات (t.me/your_bot) و توکن آن می‌فرستد. توکن را کپی کنید و جای امنی نگه دارید.

اگر نام کاربری قبلاً گرفته شده باشد، BotFather آن را نمی‌پذیرد و باید نام دیگری امتحان کنید. همه این تنظیمات در Mini App خود BotFather هم با رابط گرافیکی در دسترس است. بیشتر سرویس‌های ربات‌ساز آماده و ابزارهای اتوماسیون هم در نهایت همین توکن را از شما می‌خواهند.

توکن ربات و نگهداری امن آن

توکن رشته‌ای مثل 123456789:AAEexampleTokenReplaceWithYours است: عدد قبل از دونقطه شناسه ربات است و بخش بعدی کلید مخفی آن. هر کس توکن را داشته باشد کنترل کامل ربات را دارد؛ پس آن را در کد سمت کاربر، اسکرین‌شات یا مخزن عمومی گیت‌هاب نگذارید و در متغیر محیطی نگه دارید. اگر توکن لو رفت، با ‎/revoke در BotFather باطلش کنید. جزئیات بیشتر در راهنمای توکن ربات تلگرام آمده است.

تست توکن با متد getMe

قبل از نوشتن هر کدی مطمئن شوید توکن درست است. متد getMe پارامتری ندارد و اطلاعات خود ربات را برمی‌گرداند:

curl https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe

پاسخ موفق (خلاصه‌شده):

{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "ربات تست من",
    "username": "my_test_bot",
    "can_join_groups": true,
    "can_read_all_group_messages": false
  }
}

به کلمه bot که بلافاصله قبل از توکن در آدرس آمده دقت کنید. اگر خطای 401 با توضیح Unauthorized گرفتید، توکن اشتباه کپی شده یا باطل شده است. بدون ترمینال هم می‌توانید توکن را در متد getMe در Bot API Tester امتحان کنید؛ توکن در localStorage مرورگر خودتان می‌ماند و درخواست مستقیم به api.telegram.org می‌رود.

ارسال اولین پیام با ربات

ربات‌ها نمی‌توانند شروع‌کننده گفتگو باشند؛ اول شما باید به ربات پیام بدهید:

1. لینک ربات (t.me/your_bot) را باز کنید و Start را بزنید یا ‎/start را بفرستید.
2. متد getUpdates را صدا بزنید و در پاسخ، مقدار message.chat.id را پیدا کنید؛ این چت آیدی شماست.
3. با متد sendMessage به همان چت آیدی پیام بفرستید.

curl https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getUpdates

{"ok": true, "result": [{"update_id": 100000001, "message": {
  "message_id": 1,
  "from": {"id": 123456789, "is_bot": false, "first_name": "علی"},
  "chat": {"id": 123456789, "first_name": "علی", "type": "private"},
  "date": 1793266200, "text": "/start"}}]}

ارسال پیام با curl:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 123456789, "text": "Hello from my first bot"}'

همین کار با Python و کتابخانه requests:

import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
CHAT_ID = 123456789

resp = requests.post(
    f"https://api.telegram.org/bot{TOKEN}/sendMessage",
    json={"chat_id": CHAT_ID, "text": "سلام! این اولین پیام ربات من است."},
    timeout=10,
)
print(resp.json())

اگر result خالی بود، دوباره به ربات پیام بدهید و درخواست را تکرار کنید. خطای 400 با متن Bad Request: chat not found یعنی چت آیدی اشتباه است یا هنوز ربات را استارت نکرده‌اید. اگر درخواست‌ها به timeout می‌خورند، شبکه یا سرور شما به api.telegram.org دسترسی ندارد. روش‌های دیگر در راهنمای چت آیدی تلگرام و جزئیات قالب‌بندی و دکمه‌ها در آموزش ارسال پیام با ربات تلگرام آمده است.

ساخت ربات تلگرام با پایتون: یک ربات ساده

این اسکریپت بدون کتابخانه اضافه، با long polling پیام‌ها را می‌گیرد و همان متن را برمی‌گرداند:

import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
offset = 0

while True:
    data = requests.get(f"{API}/getUpdates",
                        params={"offset": offset, "timeout": 30},
                        timeout=40).json()
    if not data["ok"]:
        print(data)
        time.sleep(5)
        continue
    for update in data["result"]:
        offset = update["update_id"] + 1
        msg = update.get("message")
        if msg and "text" in msg:
            requests.post(f"{API}/sendMessage", json={
                "chat_id": msg["chat"]["id"],
                "text": "شما نوشتید: " + msg["text"],
            }, timeout=10)

پارامتر timeout درخواست را تا 30 ثانیه باز نگه می‌دارد تا آپدیت جدید برسد. مقدار offset برابر آخرین update_id به‌علاوه 1 است و آپدیت‌های پردازش‌شده را تأیید می‌کند؛ بدون آن همان آپدیت‌ها دوباره برمی‌گردند.

توضیحات و دستورهای ربات

• ‎/setdescription: متنی که کاربر قبل از زدن Start در چت خالی می‌بیند (تا 512 کاراکتر).
• ‎/setabouttext: معرفی کوتاه در پروفایل ربات (تا 120 کاراکتر).
• ‎/setuserpic: عکس پروفایل ربات.
• ‎/setcommands: لیست دستورهایی که با تایپ / پیشنهاد می‌شوند؛ هر خط به شکل command - description.

همین لیست را با متد setMyCommands هم می‌توانید از داخل کد تنظیم کنید:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"commands": [{"command": "start", "description": "Start"}, {"command": "help", "description": "Help"}], "language_code": "en"}'

نام هر دستور 1 تا 32 کاراکتر و فقط شامل حروف کوچک انگلیسی، عدد و زیرخط است و توضیح آن 1 تا 256 کاراکتر؛ حداکثر 100 دستور مجاز است. با language_code برابر fa می‌توانید برای کاربران فارسی‌زبان لیست جداگانه‌ای با توضیحات فارسی بسازید.

قدم‌های بعدی: polling یا وب‌هوک، کتابخانه‌ها و Mini App

• getUpdates یا وب‌هوک: long polling برای شروع ساده‌تر است؛ در وب‌هوک، تلگرام آپدیت‌ها را مستقیم به سرور HTTPS شما می‌فرستد. این دو روش هم‌زمان کار نمی‌کنند. راهنما: راه‌اندازی وب‌هوک ربات تلگرام.
• کتابخانه‌ها: در Python کتابخانه‌های python-telegram-bot، aiogram و pyTelegramBotAPI؛ در Node.js کتابخانه‌های grammY و Telegraf؛ در Go کتابخانه‌های telebot و go-telegram-bot-api. همه روی همین Bot API ساخته شده‌اند.
• Mini App: برای رابط کاربری وب داخل تلگرام، Mini App بسازید و آن را در Mini App Tester امتحان کنید.
• مرجع: همه متدها در مرجع متدهای Bot API (انگلیسی) و مستندات Swagger فهرست شده‌اند.