سرور تست تلگرام: چطور ربات را در محیط تست تلگرام تست کنیم
سرور تست تلگرام یک محیط تست جداگانه با حسابها و رباتهای مخصوص خودش است که در آن ربات شما Bot API را از آدرس https://api.telegram.org/bot<token>/test/METHOD_NAME صدا میزند. وقتی به آن سراغش بروید که برای Mini App یا Web Login لینک HTTP ساده لازم دارید، چند کاربر تست یکبارمصرف میخواهید یا به قابلیتهایی از Bot API نیاز دارید که فعلاً فقط آنجا فعالاند. برای تست روزمره ربات تلگرام، معمولاً یک ربات دوم در production کافی است. در این راهنما هر دو روش، ورود به محیط تست در iOS، Desktop و macOS، و فراخوانی API تست با curl، Python، JavaScript و Bot API Tester ما را مرور میکنیم.
روش 1: یک ربات تست جداگانه در production
سریعترین راه برای تست ربات تلگرام بدون مزاحمت برای کاربرانش این است که نسخه دومی از کدتان را با یک حساب ربات دیگر اجرا کنید:
- در @BotFather با دستور
/newbotربات جدیدی بسازید (آموزش ساخت ربات تلگرام را ببینید). - توکن آن را در تنظیمات نسخه تست قرار دهید، مثلاً در یک فایل
.envجداگانه. - با ربات جدید بهصورت خصوصی دیباگ کنید؛ ربات اصلی بدون تغییر به کارش ادامه میدهد.
یک نکته: هر file_id به شناسه یک ربات گره خورده است. ربات تست نمیتواند از مقدارهای file_id ذخیرهشده ربات اصلی استفاده کند، پس فایلها باید دوباره توسط ربات تست آپلود شوند.
روش 2: محیط تست اختصاصی تلگرام
تلگرام برای تستهای پیشرفتهتر یک محیط تست اختصاصی هم دارد. این محیط کاملاً از محیط اصلی (production) جداست: حسابها، رباتها، چتها و توکنهای production آنجا وجود ندارند. تفاوتها:
| Production | سرور تست | |
|---|---|---|
| حساب کاربری | حساب معمولی تلگرام شما | حساب جدیدی که در محیط تست ساخته میشود |
| رباتها و توکنها | با @BotFather در production ساخته میشوند | با @BotFather داخل حساب تست ساخته میشوند؛ توکنها جدا هستند |
| آدرس Bot API | /bot<token>/METHOD_NAME | /bot<token>/test/METHOD_NAME |
| لینکهای Mini App و Web Login | فقط HTTPS | HTTP بدون TLS مجاز است |
| محدودیتهای flood | محدودیتهای استاندارد | بیشتر نمیشوند و گاهی سختگیرانهترند |
| ویجتها (Bot API 10.4) | فقط چت خصوصی با ربات | گروهها، حالت inline و فوروارد هم کار میکنند |
ساخت حساب تست در iOS، Desktop یا macOS
از یکی از اپهای رسمی وارد محیط تست تلگرام شوید:
- iOS: ده بار روی آیکون Settings بزنید → Accounts → Login to another account → Test.
- Telegram Desktop: منوی ☰ Settings را باز کنید، Shift+Alt را نگه دارید و روی «Add Account» راستکلیک کنید، بعد «Test Server» را انتخاب کنید.
- macOS: ده بار روی آیکون Settings کلیک کنید تا Debug Menu باز شود، بعد ⌘+کلیک روی «Add Account» و با شماره تلفن وارد شوید.
حساب تست کنار حساب معمولیتان اضافه میشود و میتوانید در همان اپ بین دو محیط جابهجا شوید. هر کاری آنجا انجام دهید، از جمله چت با ربات تست، فقط در محیط تست میماند.
ساخت ربات روی سرور تست و گرفتن توکن
داخل حساب تست، @BotFather را باز کنید و ربات را به روش همیشگی بسازید: /newbot، یک نام نمایشی و بعد نام کاربریای که به bot ختم شود. BotFather توکنی برای محیط تست میفرستد. ظاهرش مثل هر توکن دیگری است، اما فقط با آدرس API دارای /test/ کار میکند. آن را با نامی جدا، مثلاً TEST_BOT_TOKEN، ذخیره کنید تا هیچوقت با توکن production قاطی نشود؛ نکتههای راهنمای توکن ربات تلگرام اینجا هم صدق میکند.
فراخوانی Bot API روی سرور تست تلگرام
همه متدهای Bot API همانطور کار میکنند؛ تنها فرق، /test/ بعد از توکن است. توکن را با getMe بررسی کنید:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getMe"
در کد، آدرس پایه را در یک ثابت نگه دارید تا جابهجایی بین محیطها فقط با تغییر یک خط انجام شود. این ربات echo ساده، توکن را بررسی میکند، بعد آپدیتها را با long polling متد getUpdates میگیرد و هنگام خطای 429 به اندازه retry_after صبر میکند:
import os
import time
import requests
TOKEN = os.environ["TEST_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}/test" # برای production، "/test" را حذف کنید
def call(method, **params):
while True:
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if data["ok"]:
return data["result"]
if data.get("error_code") == 429: # محدودیت flood: به اندازه گفتهشده صبر کن
time.sleep(data["parameters"]["retry_after"])
continue
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
me = call("getMe")
print("ربات روی سرور تست اجرا شد: @" + me["username"])
offset = 0
while True:
for update in call("getUpdates", offset=offset, timeout=30):
offset = update["update_id"] + 1
msg = update.get("message")
if msg and "text" in msg:
call("sendMessage", chat_id=msg["chat"]["id"], text="اکوی تست: " + msg["text"])const TOKEN = process.env.TEST_BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}/test`; // برای production، "/test" را حذف کنید
async function call(method, params = {}) {
while (true) {
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) return data.result;
if (data.error_code === 429) { // محدودیت flood: به اندازه گفتهشده صبر کن
await new Promise((resolve) => setTimeout(resolve, data.parameters.retry_after * 1000));
continue;
}
throw new Error(`${method}: ${data.error_code} ${data.description}`);
}
}
const me = await call("getMe");
console.log("ربات روی سرور تست اجرا شد: @" + me.username);
let offset = 0;
while (true) {
for (const update of await call("getUpdates", { offset, timeout: 30 })) {
offset = update.update_id + 1;
const msg = update.message;
if (msg?.text) {
await call("sendMessage", { chat_id: msg.chat.id, text: "اکوی تست: " + msg.text });
}
}
}از حساب تست به ربات /start بفرستید تا جواب بدهد. نسخه JavaScript از await در سطح بالا استفاده میکند، پس آن را با نام bot.mjs ذخیره و با Node.js نسخه 18 یا بالاتر اجرا کنید.
وبهوک هم همینطور کار میکند: setWebhook را از طریق آدرس تست صدا بزنید؛ قواعد معمول url، پورتها و secret_token برقرار است (جزئیات در راهنمای وب هوک ربات تلگرام). نتیجه را با getWebhookInfo، باز هم از مسیر /test/، بررسی کنید:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/setWebhook" \
-d "url=https://example.com/telegram/webhook"
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getWebhookInfo"
کتابخانههای ربات معمولاً آدرس درخواستها را از یک آدرس پایه میسازند. اگر کتابخانه شما اجازه تغییر آدرس پایه Bot API را میدهد، آن را طوری تنظیم کنید که درخواستها به …/bot<token>/test/METHOD_NAME برسند؛ نام دقیق این تنظیم در هر کتابخانه فرق میکند، پس آن را در مستندات کتابخانهتان پیدا کنید.
امتحان سرور تست در Bot API Tester
Bot API Tester ما میتواند بدون نوشتن کد، درخواستها را به محیط تست بفرستد:
- متد getMe را در Bot API Tester باز کنید.
- سوییچ TEST کنار فیلد توکن را بزنید، یا صفحه تستر را با
?env=testدر آدرس باز کنید. - توکن ربات تست را وارد کنید و Execute را بزنید. از این به بعد درخواستها به
https://api.telegram.org/bot<token>/test/METHODمیروند.
تا وقتی سوییچ روشن است همه متدها از آدرس تست استفاده میکنند، از جمله long polling با getUpdates؛ پس میتوانید رسیدن آپدیتهای حساب تست را در تاریخچه آپدیتها ببینید. تستر وضعیت سوییچ را در مرورگر شما به خاطر میسپارد؛ قبل از وارد کردن توکن production آن را خاموش کنید. مثل همیشه، توکن در localStorage مرورگر خودتان میماند و درخواستها مستقیم به api.telegram.org میروند.
Mini App و Web Login روی HTTP ساده
دلیل اصلی که توسعهدهندگان Mini App سراغ محیط تست میروند این است: آنجا url در WebAppInfo (Mini App) و LoginUrl (دکمههای Web Login) میتواند لینک HTTP بدون TLS باشد. به این ترتیب میتوانید دکمه منو یا دکمه web_app ربات تست را بدون تنظیم گواهی یا تونل، به یک سرور توسعه در شبکه محلی وصل کنید. در production لینکها باید HTTPS باشند. صفحه Mini App را میتوانید قبل از باز کردن در تلگرام، در Mini App Tester هم امتحان کنید.
ویجتهای Bot API 10.4 روی سرور تست
ویجتهای HTML داخل پیام که در Bot API 10.4 اضافه شدند، فعلاً در production فقط در چت خصوصی با ربات کار میکنند. ویجت در گروهها، در حالت inline و در پیامهای فورواردشده فعلاً فقط روی سرور تست کار میکند، پس این سناریوها را آنجا میتوانید امتحان کنید. نحوه کار ویجتها را در ویجت تلگرام چیست ببینید.
محدودیتها و توصیهها
- آنجا تست بار (load test) نگیرید. محدودیتهای flood در محیط تست بیشتر نمیشوند و گاهی سختگیرانهترند. خطای
429را باretry_afterمدیریت کنید و به عددهای ثابت محدودیت تکیه نکنید. - محیطها را در تنظیمات از هم جدا نگه دارید. برای توکن و آدرس پایه متغیرهای جداگانه داشته باشید و هنگام شروع، در لاگ بنویسید ربات در کدام محیط اجرا شده است.
- در production دوباره تست کنید. قبل از انتشار، همان سناریوها را با یک ربات تست در production و روی HTTPS اجرا کنید، چون لینکهای HTTP و قابلیتهای مخصوص محیط تست برای کاربران واقعی کار نمیکنند.
رفع مشکلات
| علامت | علت احتمالی | راهحل |
|---|---|---|
401 Unauthorized | توکن production به /test/ فرستاده شده، یا توکن تست بدون /test/ | محیطها جدا هستند: توکن را با آدرس (یا سوییچ TEST در تستر) هماهنگ کنید |
400 Bad Request: chat not found | چت آیدی مربوط به production است؛ آن کاربران و چتها روی سرور تست وجود ندارند | از حساب تست به ربات تست پیام بدهید و چت آیدی را از getUpdates بردارید (راهنمای چت آیدی تلگرام) |
| ربات در جستجو پیدا نمیشود | جستجو از حساب production انجام شده | از حساب تستی که ربات در آن ساخته شده جستجو کنید |
429 Too Many Requests | محدودیتهای flood که روی سرور تست بیشتر نمیشوند | به اندازه retry_after ثانیه صبر کنید و سرعت ارسال را کم کنید |
| Mini App روی HTTP باز نمیشود | ربات یا حساب در production است | از رباتی که در محیط تست ساخته شده استفاده کنید و آن را از حساب تست باز کنید |
فهرست کامل متدها در مرجع متدهای Bot API آمده است.
پرسشهای متداول
سرور تست تلگرام چیست؟
یک محیط تست اختصاصی که کاملاً از تلگرام اصلی (production) جداست. حسابهای کاربری و رباتهای خودش را دارد و رباتها Bot API را از آدرس https://api.telegram.org/bot<token>/test/METHOD_NAME صدا میزنند.
چطور وارد محیط تست تلگرام شوم؟
در iOS ده بار روی آیکون Settings بزنید و بعد Accounts → Login to another account → Test. در Telegram Desktop منوی ☰ Settings را باز کنید، Shift + Alt را نگه دارید و روی Add Account راستکلیک کنید و Test Server را بزنید. در macOS ده بار روی آیکون Settings کلیک کنید تا Debug Menu باز شود، بعد ⌘ + کلیک روی Add Account.
میتوانم توکن ربات اصلی را روی سرور تست استفاده کنم؟
نه. این دو محیط از هم جدا هستند؛ رباتی که در production ساخته شده روی سرور تست وجود ندارد و برعکس. داخل حساب تست با @BotFather ربات جدید بسازید؛ استفاده از توکن محیط اشتباه معمولاً به 401 Unauthorized ختم میشود.
محدودیتهای نرخ (rate limit) روی سرور تست تلگرام بیشتر است؟
نه. محدودیتهای flood در محیط تست بیشتر نمیشوند و گاهی حتی سختگیرانهترند؛ پس خطای 429 Too Many Requests را با retry_after مدیریت کنید و عدد محدودیت را در کد ثابت نگذارید.
Mini App در محیط تست میتواند روی HTTP ساده اجرا شود؟
بله. در محیط تست، url در WebAppInfo (Mini App) و LoginUrl (Web Login) میتواند لینک HTTP بدون TLS باشد. در production لینکها باید HTTPS باشند.
برای تست ربات همیشه به سرور تست نیاز دارم؟
نه. در بیشتر موارد یک ربات دوم که در production با @BotFather ساختهاید کافی است: توکن خودش را دارد و مزاحم کاربران واقعی نمیشود. سرور تست را وقتی استفاده کنید که لینک HTTP، حسابهای تست جدا یا قابلیتهایی لازم دارید که فقط آنجا فعالاند.
آموزشهای مرتبط
ساخت ربات تلگرام: آموزش قدمبهقدم از BotFather تا اولین پیام با Python
ساخت ربات تلگرام قدمبهقدم: ساخت ربات در BotFather، گرفتن توکن، تست با getMe، پیدا کردن chat id و ارسال اولین پیام با curl و Python.
ارسال پیام با ربات تلگرام از طریق API تلگرام (sendMessage)
آموزش ارسال پیام با ربات تلگرام از طریق API تلگرام: متد sendMessage با curl، Python و JavaScript، قالببندی HTML و MarkdownV2، دکمه شیشهای و رفع خطاها.
توکن ربات تلگرام: چیست، چطور بگیریم، بررسی و باطل کنیم
توکن ربات تلگرام چیست و از کجا بگیریم؟ گرفتن توکن از BotFather، پیدا کردن توکن ربات قبلی، تست با getMe، باطل کردن توکن لو رفته و نگهداری امن آن.
وب هوک ربات تلگرام: راهاندازی setWebhook، بررسی و رفع خطا
آموزش ست وب هوک تلگرام با setWebhook: پیشنیازهای HTTPS و پورتها، secret_token، بررسی با getWebhookInfo، حذف وب هوک و رفع خطاهای رایج مثل 409.
چت آیدی تلگرام: چیست، کجاست و چطور chat id کاربر، گروه و کانال را پیدا کنیم
چت آیدی تلگرام کجاست؟ پیدا کردن chat_id کاربر، گروه، سوپرگروه، کانال و تاپیک با getUpdates، معنی آیدیهای منفی و رفع مشکل نتیجه خالی و خطای 409.
ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنتها و دکمه اشتراکگذاری
ورود با تلگرام در سایت با 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، محدودیتها، جاهایی که فعلاً کار میکند و تفاوت با مینی اپ.