Telegram api_id и api_hash: как получить и где хранить

Если Telegram не выдает api_id или форма возвращает ошибку, спросите в комментариях моего Telegram-канала. Там же я пишу о новых инструментах для Telegram-ботов и агентов.

В Telegram два разных API, и путают их чаще всего. Bot API действует от имени бота, токен для него выдает @BotFather, а запросы идут на api.telegram.org. Клиентское API на протоколе MTProto работает от имени человека, и только ему нужны api_id и api_hash. Если вы пишете бота, хватит токена, а проверить его, посмотреть обновления и вебхук можно в проверке Telegram-бота.

Как получить api_id и api_hash

1. Зарегистрируйте аккаунт через официальное приложение Telegram, если его еще нет.
2. Откройте my.telegram.org и войдите по номеру телефона. Код подтверждения придет сообщением в Telegram.
3. Выберите раздел API development tools и заполните форму о приложении, в ней достаточно названия и короткого имени.
4. Отправьте форму. На странице появятся api_id (число) и api_hash (строка из 32 символов).

По документации Telegram на 30 сентября 2026 года к одному номеру привязывается только один api_id. На этот номер приходят важные уведомления для разработчиков, поэтому указывайте тот, которым пользуетесь.

Как проверить, что ключи работают

Проще всего проверить пару первым входом через библиотеку. У Telegram MCP Server для этого есть скрипт. Он берет переменные TELEGRAM_API_ID и TELEGRAM_API_HASH из файла .env, спрашивает номер и код и печатает строку сессии.

uv run session_string_generator.py --phone

Если после ввода кода скрипт напечатал строку сессии, пара рабочая. Ошибка 400 API_ID_INVALID значит, что api_id и api_hash не совпадают между собой или скопированы с лишним символом. Ошибка 406 PHONE_NUMBER_INVALID относится к номеру, его вводят в международном формате, например +7 и 10 цифр. Код 400 PHONE_NUMBER_BANNED означает, что номер заблокирован в Telegram.

Где хранить api_hash и файл сессии

api_hash нужно хранить как пароль, в переменных окружения или в менеджере секретов. В коде и в публичном репозитории его быть не должно, поэтому .env стоит добавить в .gitignore до первого коммита.

Файл или строка сессии опаснее самого api_hash. В них лежит ключ авторизации, и с ним программа работает от вашего имени без кода подтверждения. Если файл сессии утек, завершите этот сеанс в разделе «Устройства» в настройках Telegram.

За что Telegram блокирует аккаунт

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

Тестовый api_id, который Telegram вшивает в свои открытые приложения, подходит только для проверки. Если выпустить с ним приложение, пользователи получат ошибку 400 API_ID_PUBLISHED_FLOOD, поэтому перед публикацией нужен свой. Если аккаунт заблокировали после работы с API, а правила вы не нарушали, напишите на recover@telegram.org и объясните, для чего используете API. Письма читают люди, автоматические рассылки блокируют.

Права агента с вашими ключами

С api_id, api_hash и сессией агент читает и отправляет сообщения от вашего имени во всех чатах. В каталоге 49 карточек для Telegram. С личным аккаунтом из них работают, в частности, два инструмента с разным уровнем доступа.

Telegram MCP Server на Telethon, 1730 ★ репозитория, помечен высоким риском: строка сессии дает полный доступ к аккаунту, а сервер умеет отправлять и удалять сообщения и менять настройки чатов. Автоматической установки у него нет, сервер собирают из репозитория командой uv sync, нужен Python 3.10 или новее. Автор предупреждает, что пакет telegram-mcp в PyPI принадлежит другому проекту, поэтому ставить сервер через pip или uvx нельзя. Начните с переменной TELEGRAM_EXPOSED_TOOLS=read-only, тогда агент получит только читающие инструменты.

Telegram Search, 4110 ★ репозитория, помечен средним риском. Скилл выгружает историю в локальную базу и ищет по ней в режиме только чтения, а массовая выгрузка требует вашего согласия через Telegram Takeout.

npx skillfoxx add skills/telegram-search

Все карточки для Telegram, включая MCP-серверы для ботов, собраны на странице сервиса. У каждой есть уровень риска с причинами.