Токен доступу Telegram: токен бота, API ID, API hash і рядок сесії

Люди часто шукають «токен доступу Telegram» так, ніби Telegram видає один універсальний ключ. Це не так. У Telegram кілька систем автентифікації, і правильні облікові дані залежать від того, що робить ваше програмне забезпечення: керує ботом, авторизує особистий акаунт, впускає користувача на сайт чи перепідключає вже авторизований клієнт.

Різниця важлива, бо ці облікові дані мають різні повноваження. Токен бота керує одним ботом. API ID і API hash ідентифікують застосунок розробника. Код входу підтверджує тимчасовий доступ до номера телефону. Рядок сесії або файл сесії може зберігати завершену авторизацію особистого акаунта, а отже, може давати доступ до акаунта без нового запиту на вхід. Якщо вважати ці значення взаємозамінними, це водночас поширена помилка реалізації та серйозний ризик для безпеки.

У цьому посібнику пояснено, що робить кожен тип облікових даних, звідки він береться і як із ним безпечно поводитися. Також пояснено, чому підключення Telegram CRM або MCP для особистих акаунтів не те саме, що інтеграція через Bot API.

Якщо посібник просить «токен Telegram», зупиніться й визначте, який рядок таблиці мається на увазі, перш ніж щось копіювати.

Токен бота Telegram автентифікує бота в Bot API. Офіційний посібник Telegram про ботів радить розробникам створювати бота через @BotFather, зазвичай командою /newbot. BotFather повертає токен, який бекенд використовує під час виклику методів на кшталт getMe, sendMessage або setWebhook.

Токен бота зазвичай виглядає як числовий ідентифікатор бота, за яким іде двокрапка та довгий секрет. Не вставляйте справжній токен у документацію, скриншоти, повідомлення в чатах, трекери задач, клієнтський JavaScript або публічний репозиторій. Telegram прямо радить поводитися з токеном як із паролем, бо будь-хто, хто його має, може керувати ботом.

У токенів ботів є важливе обмеження: вони автентифікують бота, а не вашу особисту ідентичність у Telegram. Боти не можуть просто читати наявні приватні чати людини. Документація Telegram про ботів також пояснює, що боти не можуть першими почати розмову з користувачем: користувач має сам написати боту або додати його до групи. У групах налаштування приватності можуть додатково обмежувати, які повідомлення отримує бот.

Обирайте токен бота, коли будуєте сценарій із ботом: команди, сповіщення, меню, прийом звернень у підтримку, Mini App або автоматизований процес, у якому користувачі свідомо взаємодіють із ботом.

Клієнти для особистих акаунтів використовують MTProto API Telegram, а не покладаються лише на HTTP Bot API. Кожен сторонній застосунок Telegram належить до цієї категорії, тому вибір клієнта Telegram для робочого акаунта є питанням безпеки. Перш ніж застосунок зможе авторизувати користувача Telegram, його розробнику потрібні API ID і API hash.

Офіційна інструкція Telegram з реєстрації застосунку описує процес так:

1. Використайте активний номер телефону, зареєстрований у Telegram.
2. Увійдіть на my.telegram.org.
3. Відкрийте API development tools (інструменти розробки API).
4. Зареєструйте застосунок.
5. Надійно збережіть отримані api_id і api_hash.

API ID це числовий ідентифікатор застосунку. API hash це парний до нього секрет. Вони ідентифікують програмне забезпечення, яке запитує авторизацію, але самі по собі не входять у кожен акаунт Telegram. Процес авторизації користувача все одно потрібен.

Не копіюйте облікові дані API з випадкового проєкту на GitHub або прикладу застосунку. Telegram попереджає, що тестовий API ID у його відкритому коді обмежений і не підходить для застосунків, які випускають для користувачів. Робоча інтеграція має використовувати облікові дані, зареєстровані на організацію, яка нею керує, і дотримуватися умов використання API Telegram.

Коли клієнт MTProto авторизує особистий акаунт, Telegram зазвичай надсилає тимчасовий код входу через наявну сесію Telegram або інший підтримуваний канал. Якщо в акаунті ввімкнено двоетапну перевірку, Telegram також запитує додатковий пароль акаунта.

Жодне з цих значень не є обліковими даними API, які розробник має зберігати постійно. Код це тимчасове підтвердження того, що людина, яка контролює акаунт, схвалює вхід. Пароль двоетапної перевірки це пароль власника акаунта. Легітимний екран авторизації має пояснювати, навіщо потрібне значення, передавати його безпечно й не записувати в логи чи аналітику.

Ніколи не надсилайте код входу Telegram тому, хто називає себе підтримкою. Ніколи не вставляйте його в розмову з ботом. Запит коду входу поза процесом входу це серйозна ознака спроби захопити акаунт.

Після успішної авторизації бібліотеки MTProto зазвичай зберігають сесію. Залежно від бібліотеки, сесія може зберігатися в локальному файлі бази даних, зашифрованому записі або переносному рядку.

Сесія позбавляє користувачів потреби вводити новий код входу щоразу, коли застосунок перезапускається. Саме ця зручність робить її дуже чутливою. Дійсна сесія може відповідати вже авторизованому пристрою, тож її витік може дозволити сторонній особі діяти через акаунт, доки сесію не відкличуть.

Дотримуйтеся цих правил:

