← API

Python SDK

Пакет telefeeds-sdk импортируется как telefeeds. Он не устанавливает Pyrogram: отдельно установите реализацию, которая должна предоставить namespace pyrogram, например Kurigram.

pip install telefeeds-sdk kurigram

from telefeeds.pyrogram import Telefeeds, Router
from pyrogram import Client, filters
from pyrogram.types import Message

app = Telefeeds(token="telefeeds_...")
router = Router(name="messages")

@router.on_message(filters.text)
async def message(client: Client, message: Message):
    print(client.session_peer_id, message.text)
    await message.reply("received")

app.include_router(router)
app.start()

Один объект Telefeeds держит одно TLS gRPC-соединение. Для каждого session_peer_id создаётся отдельный лёгкий экземпляр выбранного pyrogram.Client со своим peer storage; его session.invoke работает через Telefeeds. SDK автоматически передаёт pyrogram.raw.all.layer установленного Pyrogram/Kurigram в подписке и каждом Invoke. Значение можно явно задать через Telefeeds(..., tl_layer=228). ClientHub поддерживает слои 227–229 и преобразует их в единый внутренний слой 229. Вручную вызывать InvokeWithLayer или InitConnection не требуется.

Управление сессиями

await app.unsubscribe_session(peer_id)
assert not await app.is_session_subscribed(peer_id)
await app.subscribe_session(peer_id)

page = await app.list_sessions(page_size=300)

Пауза прекращает апдейты этой сессии во всех каналах интеграции, но оставляет сессию запущенной и доступной для Invoke. Список читается без запроса runtime-метрик у Core и поддерживает cursor pagination.

Медиа

send_document, download_media и остальные методы используют частичный transport поверх Invoke. Загрузки идут частями по 512 KiB, скачивания — по 1 MiB и всегда с cdn_supported=False. Реализованы таймаут и повтор конкретной части, отмена asyncio task, FILE_MIGRATE_X, FILE_PART_X_MISSING и обновление ссылки сообщения при FILE_REFERENCE_EXPIRED. ClientHub ограничивает параллелизм по токену и сессии и показывает счётчики байтов в snapshot.

Регистрация

from telefeeds import AuthorizationState, TelefeedsClient

async with TelefeedsClient("telefeeds_...") as gateway:
    challenge = await gateway.begin_phone_authorization("+995...")
    result = await gateway.complete_phone_authorization(
        challenge.authorization_id, input("Telegram code: ")
    )
    if result.state == AuthorizationState.PASSWORD_REQUIRED:
        session = await gateway.complete_password_authorization(
            challenge.authorization_id, input("2FA password: ")
        )

Одновременно можно держать до трёх незавершённых регистраций. Попытка закрывается через час или вызовом cancel_authorization(). Каждый RPC получает authorization: Bearer <integration_access_token>. ClientHub проверяет, что токену принадлежит запрошенный session_peer_id, до передачи запроса в Core.

Контракт и версии

Текущий package — telefeeds.telegram.v1. Совместимые поля и RPC добавляются в v1; несовместимый контракт получает новую версию. Скачать актуальный protobuf-контракт.