دیپلوی ربات تلگرام: راهاندازی روی VPS، داکر و هاست Serverless
برای دیپلوی ربات تلگرام، کد آن را روی ماشینی اجرا کنید که همیشه روشن است و به 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 ربات را هنگام بوت اجرا کند و اگر کرش کرد دوباره راه بیندازد:
- یک کاربر بدون دسترسی لاگین بسازید و کد را در
/opt/mybotکپی کنید؛ برای پایتون همانجا یک virtual environment بسازید و وابستگیها را نصب کنید. - توکن را در
/etc/mybot.envبه صورت خطBOT_TOKEN=123456789:AAEexampleTokenReplaceWithYoursبگذارید و دسترسی را باchmod 600محدود کنید. - فایل یونیت
/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 را دوباره تلاش میکند، پس تابعی که تایماوت یا کرش کند همان آپدیت را دوباره دریافت میکند.
روشهای رایگان و کمهزینه برای هاست ربات تلگرام
- پلنهای رایگان serverless برای رباتهای وب هوکی با ترافیک متوسط و هندلرهای کوتاه مناسباند.
- یک VPS کوچک انعطافپذیرترین گزینه است: polling یا وب هوک، هر زبانی، و دیتابیس کنار ربات.
- سرور خانگی یا کامپیوتر تکبردی با polling کار میکند چون اتصال ورودی لازم نیست؛ آپتایم به برق و اینترنت شما بستگی دارد.
- پلتفرمهای کانتینری که پروسس را روشن نگه میدارند میتوانند ربات polling را میزبانی کنند؛ بررسی کنید اپهای بیکار را به خواب نبرند.
پیشنیازهای وب هوک روی هر هاستی
- فقط HTTPS، با TLS 1.2 یا جدیدتر، گواهی منطبق با دامنه همراه با زنجیرهی کامل، یا گواهی خودامضا که با
certificateآپلود شود. - پورتهای 443، 80، 88 یا 8443؛ IPv4 (IPv6 برای وب هوک پشتیبانی نمیشود)؛ بدون ریدایرکت.
- درخواستها از
149.154.160.0/20و91.108.4.0/22میآیند؛ تلگرام میگوید این رنجها ممکن است تغییر کنند. secret_token(1 تا 256 کاراکترA-Z a-z 0-9 _ -) را تنظیم کنید و هدرX-Telegram-Bot-Api-Secret-Tokenرا بررسی کنید.
بعد از هر دیپلوی، getWebhookInfo را در Bot API Tester باز کنید: اگر pending_update_count بالا میرود یا last_error_message تازهای دارید، تلگرام نمیتواند آپدیتها را تحویل دهد.
متغیرهای محیطی، لاگ و ریاستارت
- توکن: فقط در متغیر محیطی یا محل نگهداری secret، هرگز در Git، ایمیج یا کد سمت کلاینت. اگر لو رفت، طبق راهنمای توکن ربات تلگرام باطلش کنید و سرور را بهروز کنید.
- لاگ: در stdout/stderr بنویسید و بگذارید journald، داکر یا پلتفرم آنها را جمع کند. URL کامل درخواستها را لاگ نکنید، چون توکن داخلشان است.
- ریاستارت: یک ناظر (
Restart=always،--restart unless-stopped) کرشها را مدیریت میکند. تلگرام آپدیتها را تا زمان تأیید سمت خودش نگه میدارد: آپدیت وقتی تأیید میشود کهgetUpdatesباoffsetبزرگتری صدا زده شود، پس بعد از ریاستارت ربات فقط آپدیتهای تأییدنشده را میگیرد. آخرین دسته قبل از کرش ممکن است دو بار برسد؛ هر جا مهم است، باupdate_idتکراریها را حذف کنید. - محدودیت نرخ: خطای
429 Too Many Requestsرا با صبر کردن به اندازهیretry_afterثانیه مدیریت کنید؛ محدودیتهای Telegram Bot API را ببینید.
چکلیست دیپلوی
- توکن از متغیر محیطی یا secret خوانده میشود؛
getMeروی سرور موفق است. - برای هر توکن دقیقاً یک نمونهی polling، یا یک وب هوک با
secret_token؛ هرگز هر دو. - پروسس بعد از کرش و ریبوت خودکار دوباره اجرا میشود.
- لاگها جمعآوری میشوند و توکنی در آنها نیست.
- خطا در یک آپدیت لاگ میشود و کل ربات را از کار نمیاندازد؛ هندلرهای وب هوک سریع 2XX برمیگردانند.
- برای وب هوک،
getWebhookInfoآدرس درست و بدون خطای اخیر نشان میدهد. - برای آزمایش از یک ربات تست جداگانه یا سرور تست تلگرام استفاده میشود، نه توکن 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 در سرور.