Интеграция Telegram API
Socialift полностью поддерживает оба типа подключения к Telegram: аккаунт через MTProto (на базе Telethon) и бот через Bot API. Аккаунт работает как сам пользователь — полная история переписки, участники групп, статистика каналов; бот — для отправки сообщений, модерации и вебхуков. Оба подключения живут в том же SDK и с той же моделью ошибок, что и остальные платформы.
Обновлено:
Чем отличается API бота от API аккаунта в Telegram
В Telegram два разных API. Bot API — HTTP-интерфейс, который работает по токену от BotFather: бот отправляет сообщения, модерирует группы и получает обновления через вебхук. MTProto API работает от имени настоящего пользовательского аккаунта: полная история переписки, список участников групп, статистика каналов и другие возможности, закрытые для ботов.
Бот не может написать пользователю первым (человек сначала нажимает /start) и не может получить список всех участников группы — поэтому Socialift поддерживает и подключение аккаунта. Подробное сравнение, что и когда выбирать, — в статье «Bot API или MTProto» в ссылках ниже.
Возможности аккаунта и бота
| Возможность | Аккаунт (MTProto) | Бот (Bot API) |
|---|---|---|
| Отправка, редактирование, удаление, закрепление сообщений | есть | есть |
| Файлы: фото, видео, документы, аудио, голосовые | есть | есть |
| Модерация: бан, ограничения, назначение админов | есть | есть |
| Пригласительные ссылки | есть | есть |
| Публикация историй (Stories) | есть— с Premium или бустами | нет |
| Полная история переписки | есть | нет |
| Список участников группы | есть | нет |
| Статистика канала | есть | нет |
| Создание групп и каналов | есть | нет |
| Вызов метода, которого нет в SDK | raw() | call() |
естьнет
Примечания и ограничения
Пустые ячейки — следствие правил Telegram: Bot API не даёт ботам этих возможностей. Статистику канала Telegram отдаёт только админам каналов определённого размера — порог задаётся на сервере (флаг can_view_stats).
Вход в аккаунт: телефон → код → 2FA
Вход проходит в три шага. Затем tg.export_session() возвращает строку сессии — сохраните её в зашифрованном виде и в следующий раз подключайтесь через TelegramAccount(session=...) без кода. Сессию аккаунта, подключённого в кабинете, Socialift хранит на сервере в зашифрованном виде.
import asyncio, os
from socialift import TelegramAccount
async def main(session: str | None):
# session — ранее сохранённая строка сессии или None
async with TelegramAccount(api_id=int(os.environ["TELEGRAM_API_ID"]),
api_hash=os.environ["TELEGRAM_API_HASH"], session=session) as tg:
phone = "+998901234567"
sent = await tg.send_code(phone)
result = await tg.sign_in(phone, code="12345", phone_code_hash=sent["phone_code_hash"])
if result["two_factor_required"]:
await tg.sign_in_password("...")
new_session = tg.export_session() # сохраните в зашифрованном виде
chats = await tg.dialogs(limit=50)
history = await tg.messages("@durov", limit=50)
members = await tg.participants("@group", limit=500)
await tg.send_poll("@group", "Когда удобнее?", ["10:00", "15:00"])
await tg.send_file("me", "photo.jpg", caption="Отчёт")
asyncio.run(main(session=None))api_id и api_hash выдаются на my.telegram.org. Для подключения аккаунта SDK ставится с дополнением: pip install "socialift[telegram]".
Сервер Socialift за кабинетом и Playground держит пул MTProto-клиентов, поэтому там рукопожатие не повторяется при каждом запросе. В SDK переиспользуйте один объект TelegramAccount.
В пробный месяц (первые 30 дней) токен открывает все возможности SDK, включая TelegramAccount (возможность messaging в лицензии). После продления возможности зависят от тарифа токена — точный список показывает «Tekshirish va muhitlar» (проверка и окружения) в кабинете; в Playground кабинета методы аккаунта работают независимо от тарифа.
Что покрывает подключение аккаунта
Сообщения
Отправка, редактирование, удаление, пересылка и закрепление; реакции, опросы, отложенные сообщения, отметка о прочтении и статус «печатает».
Файлы и поиск
Отправка файлов и скачивание медиа; поиск внутри чата и глобальный поиск.
Данные групп и каналов
Информация о чате, участники, админы и заблокированные, права участников и статистика каналов.
Управление группами и каналами
Создание групп и каналов, вступление, выход, удаление; название, описание, slow mode, права по умолчанию и фото чата.
Участники и модерация
Приглашение, исключение, бан и разбан, ограничения, назначение и снятие админов; ссылки с лимитами и обработка заявок на вступление.
Контакты и сессии
Добавление и удаление контактов, блокировка, полная информация о пользователе, общие чаты, список активных сессий и их завершение.
Истории Telegram: кто может публиковать и на каких условиях
Истории живут только на стороне аккаунта (MTProto). Документация Telegram требует перед публикацией вызывать stories.canSendStory — в SDK это tg.can_send_story(entity): метод возвращает число свободных «слотов» под истории и даёт понятную ошибку, если условия не выполнены.
import asyncio, os
from socialift import TelegramAccount
async def main(session: str):
async with TelegramAccount(api_id=int(os.environ["TELEGRAM_API_ID"]),
api_hash=os.environ["TELEGRAM_API_HASH"], session=session) as tg:
print(await tg.can_send_story("me"))
print(await tg.story_targets())
await tg.send_story("me", "story.mp4", caption="Новый продукт",
period=86400, privacy="contacts")
active = await tg.stories("me")
print(active)
asyncio.run(main(os.environ["TELEGRAM_SESSION"]))Условия задаёт Telegram: для публикации от имени пользователя нужен **Telegram Premium** (иначе PREMIUM_ACCOUNT_REQUIRED), а от имени канала или супергруппы — право админа post_stories (CHAT_ADMIN_REQUIRED) и достаточное число **бустов** у канала (BOOSTS_REQUIRED). Список каналов, от имени которых можно публиковать, отдаёт tg.story_targets(), но попадание в список ещё не значит «можно опубликовать» — can_send_story всё равно вызывается.
period — сколько история живёт до ухода в архив: 21600 (6 часов), 43200 (12 часов), 86400 (24 часа) или 172800 (48 часов). **Без Premium работает только 86400**, остальные значения Telegram отклоняет; если параметр не передан, Telegram сам ставит 24 часа.
privacy принимает четыре значения: everyone (по умолчанию), contacts, close_friends и selected — в последнем случае allow обязателен. deny добавляет исключения («контакты, кроме такого-то»). При pinned=True история остаётся в профиле после истечения срока.
Медиа должно быть **вертикальным** фото или видео не тяжелее 30 МБ — размер SDK проверяет локально, до отправки. Соотношение сторон и длительность Telegram в документации числами не задаёт, поэтому невертикальное медиа в приложениях обрежется неудачно.
**Bot API публиковать истории не умеет вообще** — это ограничение Telegram, обойти его не может ни один SDK. Бот способен лишь ответить на присланную ему историю. Опубликованную историю можно отредактировать через tg.edit_story(entity, story_id, caption=...) и удалить через tg.delete_story(entity, story_id).
Бот: подключение по токену и любой метод Bot API
Подключение бота покрывает сообщения, файлы (фото, видео, документы, аудио, голосовые, анимации), информацию и настройки чата, админов, статус участника, модерацию, пригласительные ссылки, вебхук и getUpdates.
import asyncio, os
from socialift import Telegram
async def main():
async with Telegram(token=os.environ["TELEGRAM_BOT_TOKEN"]) as bot:
await bot.send_message("@my_channel", "Привет!")
# Любой метод Bot API, для которого в SDK нет отдельной обёртки
commands = await bot.call("getMyCommands")
print(commands)
asyncio.run(main())Bot API не подписывает тело: передайте secret_token в set_webhook и проверяйте, что он пришёл в заголовке X-Telegram-Bot-Api-Secret-Token. Пока вебхук установлен, get_updates не работает. При подключении бота в кабинете токен проверяется через getMe.
bot.call("имяМетода", ...) вызывает любой метод Bot API, а методы без обёртки клиент пробрасывает автоматически (bot.getChatMenuButton(...)). В универсальном вызове Playground в кабинете logOut и close намеренно заблокированы. На стороне аккаунта ту же роль выполняет tg.raw(...): он отправляет любой TL-запрос Telethon.
При планировании интеграции с Telegram
- Бот не может написать пользователю первым — диалог начинается после того, как человек нажал /start.
- Если нужен список участников группы или полная история переписки, выбирайте подключение аккаунта, а не бота.
- Статистика доступна, только если вы админ канала и Telegram выставил флаг
can_view_stats— порог задаётся на сервере Telegram. - Строка сессии даёт полный доступ к аккаунту: не оставляйте её в коде и логах, храните зашифрованной. Для аккаунтов, подключённых через кабинет, Socialift хранит её на сервере в зашифрованном виде.
- Для вебхука бота передайте свой секрет в
bot.set_webhook(url, secret_token=...)и проверяйте каждый запрос черезTelegram.verify_webhook(request.headers, secret)— Telegram не подписывает тело запроса. - Аккаунт работает как обычный пользователь: Telegram автоматически ставит под наблюдение аккаунты, вошедшие через неофициальные API-клиенты, а за флуд и спам блокирует навсегда. Не используйте аккаунт для массовых рассылок.
Частые вопросы
Можно ли получить всех участников группы Telegram через API?
Через бота — нет: Bot API отдаёт только список админов, число участников и статус отдельного участника. Через аккаунт (MTProto) participants() возвращает список участников, но если админы скрыли список (это возможно в больших группах), полностью он не вернётся.
Может ли бот написать пользователю первым?
Нет. По правилам Telegram человек сначала должен отправить боту /start. Аккаунт работает как обычный пользователь: Telegram автоматически ставит под наблюдение аккаунты, вошедшие через неофициальные API-клиенты, а за флуд и спам блокирует навсегда. Не используйте аккаунт для массовых рассылок.
Безопасно ли подключать аккаунт Telegram?
Вход проходит на стороне самого Telegram: номер телефона, код и, если включён, пароль двухэтапной проверки. При подключении через кабинет строка сессии хранится на сервере в зашифрованном виде и не попадает в браузер; в SDK её шифруете и храните вы. Список активных сессий можно посмотреть и завершить.
Почему не приходит статистика канала?
Telegram отдаёт статистику только админам каналов определённого размера; точный порог — серверная настройка, он виден во флаге channelFull.can_view_stats. Это ограничение уровня Telegram API, и Socialift не может его обойти.
Что делать, если нужного метода нет в SDK?
Для бота bot.call("имяМетода") вызывает любой метод Bot API (logOut и close заблокированы только в универсальном вызове Playground в кабинете). Для аккаунта tg.raw(...) отправляет любой TL-запрос Telethon.
Socialift — официальный партнёр Telegram?
Нет. Socialift — независимый слой интеграции поверх публичных Bot API и MTProto API Telegram. Статуса официального партнёра Telegram у него нет.
Источники
Связанные страницы
Подключите Telegram сегодня
Получите токен, подключите бота или аккаунт и отправьте первое сообщение из Playground.
Получить бесплатный токен →