توکن دسترسی تلگرام به زبان ساده: توکن ربات، API ID، API hash و session string

بسیاری از افراد طوری دنبال «توکن دسترسی تلگرام» می‌گردند که انگار تلگرام یک کلید همه‌کاره صادر می‌کند. این‌طور نیست. تلگرام چند سیستم احراز هویت جداگانه دارد و اعتبارنامه درست به این بستگی دارد که نرم‌افزار شما قرار است یک ربات را کنترل کند، یک حساب شخصی را مجاز کند، کاربری را وارد یک وب‌سایت کند یا دوباره به کلاینتی وصل شود که قبلاً مجاز شده است.

این تفاوت مهم است، چون هر اعتبارنامه اختیارات متفاوتی دارد. توکن ربات فقط یک ربات را کنترل می‌کند. API ID و API hash یک برنامه توسعه‌دهنده را شناسایی می‌کنند. کد ورود نشان می‌دهد که کسی به‌طور موقت به یک شماره تلفن دسترسی دارد. session string یا فایل session می‌تواند مجوز کامل‌شده یک حساب شخصی را نگه دارد و بنابراین ممکن است بدون درخواست ورود دوباره، به حساب دسترسی بدهد. یکی دانستن این مقادیر هم یک خطای رایج در پیاده‌سازی است و هم یک ریسک امنیتی جدی.

این راهنما توضیح می‌دهد هر اعتبارنامه چه کاری می‌کند، از کجا می‌آید و چگونه باید آن را امن نگه داشت. همچنین توضیح می‌دهد چرا اتصال یک CRM یا MCP تلگرام برای حساب‌های شخصی با یکپارچه‌سازی Bot API یکی نیست.

اگر یک آموزش از شما «توکن تلگرام» خواست، پیش از کپی کردن هر چیزی مکث کنید و ببینید منظورش کدام ردیف این جدول است.

توکن ربات تلگرام، یک ربات را نزد Bot API احراز هویت می‌کند. آموزش رسمی ربات تلگرام از توسعه‌دهندگان می‌خواهد ربات را از طریق @BotFather و معمولاً با دستور /newbot بسازند. BotFather توکنی برمی‌گرداند که بک‌اند هنگام فراخوانی متدهایی مانند getMe، sendMessage یا setWebhook از آن استفاده می‌کند.

توکن ربات معمولاً شبیه یک شناسه عددی ربات است که بعد از آن یک دونقطه و یک رشته محرمانه طولانی می‌آید. توکن واقعی را در مستندات، اسکرین‌شات، پیام چت، سیستم پیگیری باگ، کد جاوااسکریپت سمت کاربر یا مخزن عمومی قرار ندهید. تلگرام صراحتاً توصیه می‌کند توکن را مثل رمز عبور در نظر بگیرید، چون هر کسی آن را داشته باشد می‌تواند ربات را کنترل کند.

توکن ربات یک محدودیت مهم دارد: هویت ربات را احراز می‌کند، نه هویت شخصی شما در تلگرام را. اگر دنبال ورود به تلگرام با توکن ربات هستید، بدانید که این توکن شما را وارد حساب شخصی‌تان نمی‌کند و فقط به نام همان ربات کار می‌کند. ربات نمی‌تواند صندوق پیام خصوصی موجود یک شخص را بخواند. مستندات ربات تلگرام همچنین توضیح می‌دهد که ربات نمی‌تواند گفتگو با کاربر را آغاز کند؛ کاربر باید خودش به ربات پیام بدهد یا آن را به یک گروه اضافه کند. در گروه‌ها نیز تنظیمات حریم خصوصی می‌تواند پیام‌هایی را که ربات دریافت می‌کند محدودتر کند.

وقتی یک تجربه مبتنی بر ربات می‌سازید، توکن ربات انتخاب درستی است: دستورها، اعلان‌ها، منوها، دریافت درخواست پشتیبانی، یک Mini App یا یک گردش‌کار خودکار که کاربران در آن آگاهانه با ربات تعامل می‌کنند.