• Ніколи не комітьте сесії в Git.
• Ніколи не додавайте їх у браузерний код чи мобільну аналітику.
• Шифруйте їх у стані спокою керованим ключем, а не ключем, захардкодженим поруч із шифротекстом.
• Обмежте робочий доступ найвужчою можливою сервісною роллю.
• Приховуйте їх у логах і звітах про помилки.
• Дайте зрозумілий спосіб відключити акаунт і видалити збережену сесію.
• Відкличте скомпрометовану сесію на екрані Telegram Settings → Devices (Налаштування → Пристрої) і замініть пов'язані секрети.

Рядок сесії не є безпечнішою версією токена бота. Це інші облікові дані з потенційно ширшим доступом.

Telegram також підтримує вхід на сайти й у застосунки через Telegram Login, той самий «Telegram login API», про який пишуть більшість посібників, зокрема через процес OpenID Connect. Цей процес автентифікує користувача Telegram в іншому застосунку й повертає підписані дані про особу або токени з обмеженими правами. Він не дає автоматично дозволу читати особисті чати користувача в Telegram.

Використовуйте Telegram Login, коли мета звучить як «увійти в мій сервіс через Telegram». Використовуйте Bot API для бота. Використовуйте авторизований клієнт MTProto, коли продукту справді потрібні можливості особистого акаунта і в нього є зрозуміла модель згоди та безпеки.

MCP описує, як клієнт ШІ запитує інструменти й дії в сервера. Він не замінює автентифікацію Telegram. Серверу Telegram MCP все одно потрібен авторизований шар Telegram за ним.

Наприклад, Entergram підключає особисті акаунти Telegram до робочого простору через процес авторизації, який схвалює користувач. Потім хостований сервер Telegram MCP надає схваленому клієнту MCP визначені інструменти для CRM і обміну повідомленнями. Клієнт ШІ отримує доступ до інструментів; він не повинен отримувати сирі коди входу Telegram, API hash або сесії акаунтів, які можна використати повторно.

Таке розділення дає безпечнішу архітектуру:

1. Облікові дані Telegram залишаються всередині сервісу, відповідального за авторизацію в Telegram.
2. Сервер MCP надає лише вузько визначені операції.
3. OAuth і права в робочому просторі визначають, яка людина чи який клієнт ШІ може викликати ці операції.
4. Журнали аудиту фіксують бізнес-дії, не записуючи секрети автентифікації.
5. Відкликання може вимкнути клієнт MCP, не змушуючи користувача розкривати чи замінювати всі базові облікові дані Telegram.

Прочитайте Telegram MCP проти Bot API, щоб побачити різницю в можливостях.

Перш ніж випускати будь-яку інтеграцію з Telegram, дайте відповідь на ці запитання:

• Інтеграція діє як бот чи як особистий акаунт?
• Які чати й дії їй справді потрібні?
• Чи може користувач виключити приватні розмови або акаунти?
• Чи відокремлені дії запису від дій лише для читання?

• Чи зберігаються токени ботів, API hash і сесії лише на довірених серверах?
• Чи зашифровані секрети в стані спокою та захищені під час передавання?
• Чи виключені робочі облікові дані з системи контролю версій і превʼю-розгортань?
• Чи налаштовані логи, системи трасування та інструменти підтримки клієнтів так, щоб їх приховувати?

• Чи має кожен підключений акаунт визначеного власника?
• Чи може адміністратор відключити один акаунт, не зачепивши інших?
• Чи можна відкликати доступ для одного клієнта ШІ або одного співробітника окремо?
• Чи записуються привілейовані дії із зазначенням виконавця, часу, акаунта та результату?

• Чи є задокументована процедура заміни токена бота?
• Чи може команда швидко анулювати викрадену сесію?
• Чи сповіщає сервіс про незвичні місця входу або великий обсяг дій?
• Чи зашифровані резервні копії і чи поширюється на них та сама політика видалення?

Називати токеном будь-які облікові дані. Через це інженери вставляють не те значення не в те поле, а перевірки безпеки стають неоднозначними. Називайте змінні конфігурації точно: TELEGRAM_BOT_TOKEN, TELEGRAM_API_ID і TELEGRAM_API_HASH зрозуміліші, ніж TELEGRAM_TOKEN.

Класти токен бота у фронтенд-код. Усе, що потрапляє в браузер, слід вважати публічним. Спрямовуйте виклики Bot API через захищений бекенд.

Вважати, що API ID і API hash дорівнюють доступу до акаунта. Вони ідентифікують застосунок. Користувачу все одно потрібно авторизувати акаунт.

Вважати сесію нешкідливим кешем. Сесія це дані автентифікації. Захищайте її як облікові дані й передбачте можливість її відкликати.

Збирати більше доступу, ніж потрібно процесу. Боту для сповіщень не потрібна сесія особистого акаунта. Процесу звітності може не знадобитися право надсилати повідомлення. Починайте з найвужчої робочої схеми.

Отже, немає єдиного токена доступу, який Telegram видає для всього. Якщо ви хочете створити бота Telegram, створіть його через BotFather і використовуйте його токен на своєму бекенді. Якщо ви розробляєте авторизований клієнт Telegram для особистих акаунтів, зареєструйте власні API ID і API hash, потім пройдіть процес авторизації користувача Telegram і захистіть отриману сесію. Якщо вам потрібен лише вхід, використовуйте Telegram Login, а не запитуйте доступ до чатів.

Командам, які хочуть, щоб інструменти ШІ працювали зі схваленими особистими акаунтами Telegram, сервер Telegram MCP з контролем прав дозволяє не передавати сирі облікові дані Telegram у кожен клієнт ШІ. Хоч би який шлях ви обрали, тримайте секрети автентифікації подалі від промптів, репозиторіїв, браузерного коду та скриншотів і закладайте відкликання доступу в архітектуру з першого дня.