Telegram Bot API

دیپلوی ربات تلگرام: راه‌اندازی روی VPS، داکر و هاست Serverless

· 9 دقیقه مطالعه

برای دیپلوی ربات تلگرام، کد آن را روی ماشینی اجرا کنید که همیشه روشن است و به api.telegram.org دسترسی دارد، بعد روش دریافت آپدیت را انتخاب کنید: long polling با getUpdates که روی هر سروری بدون دامنه کار می‌کند، یا وب هوک که به یک آدرس HTTPS عمومی نیاز دارد. برای ربات‌های polling معمولاً یک VPS کوچک با systemd یا یک کانتینر داکر انتخاب می‌شود و پلتفرم‌های serverless مثل Cloudflare Workers برای ربات‌های وب هوکی مناسب‌اند. در این راهنما هر گزینه را با کانفیگ آماده‌ی کپی، به‌علاوه‌ی لاگ، ری‌استارت خودکار و چک‌لیست راه‌اندازی می‌بینید.

polling یا وب هوک روی سرور

تلگرام دو روش دریافت آپدیت دارد که هم‌زمان قابل استفاده نیستند، و در هر دو حالت آپدیت‌های تحویل‌نشده حداکثر 24 ساعت نگه داشته می‌شوند. این انتخاب تعیین می‌کند هاست ربات تلگرام شما به چه چیزی نیاز دارد:

Long polling (getUpdates)وب هوک (setWebhook)
شبکهفقط HTTPS خروجی؛ پشت NAT هم کار می‌کندآدرس HTTPS عمومی، پورت 443، 80، 88 یا 8443، IPv4
پروسسحلقه‌ی همیشه در حال اجراهندلر HTTP؛ می‌تواند serverless باشد
تعداد نمونهدقیقاً یکی برای هر توکنچند نمونه پشت یک URL مشکلی ندارد
هاست مناسبVPS، داکر، سرور خانگیVPS با reverse proxy، Cloudflare Workers، AWS Lambda، Vercel

اگر polling روی ماشین شما کار می‌کند، همان را نگه دارید: خود راهنمای وب هوک تلگرام می‌گوید استفاده از getUpdates هیچ اشکالی ندارد. وقتی به وب هوک بروید که پلتفرم شما آن را الزامی کند یا بخواهید چند نمونه بار را بین خود تقسیم کنند.

یک ربات polling آماده‌ی دیپلوی

کد آماده‌ی production سه ویژگی دارد: توکن را از متغیر محیطی می‌خواند، در stdout لاگ می‌نویسد و به جای کرش کردن، از خطاهای شبکه جان سالم به در می‌برد. این ربات echo هر سه را دارد و هنگام شروع deleteWebhook را صدا می‌زند، چون تا وقتی وب هوک تنظیم است getUpdates کار نمی‌کند:

import logging
import os
import time

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("bot")

TOKEN = os.environ["BOT_TOKEN"]  # هرگز توکن را در کد ننویسید
API = f"https://api.telegram.org/bot{TOKEN}"


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


def main():
    call("deleteWebhook")  # polling و وب هوک هم‌زمان کار نمی‌کنند
    log.info("started as @%s", call("getMe")["username"])
    offset = 0
    while True:
        try:
            updates = call("getUpdates", offset=offset, timeout=30)
        except Exception:
            log.exception("getUpdates failed, retrying in 5 s")
            time.sleep(5)
            continue
        for update in updates:
            offset = update["update_id"] + 1
            msg = update.get("message")
            if msg and "text" in msg:
                try:
                    call("sendMessage", chat_id=msg["chat"]["id"], text="Echo: " + msg["text"])
                except Exception:
                    log.exception("update %s failed", update["update_id"])


if __name__ == "__main__":
    main()
const TOKEN = process.env.BOT_TOKEN; // هرگز توکن را در کد ننویسید
if (!TOKEN) throw new Error("BOT_TOKEN is not set");
const API = `https://api.telegram.org/bot${TOKEN}`;
const log = (...args) => console.log(new Date().toISOString(), ...args);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

await call("deleteWebhook"); // polling و وب هوک هم‌زمان کار نمی‌کنند
log("started as @" + (await call("getMe")).username);