کلاینت‌های حساب شخصی به جای تکیه صرف بر Bot API مبتنی بر HTTP، از MTProto API تلگرام استفاده می‌کنند. پیش از آنکه یک برنامه بتواند کاربر تلگرام را مجاز کند، توسعه‌دهنده آن به API ID و API hash نیاز دارد.

دستورالعمل رسمی ثبت برنامه در تلگرام این مراحل را شرح می‌دهد:

1. از یک شماره تلفن فعال که در تلگرام ثبت شده است استفاده کنید.
2. وارد my.telegram.org شوید.
3. بخش API development tools را باز کنید.
4. برنامه را ثبت کنید.
5. مقادیر api_id و api_hash به‌دست‌آمده را در جای امن نگه دارید.

API ID یک شناسه عددی برای برنامه است و API hash رمز همراه آن. این دو، نرم‌افزاری را که درخواست مجوز می‌دهد شناسایی می‌کنند، اما به‌تنهایی آن نرم‌افزار را وارد هیچ حساب تلگرامی نمی‌کنند. همچنان یک فرایند مجوزدهی کاربر لازم است.

اعتبارنامه API را از یک پروژه تصادفی در GitHub یا یک برنامه نمونه کپی نکنید. تلگرام هشدار می‌دهد که API ID نمونه در کد متن‌باز آن محدود است و برای برنامه‌هایی که برای کاربران منتشر می‌شوند مناسب نیست. یک یکپارچه‌سازی در محیط عملیاتی باید از اعتبارنامه‌ای استفاده کند که به نام سازمانِ اداره‌کننده آن ثبت شده و با شرایط API تلگرام سازگار باشد.

وقتی یک کلاینت MTProto یک حساب شخصی را مجاز می‌کند، تلگرام معمولاً یک کد ورود موقت را از طریق یک نشست فعال تلگرام یا یک کانال پشتیبانی‌شده دیگر می‌فرستد. اگر تأیید دومرحله‌ای حساب فعال باشد، تلگرام رمز اضافه حساب را هم می‌خواهد.

هیچ‌کدام از این دو، اعتبارنامه API نیست که توسعه‌دهنده بخواهد آن را برای همیشه ذخیره کند. کد ورود یک اثبات موقت است که نشان می‌دهد کسی که حساب را در اختیار دارد این ورود را تأیید می‌کند. رمز تأیید دومرحله‌ای هم رمز عبور صاحب حساب است. یک صفحه مجوزدهی معتبر باید توضیح دهد چرا به این مقدار نیاز دارد، آن را امن منتقل کند و از ثبت آن در لاگ‌ها یا ابزارهای تحلیلی خودداری کند.

هرگز کد ورود تلگرام را برای کسی که ادعا می‌کند پشتیبانی است نفرستید. هرگز آن را در گفتگو با یک ربات وارد نکنید. درخواست کد ورود خارج از فرایند ورود، نشانه جدی تلاش برای تصاحب حساب است.

پس از مجوزدهی موفق، کتابخانه‌های MTProto معمولاً نشست (session) را ذخیره می‌کنند. بسته به کتابخانه، این نشست ممکن است در یک فایل پایگاه‌داده محلی، یک رکورد رمزگذاری‌شده یا یک رشته قابل انتقال نگه داشته شود.

نشست باعث می‌شود کاربر مجبور نباشد هر بار که برنامه دوباره اجرا می‌شود کد ورود جدیدی وارد کند. همین راحتی آن را بسیار حساس می‌کند. یک نشست معتبر می‌تواند معادل یک دستگاه مجاز باشد، بنابراین افشای آن ممکن است به شخص دیگری اجازه دهد تا زمان لغو نشست، از طریق آن حساب عمل کند.

این قواعد را رعایت کنید:

