← Все статьи
Сравнение

Telegram API ID и API hash или токен бота: какие учётные данные нужны?

Токен Telegram-бота авторизует одного бота в HTTP Bot API, но не выполняет вход в личный аккаунт Telegram. API ID и API hash идентифицируют клиентское приложение и требуются для авторизации пользовательского аккаунта через MTProto API Telegram, в том числе по коду или QR-коду. Выбирайте учётные данные исходя из того, от чьего имени должна работать интеграция: бот → токен бота; существующий пользовательский аккаунт → API ID и API hash.

Главное

  • Получите токен бота у @BotFather, если интеграция должна работать как отдельный Telegram-бот.
  • Получите API ID и API hash на my.telegram.org, если приложению нужно авторизовать существующий пользовательский аккаунт Telegram.
  • Токен бота не заменяет API ID/API hash, а сканирование QR-кода не отменяет необходимость в учётных данных приложения.
  • Не храните токены ботов, API hash, коды входа и данные авторизованных сессий в системе контроля версий и логах.
  • Чтобы подключить обычный аккаунт Telegram к UnifyPort, следуйте руководству по авторизации Telegram и используйте API ID и API hash; не вставляйте в этот процесс токен от BotFather.

Telegram API ID и API hash или токен бота

Эти понятия легко перепутать, поскольку все три значения предоставляют тот или иной доступ к Telegram. Но они относятся к разным API и авторизуют разные идентификации.

Что вы создаётеУчётные данныеГде их получитьОт чьего имени работает интеграция после авторизации
Интеграция с HTTP Bot APIТокен бота@BotFatherОт имени отдельного аккаунта бота
Клиент, который выполняет вход в пользовательский аккаунт TelegramAPI ID + API hash, затем код, QR-код или другой поддерживаемый способ входа пользователяmy.telegram.org → API development toolsОт имени авторизованного пользовательского аккаунта
Подключение пользовательского аккаунта в UnifyPortAPI ID + API hash для авторизации по коду или QR-кодуmy.telegram.orgОт имени аккаунта Telegram, в котором подтверждён вход

В официальном руководстве Telegram для ботов прямо сказано: токен бота авторизует бота, а не ваш аккаунт. Токен передаётся в запросах к таким адресам, как https://api.telegram.org/bot<TOKEN>/getMe, и его можно отозвать через @BotFather.

API ID и API hash, напротив, относятся к клиентскому приложению Telegram. Telegram выдаёт их после входа на my.telegram.org и заполнения формы API development tools. Затем при авторизации пользователя эти учётные данные приложения используются вместе с действием, которое выполняет сам пользователь. Например, метод auth.sendCode принимает номер телефона, api_id и api_hash; после успешной авторизации созданная клиентская сессия связывается с пользователем.

Именно в этом главное различие: токен бота позволяет интеграции работать от имени бота, а API ID/API hash идентифицируют клиент, участвующий во входе в пользовательский аккаунт.

Какие учётные данные выбрать?

Начните с того, кто должен получать или отправлять сообщения.

Выберите токен бота, если подходит работа от имени отдельного бота

Используйте официальный Bot API, если пользователи будут намеренно общаться с ботом по его имени, добавлять его в группы или использовать функции, доступные ботам. Создайте бота через @BotFather, храните его токен как пароль и получайте обновления Bot API с помощью опроса или Telegram webhook.

Обычно это самый понятный путь для продукта, который работает только с Telegram и изначально построен вокруг бота. Жизненным циклом бота управляет Telegram, API является официальным, а авторизовывать сессию личного аккаунта не нужно. В нашем сравнении нативной автоматизации чатов Telegram и единой очереди входящих сообщений из разных каналов подробнее разобрано, когда эта официальная модель подходит лучше всего.

Выберите API ID и API hash, если нужна работа от имени пользовательского аккаунта

Используйте клиентский API Telegram, если продукт должен авторизовать существующий аккаунт Telegram, а не создавать отдельного бота. Сначала приложение идентифицирует себя с помощью API ID и API hash. Затем владелец аккаунта выполняет вход, например подтверждает проверочный код или QR-код и проходит 2FA, если она включена.

API ID/API hash сами по себе не означают, что вход в аккаунт уже выполнен. Они идентифицируют приложение, а пользовательская авторизация создаёт сессию аккаунта. Аналогично, номер телефона или QR-код не заменяет учётные данные приложения.

Если ваша конечная цель — передавать сообщения из существующего аккаунта Telegram в другую систему, журнал создания ретранслятора Telegram — Slack показывает архитектуру webhook после подключения аккаунта.

Как получить API ID и API hash на my.telegram.org

Официальный процесс Telegram короткий, но важно выбрать правильные разделы:

  1. Зарегистрируйте и поддерживайте активный номер телефона в официальном приложении Telegram.
  2. Откройте my.telegram.org и войдите в аккаунт на странице /auth.
  3. Выберите API development tools.
  4. Заполните форму приложения.
  5. Сохраните полученные api_id и api_hash в серверном хранилище учётных данных.

