api_id и api_hash Telegram: получение, безопасность и правила

Что такое api_id и api_hash?

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

1. 1

   Зарегистрируйтесь в официальном приложении

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

2. 2

   Войдите на my.telegram.org

   Откройте https://my.telegram.org, введите номер в международном формате (+7..., +998...) и полученный код подтверждения.

3. 3

   Откройте «API development tools»

   В этом разделе находится форма создания приложения.

4. 4

   Заполните форму

   Укажите название приложения, короткое имя и остальные поля. По ToS в названии не должно быть слова «Telegram» (допускается только после слова «Unofficial»), а официальный логотип Telegram использовать нельзя.

5. 5

   Сохраните api_id и api_hash

   На странице появятся api_id, api_hash и адреса серверов MTProto. Не храните ключи в коде: используйте переменные окружения TELEGRAM_API_ID и TELEGRAM_API_HASH или хранилище секретов.

6. 6

   Подключите в Socialift (по желанию)

   В кабинете в разделе Kalitlar (ключи) → Telegram введите api_id и api_hash — они хранятся в зашифрованном виде и проверяются в Telegram. Затем в Ulanishlar (подключения) → аккаунт Telegram подключите аккаунт: телефон → код → при необходимости пароль 2FA.

Telegram API Terms of Service: на что обратить внимание

Ключевые пункты официальной страницы «Creating your Telegram Application» и API Terms of Service.

Процесс входа: телефон → код → пароль 2FA

В веб-приложении вход делится на два HTTP-запроса. phone_code_hash из первого шага действителен только внутри той же промежуточной сессии, поэтому передавайте на второй шаг и то, и другое.

import os
from socialift import TelegramAccount

API_ID = int(os.environ["TELEGRAM_API_ID"])
API_HASH = os.environ["TELEGRAM_API_HASH"]

async def start_login(phone: str) -> dict:
    async with TelegramAccount(api_id=API_ID, api_hash=API_HASH) as tg:
        return await tg.send_code(phone)  # phone_code_hash + промежуточная session

async def finish_login(phone: str, code: str, sent: dict, password: str | None = None) -> str:
    async with TelegramAccount(api_id=API_ID, api_hash=API_HASH,
                               session=sent["session"]) as tg:
        result = await tg.sign_in(phone, code, phone_code_hash=sent["phone_code_hash"])
        if result["two_factor_required"]:
            result = await tg.sign_in_password(password)
        return tg.export_session()  # равна паролю — храните зашифрованной

Повторное подключение по сохранённой сессии

import os
from socialift import TelegramAccount

async def get_account() -> TelegramAccount:
    tg = TelegramAccount(api_id=int(os.environ["TELEGRAM_API_ID"]),
                         api_hash=os.environ["TELEGRAM_API_HASH"],
                         session=os.environ["TELEGRAM_SESSION"])
    await tg.connect()
    if not await tg.is_authorized():
        await tg.disconnect()
        raise RuntimeError("Сессия отозвана — нужен повторный вход")
    return tg

Как безопасно хранить строку сессии

Строка из export_session() даёт полный доступ к аккаунту — без кода, пароля и 2FA.

• ▸Храните в базе только в зашифрованном виде (например, через KMS или отдельный ключ шифрования) и не держите ключ рядом с базой.
• ▸Не выводите сессию в логи, мониторинг ошибок и браузер.
• ▸Не используйте одну сессию одновременно в двух процессах: увидев параллельные основные соединения одной авторизации, Telegram вернёт AUTH_KEY_DUPLICATED и аннулирует сессию — понадобится повторный вход.
• ▸Отдельная сессия для каждого аккаунта; не копируйте одну строку между серверами.
• ▸Ненужную сессию закрывайте через log_out(); чужие устройства проверяйте и завершайте через sessions() и reset_session().
• ▸При новом входе другие сессии аккаунта получают уведомление — предупредите владельца аккаунта заранее.

Риск бана и FLOOD_WAIT: ответственное использование

Обработка FLOOD_WAIT

import asyncio
from socialift import RateLimitError

async def send_report(tg, text: str) -> None:
    try:
        await tg.send_message("@my_group", text)
    except RateLimitError as exc:        # Telegram: FLOOD_WAIT_X
        if (exc.retry_after or 0) > 300:
            raise                          # долгое ожидание — отложите задачу
        await asyncio.sleep(exc.retry_after or 5)
        await tg.send_message("@my_group", text)