let offset = 0;
while (true) {
  let updates;
  try {
    updates = await call("getUpdates", { offset, timeout: 30 });
  } catch (err) {
    log("getUpdates failed, retrying in 5 s:", err.message);
    await sleep(5000);
    continue;
  }
  for (const update of updates) {
    offset = update.update_id + 1;
    const msg = update.message;
    if (!msg?.text) continue;
    try {
      await call("sendMessage", { chat_id: msg.chat.id, text: "Echo: " + msg.text });
    } catch (err) {
      log(`update ${update.update_id} failed:`, err.message);
    }
  }
}

آن‌ها را با نام bot.py (با requests در requirements.txt) یا bot.mjs (Node.js 18 به بالا، بدون وابستگی) ذخیره کنید. فریم‌ورک‌های لیست کتابخانه‌ها حلقه را خودشان مدیریت می‌کنند، اما مراحل دیپلوی زیر همان می‌ماند.

ربات تلگرام روی VPS با systemd

VPS یک ماشین لینوکسی معمولی در اختیارتان می‌گذارد. بگذارید systemd ربات را هنگام بوت اجرا کند و اگر کرش کرد دوباره راه بیندازد:

  1. یک کاربر بدون دسترسی لاگین بسازید و کد را در /opt/mybot کپی کنید؛ برای پایتون همان‌جا یک virtual environment بسازید و وابستگی‌ها را نصب کنید.
  2. توکن را در /etc/mybot.env به صورت خط BOT_TOKEN=123456789:AAEexampleTokenReplaceWithYours بگذارید و دسترسی را با chmod 600 محدود کنید.
  3. فایل یونیت /etc/systemd/system/mybot.service را بسازید:
[Unit]
Description=Telegram bot
After=network-online.target
Wants=network-online.target

[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/opt/mybot/.venv/bin/python -u bot.py
# Node.js: ExecStart=/usr/bin/node bot.mjs
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

سرویس را فعال کنید و لاگ‌ها را دنبال کنید:

sudo systemctl daemon-reload
sudo systemctl enable --now mybot
journalctl -u mybot -f        # لاگ زنده
sudo systemctl restart mybot  # بعد از به‌روزرسانی کد

برای وب هوک روی همان VPS، ربات را به صورت یک سرور HTTP روی پورت محلی اجرا کنید و nginx یا Caddy را جلوی آن بگذارید تا TLS را روی پورت 443 مدیریت کند؛ آموزش وب هوک تلگرام یک هندلر با بررسی secret token دارد.

دیپلوی ربات تلگرام با داکر

کانتینر محیط اجرا و وابستگی‌ها را بسته‌بندی می‌کند، پس ربات روی لپ‌تاپ شما و روی هر هاست داکری یکسان اجرا می‌شود. یک Dockerfile برای ربات پایتون:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY bot.py .
CMD ["python", "-u", "bot.py"]
# Node.js: FROM node:22-slim, COPY bot.mjs ., CMD ["node", "bot.mjs"]

ایمیج را بسازید و اجرا کنید؛ توکن هنگام اجرا داده می‌شود و هرگز داخل ایمیج قرار نمی‌گیرد:

docker build -t mybot .
docker run -d --name mybot --restart unless-stopped --env-file .env mybot
docker logs -f mybot

--restart unless-stopped ربات را بعد از کرش و ریبوت هاست برمی‌گرداند. فایل .env را بیرون از Git و ایمیج نگه دارید (آن را به .dockerignore اضافه کنید). وقتی ربات polling را دوباره دیپلوی می‌کنید، قبل از شروع کانتینر جدید کانتینر قدیمی را متوقف کنید: دو کانتینر که با یک توکن poll کنند باعث می‌شوند getUpdates با 409 Conflict شکست بخورد.

Serverless: ربات تلگرام روی Cloudflare Workers

پلتفرم‌های serverless کد را فقط با رسیدن درخواست اجرا می‌کنند، پس به حالت وب هوک نیاز دارند. در Cloudflare Workers آدرس پیش‌فرض workers.dev از قبل روی پورت 443 HTTPS ارائه می‌دهد. این Worker هدر secret token را بررسی می‌کند، فوراً جواب می‌دهد و کار را با ctx.waitUntil در پس‌زمینه تمام می‌کند:

// worker.js: با "npx wrangler deploy" دیپلوی کنید
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    if (request.method !== "POST" || url.pathname !== "/telegram/webhook") {
      return new Response("Not found", { status: 404 });
    }
    const enc = new TextEncoder();
    const received = enc.encode(request.headers.get("X-Telegram-Bot-Api-Secret-Token") ?? "");
    const expected = enc.encode(env.WEBHOOK_SECRET);
    if (received.byteLength !== expected.byteLength ||
        !crypto.subtle.timingSafeEqual(received, expected)) {
      return new Response("Forbidden", { status: 403 });
    }
    const update = await request.json();
    ctx.waitUntil(handleUpdate(update, env)); // الان 200 برگردان، کار را ادامه بده
    return new Response("OK");
  },
};

