Telegram API: как получить API ID и API Hash — пошаговая инструкция

Если вы хотите писать ботов, автоматизировать Telegram или подключить мессенджер к n8n — рано или поздно столкнётесь с понятиями API ID, API Hash и Bot Token. Разберём, что это такое, чем отличается Telegram Bot API от MTProto API и как получить нужные ключи через api.telegram.org и my.telegram.org.

Два типа Telegram API: Bot API vs MTProto

Telegram API — это не один интерфейс, а два разных. Оба работают по защищённому протоколу (Telegram API HTTPS):

Для большинства задач автоматизации достаточно Bot API — именно его использует n8n для Telegram-узла. API ID и API Hash нужны только при работе с MTProto (userbot, парсинг чатов, скачивание файлов через Telegram как пользователь).

Как получить Bot Token через BotFather

Для работы через Bot API нужен только токен бота. Запросы отправляются по адресу https api telegram bot / https://api.telegram.org/bot{TOKEN}/METHOD:

1. Откройте Telegram, найдите @BotFather
2. Отправьте команду /newbot
3. Введите название бота (например: «Мой автоматизатор»)
4. Введите username в формате my_automation_bot (обязательно заканчивается на bot)
5. Получите токен вида: 1234567890:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Этот токен используется в URL https api telegram org вида https://api.telegram.org/bot{TOKEN}/getUpdates. Команда telegram api getUpdates возвращает последние сообщения боту — удобно для отладки.

Как получить Telegram API ID и API Hash

Получить API Telegram ID и Hash можно только через официальный сайт разработчиков:

1. Откройте браузер и перейдите на my.telegram.org
2. Войдите с номером телефона (код придёт в Telegram)
3. Выберите раздел API Development Tools
4. Заполните форму: название приложения, платформа (Other)
5. Нажмите Create application
6. Получите api_id (числовой) и api_hash (строка)

Домен api telegram org — это официальный адрес серверов Bot API. Не путайте с my.telegram.org (сайт для разработчиков) и методом api telegram org getupdates (getUpdates в Bot API).

Безопасность: где хранить API ключи

API ID API Hash Telegram — это секретные данные. Если они попадут к третьим лицам, кто угодно сможет действовать от имени вашего аккаунта. Правила хранения:

• Никогда не публикуйте в Git/GitHub
• Храните в .env файле или менеджере секретов
• Если скомпрометированы — сбросьте через my.telegram.org
• Bot Token можно отозвать через BotFather командой /revoke

Telegram API Proxy: работа из России

Если api.telegram.org заблокирован в вашей сети, используйте Telegram API proxy. Для Bot API доступны два способа:

# Способ 1: SOCKS5 proxy
curl -x socks5://user:pass@proxy:1080   https://api.telegram.org/bot{TOKEN}/getMe

# Способ 2: Локальный Telegram Bot API server
# Официальный репозиторий: github.com/tdlib/telegram-bot-api

Telegram API server — официальное решение от Telegram для запуска локального Bot API. Актуально для снятия ограничений на размер файлов (2 ГБ вместо 50 МБ) и работы в изолированных сетях.

Подключение Telegram API в n8n

Для работы с Telegram в n8n используется Telegram Bot API (Bot Token). Настройка:

1. В n8n откройте Credentials → New Credential → Telegram API
2. Вставьте Bot Token из BotFather
3. Сохраните
4. Используйте узлы Telegram (сообщения) или Telegram Trigger (вебхук)

api.telegram.org/bot{TOKEN}/: структура URL

Базовый URL Bot API: https://api.telegram.org/bot{TOKEN}/METHOD

api telegram port: Bot API доступен на стандартном HTTPS-порту 443. Для локального Bot API server можно задать произвольный порт.

Лимиты и ограничения Telegram Bot API

При работе через api.telegram.org действуют официальные ограничения, которые важно знать заранее:

Если бот рассылает сообщения большому числу пользователей одновременно — соблюдайте лимит ~30 сообщений/сек, иначе Telegram вернёт ошибку 429 Too Many Requests с полем retry_after, указывающим сколько секунд подождать.

getUpdates vs Webhook: что выбрать

Два способа получать сообщения через Telegram Bot API:

• getUpdates (polling) — бот сам периодически опрашивает сервер Telegram. Проще в настройке, не нужен публичный HTTPS-адрес. Подходит для тестов и небольших ботов.
• Webhook — Telegram сам отправляет обновления на ваш сервер при поступлении сообщения. Требует HTTPS с валидным сертификатом. Быстрее реагирует, экономит ресурсы при большой нагрузке.

В n8n используется именно webhook-модель: нода Telegram Trigger автоматически регистрирует webhook через setWebhook при активации воркфлоу — вручную вызывать метод не нужно.

Типичные ошибки при получении API-ключей

"PHONE_NUMBER_INVALID" на my.telegram.org

Номер телефона нужно вводить в международном формате с кодом страны, без пробелов и скобок: +79991234567. Если код подтверждения не приходит — проверьте, не заблокированы ли уведомления от Telegram в самом приложении.

Bot Token не работает после получения

Частая причина — токен скопирован с пробелом в начале или конце. Проверьте через curl https://api.telegram.org/bot{TOKEN}/getMe — если возвращается JSON с данными бота, токен верный.

"Unauthorized" при вызове методов API

Либо токен неверный, либо бот был удалён/заблокирован через BotFather. Проверьте статус командой /mybots в чате с BotFather.

Как ограничить доступ к API-методам бота

Bot Token даёт полный доступ ко всем методам API. Если токен используется в нескольких системах (n8n, Python-скрипт, веб-сервис) — рекомендуется:

• Для каждой интеграции создавать отдельного бота через BotFather, а не делиться одним токеном
• Ограничивать IP, с которых разрешены запросы к вашему webhook-эндпоинту, на уровне nginx
• Логировать все вызовы sendMessage для отладки и аудита

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