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

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

توکن ربات تلگرام رشته‌ای مثل 123456789:AAEexampleTokenReplaceWithYours است که BotFather هنگام ساخت ربات می‌دهد و هر درخواست به Bot API با آن احراز هویت می‌شود. برای گرفتن توکن ربات تلگرام جدید از دستور ‎/newbot و برای دیدن توکن ربات فعلی از مسیر ‎/mybots ← انتخاب ربات ← API Token استفاده کنید. هر کس توکن را داشته باشد ربات را کنترل می‌کند، پس آن را مثل رمز عبور نگه دارید.

توکن ربات تلگرام چیست؟

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

• عدد قبل از دونقطه، شناسه عددی ربات است؛ همان id که متد getMe برمی‌گرداند.
• بعد از دونقطه یک رشته مخفی از حروف لاتین، عدد، خط تیره و زیرخط می‌آید.

نمونه‌ای که در مستندات رسمی تلگرام آمده 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 است. توکن در آدرس هر درخواست، بلافاصله بعد از کلمه bot قرار می‌گیرد: https://api.telegram.org/bot<token>/METHOD_NAME. توکن با رمز حساب تلگرام شما فرق دارد و فقط به همان ربات دسترسی می‌دهد.

گرفتن توکن ربات تلگرام برای ربات جدید

1. ‎@BotFather را باز کنید و دستور ‎/newbot را بفرستید.
2. یک نام نمایشی و سپس یک نام کاربری وارد کنید که با bot تمام شود (5 تا 32 کاراکتر از حروف لاتین، عدد و زیرخط).
3. BotFather در پیام آخر توکن را می‌فرستد؛ آن را کپی کنید و جای امنی نگه دارید.

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

پیدا کردن توکن ربات قبلی

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

1. در BotFather دستور ‎/mybots را بفرستید.
2. ربات موردنظر را از لیست انتخاب کنید.
3. دکمه API Token را بزنید تا توکن فعلی نمایش داده شود.

دقت کنید: دستورهایی که توکن جدید می‌سازند برای دیدن توکن فعلی مناسب نیستند. با ساخته شدن توکن جدید، توکن قبلی از کار می‌افتد و باید آن را در همه سرورها و سرویس‌های متصل عوض کنید. برای دیدن توکن فقط از مسیر ‎/mybots ← API Token استفاده کنید.

بررسی توکن با getMe و معنی خطای 401

متد getMe ساده‌ترین راه تست توکن است؛ پارامتری ندارد و اطلاعات ربات را برمی‌گرداند:

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

اگر توکن معتبر باشد، پاسخ با ‎"ok": true و اطلاعات ربات (id، first_name، username) برمی‌گردد. در غیر این صورت این پاسخ را می‌بینید:

{"ok": false, "error_code": 401, "description": "Unauthorized"}

خطای 401 Unauthorized یعنی تلگرام این توکن را نمی‌شناسد. دلایل رایج:

• بخشی از توکن جا افتاده یا فاصله و خط جدید اضافه همراهش کپی شده است.
• توکن باطل شده و شما هنوز توکن قدیمی را در کد یا متغیر محیطی دارید.
• ربات با ‎/deletebot حذف شده است.

سریع‌ترین راه بدون ترمینال: توکن را در Bot API Tester روی متد getMe وارد کنید و پاسخ JSON را ببینید. توکن در localStorage مرورگر خودتان می‌ماند و درخواست مستقیم به api.telegram.org می‌رود. همین بررسی در Python:

import os
import requests

token = os.environ["TELEGRAM_BOT_TOKEN"]
r = requests.get(f"https://api.telegram.org/bot{token}/getMe", timeout=10).json()
if r["ok"]:
    print("توکن معتبر است:", r["result"]["username"])
else:
    print("خطا:", r["error_code"], r["description"])

باطل کردن توکن لو رفته

اگر توکن را در گیت‌هاب، یک گروه عمومی یا اسکرین‌شات منتشر کرده‌اید، فوراً آن را باطل کنید:

1. در BotFather دستور ‎/revoke را بفرستید و ربات را انتخاب کنید؛ یا از مسیر ‎/mybots ← ربات ← API Token دکمه Revoke را بزنید.
2. BotFather توکن جدیدی می‌دهد و توکن قبلی دیگر کار نمی‌کند.
3. توکن جدید را در سرور، متغیرهای محیطی و همه سرویس‌های متصل جایگزین کنید.

پاک کردن فایل یا commit از مخزن کافی نیست، چون توکن در تاریخچه git باقی می‌ماند و ممکن است قبلاً کپی شده باشد. تنها راه مطمئن، باطل کردن توکن است.

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

• توکن را در متغیر محیطی یا فایل ‎.env نگه دارید و این فایل را به ‎.gitignore اضافه کنید.
• هرگز توکن را در کد سمت کاربر (JavaScript سایت، اپ موبایل یا Mini App) قرار ندهید؛ درخواست‌های Bot API باید از سرور شما ارسال شوند.
• توکن بخشی از آدرس درخواست است، پس مراقب لاگ‌های سرور، پراکسی و ابزارهای مانیتورینگ باشید که آدرس کامل را ذخیره می‌کنند.
• برای تست و محیط اصلی دو ربات جدا با دو توکن متفاوت بسازید.

export TELEGRAM_BOT_TOKEN="123456789:AAEexampleTokenReplaceWithYours"

const token = process.env.TELEGRAM_BOT_TOKEN;

توکن و چت آیدی در n8n و دستیارهای هوش مصنوعی

ابزارهای اتوماسیون مثل نود Telegram در n8n و دستیارهای هوش مصنوعی که به تلگرام وصل می‌شوند (مثلاً OpenClaw) معمولاً دو چیز می‌خواهند: توکن ربات تلگرام برای ارسال و دریافت پیام، و چت آیدی مقصدی که پیام‌ها باید به آن برسند. چند نکته:

• برای هر سرویس ربات جداگانه بسازید تا اگر یکی را کنار گذاشتید، فقط توکن همان را باطل کنید.
• توکن را فقط به سرویس‌هایی بدهید که به آن‌ها اعتماد دارید؛ آن سرویس عملاً کنترل کامل ربات را دارد.
• اگر سرویس با وب‌هوک کار می‌کند، روی همان ربات نمی‌توانید هم‌زمان با getUpdates آپدیت بگیرید و خطای 409 Conflict می‌گیرید.

برای پیدا کردن چت آیدی کاربر، گروه یا کانال، راهنمای چت آیدی تلگرام را بخوانید و برای ارسال پیام آزمایشی سراغ آموزش ارسال پیام با ربات تلگرام بروید.