async function handleUpdate(update, env) {
  const msg = update.message;
  if (!msg?.text) return;
  const res = await fetch(`https://api.telegram.org/bot${env.BOT_TOKEN}/sendMessage`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ chat_id: msg.chat.id, text: "Echo: " + msg.text }),
  });
  if (!res.ok) console.error("sendMessage failed", res.status, await res.text());
}

هر دو مقدار را به صورت Worker secret ذخیره کنید، دیپلوی کنید و بعد آدرس Worker را با همان secret ثبت کنید:

npx wrangler secret put BOT_TOKEN
npx wrangler secret put WEBHOOK_SECRET
npx wrangler deploy

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mybot.example.workers.dev/telegram/webhook", "secret_token": "replace-with-your-random-secret"}'

یا فرم setWebhook در Bot API Tester را پر کنید. همین الگو روی AWS Lambda (پشت یک function URL با HTTPS یا API gateway) و توابع Vercel هم کار می‌کند: بدنه‌ی JSON را پارس کنید، هدر را بررسی کنید و سریع 2XX برگردانید. پلتفرم‌ها زمان اجرای تابع و کارهای پس‌زمینه‌ی آن را محدود می‌کنند، پس کارهای کند را به یک صف منتقل کنید. تلگرام هر پاسخ غیر 2XX را دوباره تلاش می‌کند، پس تابعی که تایم‌اوت یا کرش کند همان آپدیت را دوباره دریافت می‌کند.

روش‌های رایگان و کم‌هزینه برای هاست ربات تلگرام

پیش‌نیازهای وب هوک روی هر هاستی

بعد از هر دیپلوی، getWebhookInfo را در Bot API Tester باز کنید: اگر pending_update_count بالا می‌رود یا last_error_message تازه‌ای دارید، تلگرام نمی‌تواند آپدیت‌ها را تحویل دهد.

متغیرهای محیطی، لاگ و ری‌استارت

چک‌لیست دیپلوی

  1. توکن از متغیر محیطی یا secret خوانده می‌شود؛ getMe روی سرور موفق است.
  2. برای هر توکن دقیقاً یک نمونه‌ی polling، یا یک وب هوک با secret_token؛ هرگز هر دو.
  3. پروسس بعد از کرش و ریبوت خودکار دوباره اجرا می‌شود.
  4. لاگ‌ها جمع‌آوری می‌شوند و توکنی در آن‌ها نیست.
  5. خطا در یک آپدیت لاگ می‌شود و کل ربات را از کار نمی‌اندازد؛ هندلرهای وب هوک سریع 2XX برمی‌گردانند.
  6. برای وب هوک، getWebhookInfo آدرس درست و بدون خطای اخیر نشان می‌دهد.
  7. برای آزمایش از یک ربات تست جداگانه یا سرور تست تلگرام استفاده می‌شود، نه توکن production.

رفع مشکلات دیپلوی

نشانهعلت و راه‌حل
409 Conflict: terminated by other getUpdates requestدو نمونه با یک توکن poll می‌کنند (کانتینر قدیمی، لپ‌تاپ شما). همه به جز یکی را متوقف کنید.
409 Conflict با اشاره به وب هوک فعالوب هوک هنوز تنظیم است. قبل از polling، deleteWebhook را صدا بزنید.
401 Unauthorizedمتغیر توکن خالی، اشتباه تایپی یا باطل‌شده است. آن را با getMe بررسی کنید.
روی سیستم خودم کار می‌کند، روی سرور ساکت استHTTPS خروجی به api.telegram.org مسدود است یا فایل محیطی بارگذاری نشده. لاگ‌ها را بررسی کنید.
ربات وب هوکی چیزی دریافت نمی‌کندlast_error_message را در getWebhookInfo ببینید: TLS، پورت اشتباه، 403 به خاطر عدم تطابق secret یا هندلری که کرش می‌کند.