• هرگز نشست‌ها را در Git کامیت نکنید.
• هرگز آن‌ها را در کد مرورگر یا ابزارهای تحلیلی موبایل قرار ندهید.
• آن‌ها را در حالت ذخیره با یک کلید مدیریت‌شده رمزگذاری کنید، نه با کلیدی که در کد و کنار داده رمزگذاری‌شده نوشته شده است.
• دسترسی در محیط عملیاتی را به محدودترین نقش سرویس ممکن محدود کنید.
• آن‌ها را از لاگ‌ها و گزارش‌های خطا حذف یا پنهان کنید.
• راهی روشن برای قطع اتصال حساب و حذف نشست ذخیره‌شده فراهم کنید.
• نشست افشاشده را از صفحه Settings → Devices در تلگرام لغو کنید و رمزهای مرتبط را عوض کنید.

session string نسخه امن‌تر توکن ربات نیست. یک اعتبارنامه متفاوت است که به‌طور بالقوه دسترسی گسترده‌تری می‌دهد.

تلگرام از ورود به وب‌سایت‌ها و اپلیکیشن‌ها از طریق Telegram Login، از جمله یک فرایند OpenID Connect، نیز پشتیبانی می‌کند. این فرایند یک کاربر تلگرام را در برنامه دیگری احراز هویت می‌کند و اطلاعات هویتی امضاشده یا توکن‌هایی با دامنه محدود برمی‌گرداند. این کار به‌طور خودکار اجازه خواندن صندوق پیام شخصی کاربر در تلگرام را نمی‌دهد.

وقتی هدف «ورود به سرویس من با تلگرام» است، از Telegram Login استفاده کنید. برای ربات از Bot API استفاده کنید. و فقط زمانی سراغ یک کلاینت مجاز MTProto بروید که محصول واقعاً به قابلیت‌های حساب شخصی نیاز دارد و مدل رضایت و امنیت روشنی دارد.

MCP توضیح می‌دهد که یک کلاینت هوش مصنوعی چگونه ابزارها و اقدامات را از یک سرور درخواست می‌کند. MCP جایگزین احراز هویت تلگرام نمی‌شود. یک سرور MCP تلگرام همچنان به یک لایه مجازشده تلگرام در پشت خود نیاز دارد.

برای مثال، Entergram حساب‌های شخصی تلگرام را از طریق یک فرایند مجوزدهی که کاربر تأیید می‌کند به یک فضای کاری متصل می‌کند. سپس سرور MCP تلگرام میزبانی‌شده، مجموعه‌ای مشخص از ابزارهای CRM و پیام‌رسانی را در اختیار یک کلاینت MCP تأییدشده قرار می‌دهد. کلاینت هوش مصنوعی به ابزارها دسترسی پیدا می‌کند؛ نباید کد ورود خام تلگرام، API hash یا نشست‌های قابل استفاده دوباره حساب را دریافت کند.

این جداسازی معماری امن‌تری است:

1. اعتبارنامه‌های تلگرام داخل سرویسی می‌مانند که مسئول مجوزدهی تلگرام است.
2. سرور MCP فقط عملیات‌هایی با تعریف محدود را در دسترس قرار می‌دهد.
3. مجوزهای OAuth و فضای کاری تعیین می‌کنند کدام شخص یا کلاینت هوش مصنوعی می‌تواند این عملیات را فراخوانی کند.
4. لاگ‌های حسابرسی اقدامات کاری را ثبت می‌کنند، بدون اینکه رمزهای احراز هویت ثبت شوند.
5. لغو دسترسی می‌تواند کلاینت MCP را غیرفعال کند، بدون اینکه کاربر مجبور شود همه اعتبارنامه‌های زیربنایی تلگرام را افشا یا عوض کند.

برای تفاوت قابلیت‌ها، مقاله MCP تلگرام در برابر Bot API را بخوانید.

پیش از انتشار هر یکپارچه‌سازی تلگرام، به این پرسش‌ها پاسخ دهید:

• آیا این یکپارچه‌سازی به‌عنوان ربات عمل می‌کند یا به‌عنوان حساب شخصی؟
• واقعاً به کدام چت‌ها و اقدامات نیاز دارد؟
• آیا کاربر می‌تواند گفتگوهای خصوصی یا حساب‌هایی را مستثنا کند؟
• آیا اقدامات نوشتنی از اقدامات فقط‌خواندنی جدا شده‌اند؟

