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

Многие ищут «токен доступа Telegram», как будто Telegram выдаёт один универсальный ключ. Это не так. В Telegram несколько систем аутентификации, и нужные учётные данные зависят от задачи: управляет ли ваша программа ботом, авторизует личный аккаунт, выполняет вход пользователя на сайт или переподключает уже авторизованный клиент.

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

В этом руководстве разобрано, что делает каждый вид учётных данных, откуда он берётся и как с ним безопасно обращаться. Заодно объясняется, почему подключение Telegram CRM или MCP к личным аккаунтам устроено иначе, чем интеграция через Bot API.

Если руководство просит «токен Telegram», остановитесь и определите, о какой строке таблицы идёт речь, прежде чем что-то копировать.

Токен бота аутентифицирует бота в Bot API. Официальное руководство по ботам предлагает создать бота через @BotFather, обычно командой /newbot. BotFather возвращает токен, который бэкенд использует при вызове методов вроде getMe, sendMessage или setWebhook.

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

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

Выбирайте токен бота, когда строите именно бота: команды, уведомления, меню, приём обращений в поддержку, Mini App или автоматизированный процесс, в котором пользователи осознанно общаются с ботом.

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

Официальная инструкция по регистрации приложения описывает процесс так:

1. Используйте активный номер телефона, зарегистрированный в Telegram.
2. Войдите на my.telegram.org.
3. Откройте API development tools.
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 в разделе Настройки → Устройства и смените связанные секреты.

Строка сессии не безопасная версия токена бота. Это другой вид учётных данных, потенциально с гораздо более широким доступом.

Telegram также поддерживает вход на сайты и в приложения через Telegram Login, в том числе по протоколу OpenID Connect. Эта процедура аутентифицирует пользователя Telegram в другом приложении и возвращает подписанные данные о личности или токены с ограниченной областью действия. Права читать личный inbox пользователя в Telegram она автоматически не даёт.

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

MCP описывает, как AI-клиент запрашивает у сервера инструменты и действия. Аутентификацию Telegram он не заменяет: за Telegram MCP-сервером всё равно должен стоять авторизованный слой Telegram.

Например, Entergram подключает личные аккаунты Telegram к рабочему пространству через процедуру авторизации, которую одобряет пользователь. Затем размещённый Telegram MCP-сервер открывает одобренному MCP-клиенту определённый набор инструментов CRM и переписки. AI-клиент получает доступ к инструментам, но не должен получать исходные коды входа Telegram, API hash или многоразовые сессии аккаунта.

Такое разделение безопаснее:

1. Учётные данные Telegram остаются внутри сервиса, отвечающего за авторизацию в Telegram.
2. MCP-сервер открывает только чётко определённые операции.
3. OAuth и права рабочего пространства определяют, какой человек или AI-клиент может вызывать эти операции.
4. Журналы аудита фиксируют рабочие действия, не записывая секреты аутентификации.
5. Отзыв доступа отключает MCP-клиента, и пользователю не нужно раскрывать или менять все исходные учётные данные Telegram.

О разнице в возможностях читайте в статье Telegram MCP или Bot API.

Прежде чем выпускать любую интеграцию с Telegram, ответьте на эти вопросы.

• Интеграция действует как бот или как личный аккаунт?
• Какие чаты и действия ей на самом деле нужны?
• Может ли пользователь исключить личные переписки или аккаунты?
• Отделены ли действия записи от действий только для чтения?

• Хранятся ли токены ботов, API hash и сессии только на доверенных серверах?
• Зашифрованы ли секреты при хранении и защищены ли при передаче?
• Исключены ли рабочие учётные данные из системы контроля версий и превью-развёртываний?
• Настроены ли логи, системы трассировки и инструменты поддержки так, чтобы скрывать их?

• Есть ли у каждого подключённого аккаунта конкретный владелец?
• Может ли администратор отключить один аккаунт, не затрагивая остальные?
• Можно ли отозвать доступ одного AI-клиента или сотрудника отдельно от других?
• Фиксируются ли привилегированные действия с указанием исполнителя, времени, аккаунта и результата?

• Есть ли описанная процедура замены токена бота?
• Может ли команда быстро аннулировать украденную сессию?
• Предупреждает ли сервис о входах из необычных мест или о большом объёме действий?
• Зашифрованы ли резервные копии и распространяется ли на них та же политика удаления?

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

Класть токен бота во фронтенд. Всё, что попадает в браузер, следует считать публичным. Направляйте вызовы Bot API через защищённый бэкенд.

Считать, что API ID и API hash дают доступ к аккаунту. Они идентифицируют приложение. Пользователь всё равно должен авторизовать аккаунт.

Относиться к сессии как к безобидному кэшу. Сессия это материал для аутентификации. Защищайте её как учётные данные и предусмотрите возможность её отозвать.

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

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

Командам, которые хотят, чтобы AI-инструменты работали с одобренными личными аккаунтами Telegram, Telegram MCP-сервер с разграничением прав позволяет не передавать исходные учётные данные Telegram в каждый AI-клиент. Какой бы путь вы ни выбрали, не допускайте секреты аутентификации в промпты, репозитории, код для браузера и скриншоты, а возможность отзыва доступа закладывайте в архитектуру с первого дня.