تازه با ربات‌ها شروع کرده‌اید؟ اول آموزش ساخت ربات تلگرام را بخوانید و بعد برای دیپلوی برگردید.

پرسش‌های متداول

ربات تلگرام را کجا می‌توان هاست کرد؟

هر جایی که بتواند درخواست HTTPS خروجی بفرستد: VPS، هاست داکر، سرور خانگی یا پلتفرم serverless. رباتی که از getUpdates استفاده می‌کند آدرس عمومی لازم ندارد؛ ربات وب هوکی به یک آدرس HTTPS عمومی روی پورت 443، 80، 88 یا 8443 نیاز دارد.

ربات دیپلوی‌شده باید از polling استفاده کند یا وب هوک؟

هر دو در production کار می‌کنند. long polling با getUpdates روی VPS یا داکر ساده‌ترین روش است، چون دامنه و گواهی لازم ندارد. روی پلتفرم‌های serverless که کد فقط با رسیدن درخواست اجرا می‌شود، وب هوک الزامی است.

چرا بعد از دیپلوی ربات خطای 409 Conflict می‌گیرم؟

یا هنوز وب هوک تنظیم است و ربات با getUpdates poll می‌کند (deleteWebhook را صدا بزنید)، یا دو نسخه از ربات هم‌زمان poll می‌کنند؛ مثلاً کانتینر قدیمی و جدید هنگام دیپلوی، یا لپ‌تاپ شما و سرور. برای هر توکن دقیقاً یک نمونه‌ی polling اجرا کنید.

چطور ربات تلگرام را 24 ساعته روشن نگه دارم؟

آن را زیر یک ناظر پروسس اجرا کنید که بعد از کرش و ریبوت دوباره راهش بیندازد: سرویس systemd با Restart=always روی VPS، یا کانتینر داکر با --restart unless-stopped. لاگ را در stdout بنویسید و با journalctl یا docker logs دنبال کنید.

آیا می‌توان ربات تلگرام را روی Cloudflare Workers اجرا کرد؟

بله، در حالت وب هوک. Worker هر آپدیت را به صورت درخواست POST دریافت می‌کند، هدر X-Telegram-Bot-Api-Secret-Token را بررسی می‌کند و Bot API را با fetch صدا می‌زند. آدرس HTTPS آن در workers.dev را با setWebhook ثبت کنید. حلقه‌ی long polling با این مدل جور نیست.

توکن ربات را روی سرور کجا نگه دارم؟

در یک متغیر محیطی که از فایلی خوانده می‌شود که فقط کاربر ربات به آن دسترسی دارد، یا در محل نگهداری secret پلتفرم (مثلاً Worker secret). هرگز توکن را در Git کامیت نکنید یا داخل ایمیج داکر نگذارید. اگر لو رفت، در @BotFather باطلش کنید.

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

ساخت ربات تلگرام قدم‌به‌قدم: ساخت ربات در BotFather، گرفتن توکن، تست با getMe، پیدا کردن chat id و ارسال اولین پیام با curl و Python.

Telegram Bot API 10.0 تا 10.5: تنظیمات ربات، ویجت‌ها، پیام‌های rich و ephemeral، حالت مهمان و بیشتر

تغییرات Telegram Bot API 10.0 تا 10.5: متد setMySettings و BotFullInfo، ویجت‌های HTML، پیام‌های rich و ephemeral و حالت مهمان، همراه با مثال JSON.

خطاهای Telegram Bot API: معنی هر خطا و روش رفع آن

خطاهای ربات تلگرام به زبان ساده: 400 chat not found، 403 bot was blocked by the user، 409 Conflict و 429 retry_after؛ علت، راه حل و کد مدیریت خطا.

محدودیت‌های Telegram Bot API: نرخ ارسال، خطای 429، حجم فایل و طول پیام

محدودیت‌های Telegram Bot API به زبان ساده: 30 پیام در ثانیه، 1 پیام در ثانیه در هر چت، 20 در دقیقه در گروه، مدیریت خطای 429 و محدودیت حجم فایل.

دستورات ربات تلگرام: setMyCommands، اسکوپ دستورات و دیپ‌لینک /start

تنظیم دستورات ربات تلگرام: /setcommands در @BotFather، متد setMyCommands با اسکوپ و زبان، پارامتر دیپ‌لینک /start و دستور /cmd@bot در گروه‌ها.

کیبورد ربات تلگرام: دکمه شیشه‌ای (inline keyboard)، دکمه‌های callback و reply keyboard