• آیا توکن‌های ربات، API hashها و نشست‌ها فقط روی سرورهای قابل اعتماد نگهداری می‌شوند؟
• آیا رمزها در حالت ذخیره رمزگذاری شده‌اند و هنگام انتقال محافظت می‌شوند؟
• آیا اعتبارنامه‌های محیط عملیاتی از کنترل نسخه و استقرارهای پیش‌نمایش بیرون نگه داشته شده‌اند؟
• آیا لاگ‌ها، سیستم‌های ردیابی و ابزارهای پشتیبانی مشتری طوری تنظیم شده‌اند که این مقادیر را پنهان کنند؟

• آیا هر حساب متصل یک مالک مشخص دارد؟
• آیا مدیر می‌تواند یک حساب را بدون اثر بر حساب‌های دیگر قطع کند؟
• آیا دسترسی یک کلاینت هوش مصنوعی یا یک کارمند را می‌توان به‌طور مستقل لغو کرد؟
• آیا اقدامات حساس همراه با انجام‌دهنده، زمان، حساب و نتیجه ثبت می‌شوند؟

• آیا روال مستندی برای تعویض توکن ربات وجود دارد؟
• آیا تیم می‌تواند یک نشست سرقت‌شده را سریع باطل کند؟
• آیا سرویس درباره موقعیت‌های ورود غیرعادی یا اقدامات پرحجم هشدار می‌دهد؟
• آیا نسخه‌های پشتیبان رمزگذاری شده‌اند و تابع همان سیاست حذف هستند؟

هر اعتبارنامه‌ای را «توکن» نامیدن. این باعث می‌شود مهندسان مقدار اشتباه را در فیلد اشتباه بگذارند و بررسی‌های امنیتی مبهم شود. متغیرهای پیکربندی را دقیق نام‌گذاری کنید: TELEGRAM_BOT_TOKEN، TELEGRAM_API_ID و TELEGRAM_API_HASH از TELEGRAM_TOKEN روشن‌ترند.

قرار دادن توکن ربات در کد فرانت‌اند. هر چیزی که به مرورگر تحویل داده می‌شود باید عمومی فرض شود. فراخوانی‌های Bot API را از طریق یک بک‌اند محافظت‌شده انجام دهید.

فرض اینکه API ID و API hash یعنی دسترسی به حساب. این دو برنامه را شناسایی می‌کنند. کاربر همچنان باید حساب را مجاز کند.

بی‌خطر دانستن نشست، مثل یک کش ساده. نشست جزو مواد احراز هویت است. از آن مثل یک اعتبارنامه محافظت کنید و امکان لغو آن را فراهم کنید.

گرفتن دسترسی بیشتر از نیاز گردش‌کار. یک ربات اعلان به نشست حساب شخصی نیاز ندارد. یک گردش‌کار گزارش‌گیری ممکن است به مجوز ارسال پیام نیاز نداشته باشد. با محدودترین طراحی قابل اجرا شروع کنید.

اگر می‌خواهید ربات تلگرام بسازید، آن را با BotFather ایجاد کنید و توکن ربات را در بک‌اند خود به کار ببرید. اگر یک کلاینت مجاز تلگرام برای حساب‌های شخصی توسعه می‌دهید، API ID و API hash خودتان را ثبت کنید، سپس فرایند مجوزدهی کاربر در تلگرام را کامل کنید و از نشست حاصل محافظت کنید. اگر فقط به ورود کاربر نیاز دارید، به جای درخواست دسترسی به صندوق پیام، از Telegram Login استفاده کنید.

برای تیم‌هایی که می‌خواهند ابزارهای هوش مصنوعی با حساب‌های شخصی تلگرامِ تأییدشده کار کنند، یک سرور MCP تلگرام با مجوزهای مشخص باعث می‌شود اعتبارنامه‌های خام تلگرام به هر کلاینت هوش مصنوعی منتقل نشوند. هر مسیری را انتخاب کنید، رمزهای احراز هویت را از پرامپت‌ها، مخزن‌ها، کد مرورگر و اسکرین‌شات‌ها دور نگه دارید و امکان لغو دسترسی را از روز اول بخشی از طراحی کنید.