Telegram Bot API

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

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

سرور تست تلگرام یک محیط تست جداگانه با حساب‌ها و ربات‌های مخصوص خودش است که در آن ربات شما 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

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

  1. در ‎@BotFather با دستور ‎/newbot ربات جدیدی بسازید (آموزش ساخت ربات تلگرام را ببینید).
  2. توکن آن را در تنظیمات نسخه تست قرار دهید، مثلاً در یک فایل .env جداگانه.
  3. با ربات جدید به‌صورت خصوصی دیباگ کنید؛ ربات اصلی بدون تغییر به کارش ادامه می‌دهد.

یک نکته: هر 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فقط HTTPSHTTP بدون TLS مجاز است
محدودیت‌های floodمحدودیت‌های استانداردبیشتر نمی‌شوند و گاهی سخت‌گیرانه‌ترند
ویجت‌ها (Bot API 10.4)فقط چت خصوصی با رباتگروه‌ها، حالت inline و فوروارد هم کار می‌کنند

ساخت حساب تست در iOS، Desktop یا macOS

از یکی از اپ‌های رسمی وارد محیط تست تلگرام شوید:

حساب تست کنار حساب معمولی‌تان اضافه می‌شود و می‌توانید در همان اپ بین دو محیط جابه‌جا شوید. هر کاری آنجا انجام دهید، از جمله چت با ربات تست، فقط در محیط تست می‌ماند.

ساخت ربات روی سرور تست و گرفتن توکن

داخل حساب تست، @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 ما می‌تواند بدون نوشتن کد، درخواست‌ها را به محیط تست بفرستد:

  1. متد getMe را در Bot API Tester باز کنید.
  2. سوییچ TEST کنار فیلد توکن را بزنید، یا صفحه تستر را با ?env=test در آدرس باز کنید.
  3. توکن ربات تست را وارد کنید و 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 و در پیام‌های فورواردشده فعلاً فقط روی سرور تست کار می‌کند، پس این سناریوها را آنجا می‌توانید امتحان کنید. نحوه کار ویجت‌ها را در ویجت تلگرام چیست ببینید.

محدودیت‌ها و توصیه‌ها

رفع مشکلات

علامتعلت احتمالیراه‌حل
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، محدودیت‌ها، جاهایی که فعلاً کار می‌کند و تفاوت با مینی اپ.