Сейчас Telegram разрешает получить только один API ID для каждого номера телефона и предупреждает, что использование клиентских библиотек отслеживается для выявления злоупотреблений. Для выпущенного приложения используйте собственные учётные данные, соблюдайте Условия использования API Telegram и никогда не переносите в рабочую среду API ID с ограничениями, приведённый в качестве примера в приложениях Telegram с открытым исходным кодом.

Нужны ли API ID и API hash при входе по QR-коду?

Да. QR-код меняет способ, которым пользователь подтверждает вход, но не меняет клиентское приложение, запрашивающее авторизацию.

Официальный сценарий Telegram для QR-кода начинается с auth.exportLoginToken, среди параметров которого есть api_id и api_hash. Клиент отображает возвращённый токен в виде QR-кода tg://login, а пользователь сканирует и подтверждает его в приложении Telegram, где уже выполнен вход. Telegram указывает, что токен входа обычно истекает примерно через 30 секунд, поэтому просроченный QR-код нужно обновить.

Поэтому выбирать между «QR-кодом или учётными данными API» неправильно. При авторизации пользователя QR-код служит способом подтверждения, который используется вместе с учётными данными приложения.

Роль UnifyPort

UnifyPort подключает обычный аккаунт Telegram через неофициальный интерфейс, а не создаёт Telegram-бота. Поэтому при авторизации по коду и QR-коду используется путь учётных данных пользовательского аккаунта.

Для авторизации по коду создайте аккаунт с provider: "telegram", auth_mode: "code" и следующими реальными полями:

{
  "provider": "telegram",
  "auth_mode": "code",
  "provider_data": {
    "api_id": 12345678,
    "api_hash": "0123456789abcdef0123456789abcdef",
    "phone": "+886912345678"
  }
}

При авторизации по QR-коду поля provider_data.api_id и provider_data.api_hash по-прежнему обязательны, а владелец аккаунта подтверждает недолговечный QR-код в Telegram. В справочнике API авторизации Telegram перечислены точные шаги для кода, QR-кода, 2FA и сессии.

После авторизации входящие сообщения Telegram могут поступать в виде того же подписанного события message.received, которое используется для других подключённых провайдеров. Токен BotFather не передаётся в этом сценарии подключения обычного аккаунта.

Ограничения и компромиссы

Используйте официальный Bot API Telegram, если продукту подходит работа от имени отдельного бота. Этот API специально создан для ботов и не требует поддерживать сессию пользовательского аккаунта.

Используйте клиентский сценарий с пользовательским аккаунтом только тогда, когда действительно нужен существующий аккаунт. В результате авторизации создаются конфиденциальные данные сессии, на аккаунт продолжают распространяться правила Telegram, а доступ к API не даёт разрешения на спам и другие запрещённые действия. UnifyPort не превращает токен бота в пользовательскую сессию, не создаёт API ID от вашего имени и не отключает механизмы контроля платформы Telegram.

Также не смешивайте этот выбор с Telegram Login для сайтов. Текущая система входа Telegram для веб-сайтов использует OpenID Connect и собственную конфигурацию клиента; она не заменяет ни токен Bot API, ни авторизацию пользовательского аккаунта через MTProto.

Часто задаваемые вопросы

Telegram API ID — это то же самое, что токен бота?

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

Нужны ли API ID и API hash, если у меня уже есть токен бота?

Для обычных HTTP-запросов к Bot API — нет. Для этого бота нужен его токен. API ID и API hash нужны, когда интеграция авторизует пользователя Telegram через клиентский API; токен бота не может выполнить вход за такого пользователя.

Где найти my.telegram.org/auth?

Откройте https://my.telegram.org/ и войдите с помощью номера телефона Telegram. После авторизации выберите API development tools, чтобы создать или просмотреть API ID и API hash, связанные с этим номером.

Можно ли войти по QR-коду без API hash?

Нет. Запрос Telegram auth.exportLoginToken включает как api_id, так и api_hash. QR-код — это этап подтверждения со стороны пользователя, а не замена учётных данных приложения.

Можно ли подключить Telegram к UnifyPort с токеном BotFather?

Не в сценарии авторизации обычного аккаунта Telegram. В режимах кода и QR-кода используются provider_data.api_id и provider_data.api_hash; в режиме кода также требуется номер телефона аккаунта. Если интеграция должна работать от имени бота, используйте официальный Bot API напрямую.

Следующий шаг

Если вам нужно подключить существующий аккаунт Telegram, откройте руководство по авторизации Telegram и выберите сценарий с кодом или QR-кодом. Если интеграция должна работать только от имени бота, используйте @BotFather и официальный Bot API.

Источники

Источники и документация продукта проверены 2026-07-19.