ساخت دکمه شیشه‌ای ربات تلگرام: inline keyboard با callback_data، پاسخ با answerCallbackQuery، ویرایش پیام بعد از کلیک، reply keyboard و ForceReply.

اتصال n8n به تلگرام: وصل کردن ربات، اجرای ورک‌فلو و ارسال پیام

اتصال n8n به تلگرام: توکن ربات به عنوان Access Token، وب هوک Telegram Trigger روی HTTPS عمومی، ارسال پیام با چت آیدی و رفع خطاهای رایج.

ارسال پیام با ربات تلگرام از طریق API تلگرام (sendMessage)

آموزش ارسال پیام با ربات تلگرام از طریق API تلگرام: متد sendMessage با curl، Python و JavaScript، قالب‌بندی HTML و MarkdownV2، دکمه شیشه‌ای و رفع خطاها.

توکن ربات تلگرام: چیست، چطور بگیریم، بررسی و باطل کنیم

توکن ربات تلگرام چیست و از کجا بگیریم؟ گرفتن توکن از BotFather، پیدا کردن توکن ربات قبلی، تست با getMe، باطل کردن توکن لو رفته و نگهداری امن آن.

وب هوک ربات تلگرام: راه‌اندازی setWebhook، بررسی و رفع خطا

آموزش ست وب هوک تلگرام با setWebhook: پیش‌نیازهای HTTPS و پورت‌ها، secret_token، بررسی با getWebhookInfo، حذف وب هوک و رفع خطاهای رایج مثل 409.

چت آیدی تلگرام: چیست، کجاست و چطور chat id کاربر، گروه و کانال را پیدا کنیم

چت آیدی تلگرام کجاست؟ پیدا کردن chat_id کاربر، گروه، سوپرگروه، کانال و تاپیک با getUpdates، معنی آیدی‌های منفی و رفع مشکل نتیجه خالی و خطای 409.

ربات اینلاین تلگرام: فعال کردن حالت inline و پاسخ به کوئری‌ها

ساخت ربات اینلاین تلگرام: فعال کردن حالت inline با @BotFather یا setMySettings، دریافت آپدیت inline_query و پاسخ با answerInlineQuery.

پرداخت با Telegram Stars در ربات: فاکتور، پیش‌پرداخت، بازپرداخت و اشتراک

دریافت پرداخت با استارز تلگرام در ربات: sendInvoice با ارز XTR، پاسخ به pre_checkout_query، successful_payment، بازپرداخت و اشتراک با کد پایتون و JS.

سرور تست تلگرام: چطور ربات را در محیط تست تلگرام تست کنیم

سرور تست تلگرام برای ربات‌ها: ورود به محیط تست، ساخت ربات تست در BotFather، فراخوانی Bot API با مسیر /test/ و سوییچ TEST در تستر ما.

ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنت‌ها و دکمه اشتراک‌گذاری

ورود با تلگرام در سایت با Telegram Login (OIDC) و ویجت قدیمی همراه کد بررسی hash، جاسازی پست کانال، ویجت کامنت و دکمه اشتراک‌گذاری تلگرام.

مرجع API جاوااسکریپت TelegramWidget: رویدادها، کدهای خطا و محدودیت‌ها

مرجع API جاوااسکریپت ویجت تلگرام: ویژگی‌ها، request()، رویدادها، کدهای خطا، متغیرهای CSS، widget_query و answerWidgetQuery و همه محدودیت‌ها.

مثال ویجت تلگرام: کد کامل HTML و ربات پایتون

مثال‌های کامل ویجت تلگرام با کد: کارت سفارش ثابت، شمارنده با widget_query، نظرسنجی زنده با ویجت اشتراکی و پیش‌نمایش در مرورگر با ربات پایتون.

ویجت تلگرام چیست؟ HTML تعاملی داخل پیام‌های ربات

ویجت تلگرام در Bot API 10.4 چیست؟ ارسال با sendWidget، وضعیت chat_data و public_data، محدودیت‌ها، جاهایی که فعلاً کار می‌کند و تفاوت با مینی اپ.

تست مینی اپ تلگرام: از mock در مرورگر تا اجرای واقعی در تلگرام

تست مینی اپ تلگرام قدم به قدم: حالت mock در مرورگر، اجرای localhost با تونل HTTPS، محیط تست، DevTools در هر پلتفرم و اعتبارسنجی initData در سرور.