Клиент Telegram-бота (Bot API): справочник методов

Вызывает метод Bot API close: закрывает текущий экземпляр бота перед переносом с одного локального сервера Bot API на другой. Называется close_bot, потому что close() в клиентах SDK закрывает HTTP-сессию.

await bot.close_bot(*, token: Optional[str] = None) -> bool

• ▸Сначала удалите webhook, иначе после перезапуска сервера бот может запуститься снова.
• ▸В первые 10 минут после запуска бота Telegram возвращает ошибку 429.

Удаляет список команд для указанных scope и языка (deleteMyCommands). После этого пользователи видят список более высокого уровня (например, scope по умолчанию).

await bot.delete_my_commands(
    *,
    scope: Optional[dict] = None,
    language_code: Optional[str] = None,
    token: Optional[str] = None,
) -> bool

Создаёт клиент с токеном из переменной окружения TELEGRAM_BOT_TOKEN; остальные аргументы (timeout, retry, license_key, session) передаются в конструктор. Рекомендуемый способ, чтобы токен не попадал в код.

Telegram.from_env(**kwargs) -> Telegram

• ▸Если переменная пуста, клиент всё равно создаётся — ConfigurationError возникнет при первом запросе (если в сам вызов не передан token=).

Возвращает профиль бота (getMe) в виде dict: id, username, can_join_groups, can_read_all_group_messages и другие поля. Самый простой способ проверить, что токен рабочий.

await bot.get_me(*, token: Optional[str] = None) -> dict

• ▸can_read_all_group_messages равно true, если privacy mode отключён.
• ▸Ответ HTTP 401 или "Unauthorized" SDK превращает в AuthError.

me = await bot.get_me()

Возвращает команды, заданные для указанных scope и language_code (getMyCommands). Пустой список означает, что для этой комбинации команды не заданы.

await bot.get_my_commands(
    *,
    scope: Optional[dict] = None,
    language_code: Optional[str] = None,
    token: Optional[str] = None,
) -> list

Выводит бота из облачного сервера Bot API Telegram (logOut). Нужен только перед переносом бота на собственный (локальный) сервер Bot API.

await bot.log_out(*, token: Optional[str] = None) -> bool

• ▸После вызова бот 10 минут не сможет снова войти на облачный сервер.
• ▸SDK отправляет запросы только на https://api.telegram.org, поэтому с локальным сервером этот клиент работать не будет.
• ▸В универсальном вызове Playground в кабинете logOut и close заблокированы.

Задаёт список команд в меню бота (setMyCommands), при необходимости отдельно для scope (например, только админы групп) и language_code. Формат: [{"command": "start", "description": "..."}].

await bot.set_my_commands(
    commands: list,
    *,
    scope: Optional[dict] = None,
    language_code: Optional[str] = None,
    token: Optional[str] = None,
) -> bool

• ▸Не более 100 команд; команда — 1–32 символа (строчные латинские буквы, цифры, _), описание — 1–256 символов.
• ▸Telegram показывает пользователю самый точный подходящий список: сначала чат + язык, в конце — scope по умолчанию.

Удаляет webhook (deleteWebhook), после чего можно вернуться к get_updates или poll. drop_pending_updates=True отбрасывает ещё не доставленные обновления.

await bot.delete_webhook(
    *,
    drop_pending_updates: Optional[bool] = None,
    token: Optional[str] = None,
) -> bool

await bot.delete_webhook()

Получает новые обновления через long polling (getUpdates) и возвращает список dict Update. Чтобы подтвердить обработанные события, в следующем запросе передайте offset = последний update_id + 1.

await bot.get_updates(
    *,
    offset: Optional[int] = None,
    limit: Optional[int] = None,
    timeout: int = 30,
    allowed_updates: Optional[list[str]] = None,
    token: Optional[str] = None,
) -> list

• ▸Не работает, пока установлен webhook; недоставленные обновления Telegram хранит не дольше 24 часов.
• ▸SDK ограничивает timeout таймаутом клиента минус 10 секунд (клиент 30 с по умолчанию → ожидание 20 с); для более долгого ожидания создайте Telegram(token=..., timeout=90).
• ▸limit — 1–100 (по умолчанию 100).

updates = await bot.get_updates(limit=50, timeout=0)

Возвращает состояние webhook (getWebhookInfo): url, pending_update_count, last_error_date, last_error_message, max_connections, allowed_updates. Если события перестали приходить, начните диагностику отсюда.

await bot.get_webhook_info(*, token: Optional[str] = None) -> dict

• ▸Если бот использует getUpdates, url будет пустой строкой.

info = await bot.get_webhook_info()

Помощник SDK: бесконечный поток async for поверх getUpdates, offset сдвигается автоматически. Для скриптов и воркеров без публичного HTTPS-адреса.

bot.poll(
    *,
    allowed_updates: Optional[list[str]] = None,
    timeout: int = 30,
    token: Optional[str] = None,
) -> AsyncIterator[dict]

• ▸При RateLimitError ждёт retry_after (или 5 с); при других ошибках API пишет предупреждение в логгер socialift.telegram и повторяет через 5 с — неверный токен или установленный webhook цикл не остановят, поэтому сначала проверьте get_me() и get_webhook_info().
• ▸offset хранится только в памяти: после перезапуска последняя неподтверждённая пачка может прийти снова — отсеивайте дубликаты по update_id.

Сообщает Telegram, что обновления нужно отправлять HTTPS POST-запросами на ваш url (setWebhook). Всегда передавайте secret_token — входящий запрос проверяется через verify_webhook.

await bot.set_webhook(
    url: str,
    *,
    secret_token: Optional[str] = None,
    allowed_updates: Optional[list[str]] = None,
    drop_pending_updates: Optional[bool] = None,
    max_connections: Optional[int] = None,
    certificate: Union[bytes, socialift.telegram.InputFile, NoneType] = None,
    token: Optional[str] = None,
    ip_address: Optional[str] = None,
    **extra: Any,
) -> bool

• ▸Порты: 443, 80, 88, 8443. secret_token — 1–256 символов, только A-Z, a-z, 0-9, _ и -.
• ▸Пока webhook установлен, get_updates и poll обновлений не получают.
• ▸По умолчанию chat_member, message_reaction и message_reaction_count не приходят — запросите их явно в allowed_updates; если параметр не передан, сохраняется прежняя настройка.

await bot.set_webhook("https://siz.uz/tg", secret_token="...", allowed_updates=["message"])

Проверяет, что заголовок X-Telegram-Bot-Api-Secret-Token входящего webhook-запроса совпадает с secret_token, заданным в set_webhook, и возвращает True/False. Синхронный статический метод, в сеть не обращается.

Telegram.verify_webhook(headers, secret_token: str) -> bool

• ▸Bot API не подписывает тело webhook (как X-Hub-Signature-256 у Meta) — проверка идёт только по этому заголовку, поэтому без secret_token любой, кто знает адрес, может прислать поддельное событие.
• ▸Сравнение выполняется за постоянное время; пустой secret_token всегда даёт False. Та же функция: socialift.webhooks.verify_telegram_request.
• ▸Передавайте регистронезависимый объект заголовков фреймворка; в обычном dict найдутся только точное написание X-Telegram-Bot-Api-Secret-Token и полностью строчное.

Копирует сообщение без ссылки на оригинал (copyMessage) и возвращает не полный Message, а только новый message_id (MessageId). caption заменяет подпись медиа; если не передан, остаётся исходная.

await bot.copy_message(
    chat_id: Union[int, str],
    from_chat_id: Union[int, str],
    message_id: int,
    *,
    caption: Optional[str] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸Нельзя копировать служебные сообщения, платные медиа, розыгрыши, итоги розыгрышей и счета (invoice).
• ▸Викторину можно скопировать, только если боту известны правильные ответы (correct_option_ids).

Копирует 1–100 сообщений без ссылок на оригиналы (copyMessages), сохраняя группировку альбомов. Возвращает список MessageId.

await bot.copy_messages(
    chat_id: Union[int, str],
    from_chat_id: Union[int, str],
    message_ids: Iterable[int],
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> list

• ▸ID в строго возрастающем порядке; ненайденные или некопируемые сообщения пропускаются.

Пересылает одно сообщение с пометкой «Переслано от» (forwardMessage) и возвращает новый Message. Если источник показывать нельзя, используйте copy_message.

await bot.forward_message(
    chat_id: Union[int, str],
    from_chat_id: Union[int, str],
    message_id: int,
    *,
    message_thread_id: Optional[int] = None,
    disable_notification: Optional[bool] = None,
    protect_content: Optional[bool] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸Служебные сообщения и сообщения с защищённым контентом переслать нельзя.
• ▸У этой обёртки нет **extra — для новых параметров используйте call("forwardMessage", ...).

Пересылает 1–100 сообщений одним запросом (forwardMessages) и возвращает список объектов MessageId (только ID). Группировка альбомов сохраняется.

await bot.forward_messages(
    chat_id: Union[int, str],
    from_chat_id: Union[int, str],
    message_ids: Iterable[int],
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> list

• ▸ID должны идти в строго возрастающем порядке.
• ▸Ненайденные или непересылаемые сообщения пропускаются без ошибки.

Сокращение SDK: send_message с reply_parameters={"message_id": message_id} — новое сообщение отображается как ответ на указанное. Остальные аргументы send_message передаются без изменений.

await bot.reply(
    chat_id: Union[int, str],
    message_id: int,
    text: str,
    **kwargs: Any,
) -> dict

• ▸Не передавайте reply_parameters сами — он уже задан, повторный аргумент вызовет TypeError в Python.

Показывает в чате статус вроде «печатает…» или «отправляет фото…», пока бот готовит ответ (sendChatAction). Действие по умолчанию — typing.

await bot.send_chat_action(
    chat_id: Union[int, str],
    action: str = 'typing',
    *,
    message_thread_id: Optional[int] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> bool

• ▸Статус держится 5 секунд или меньше и исчезает, когда приходит сообщение бота, — при долгой операции повторяйте вызов.
• ▸Действия: typing, upload_photo, record_video, upload_video, record_voice, upload_voice, upload_document, choose_sticker, find_location, record_video_note, upload_video_note.

Отправляет карточку контакта (sendContact): phone_number, first_name и необязательный last_name. Возвращает отправленный Message.

await bot.send_contact(
    chat_id: Union[int, str],
    phone_number: str,
    first_name: str,
    *,
    last_name: Optional[str] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

Отправляет анимированный эмодзи со случайным значением (sendDice): кубик, дартс, баскетбол, футбол, боулинг или слот-машина. Результат — в dice.value возвращённого Message.

await bot.send_dice(
    chat_id: Union[int, str],
    *,
    emoji: Optional[str] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸Значения: 1–6 для 🎲 🎯 🎳, 1–5 для 🏀 ⚽, 1–64 для 🎰; эмодзи по умолчанию — 🎲.

Отправляет точку на карте (sendLocation). С live_period это живая геолокация, которую можно обновлять.

await bot.send_location(
    chat_id: Union[int, str],
    latitude: float,
    longitude: float,
    *,
    live_period: Optional[int] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸live_period — 60–86400 секунд или 0x7FFFFFFF для живой геолокации без ограничения по времени.
• ▸Обновление живой геолокации: call("editMessageLiveLocation", ...).

Отправляет текстовое сообщение пользователю, в группу или канал (sendMessage) и возвращает dict отправленного Message. chat_id — числовой ID или @username публичного канала/супергруппы.

await bot.send_message(
    chat_id: Union[int, str],
    text: str,
    *,
    parse_mode: Optional[str] = None,
    entities: Optional[list] = None,
    link_preview_options: Optional[dict] = None,
    disable_notification: Optional[bool] = None,
    protect_content: Optional[bool] = None,
    message_thread_id: Optional[int] = None,
    reply_parameters: Optional[dict] = None,
    reply_markup: Optional[dict] = None,
    business_connection_id: Optional[str] = None,
    message_effect_id: Optional[str] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸Текст — 1–4096 символов после разбора entities; parse_mode: HTML, MarkdownV2 или устаревший Markdown.
• ▸При преобразовании группы в супергруппу ID меняется: запрос со старым ID вызывает ApiError, новый ID лежит в exc.payload["parameters"]["migrate_to_chat_id"].
• ▸message_thread_id — тема форума; параметры, которых нет в сигнатуре (например, allow_paid_broadcast), передаются через **extra.

await bot.send_message("@mening_kanalim", "Salom!", parse_mode="HTML")

Отправляет опрос (sendPoll) — обычный или викторину с type="quiz". Возвращает Message с объектом poll.

await bot.send_poll(
    chat_id: Union[int, str],
    question: str,
    options: list,
    *,
    is_anonymous: Optional[bool] = None,
    allows_multiple_answers: Optional[bool] = None,
    type: Optional[str] = None,
    correct_option_id: Optional[int] = None,
    token: Optional[str] = None,
    correct_option_ids: Optional[Sequence[int]] = None,
    **extra: Any,
) -> dict

• ▸Вопрос — 1–300 символов; options — 1–12 вариантов, официальный формат InputPollOption: [{"text": "Да"}, {"text": "Нет"}].
• ▸С Bot API 9.6 викторина принимает correct_option_ids (список) вместо correct_option_id — передавайте через **extra: correct_option_ids=[0].
• ▸Опросы по умолчанию анонимные (is_anonymous — true).

Отправляет место (sendVenue) — точку на карте с названием (title) и адресом (address). Возвращает отправленный Message.

await bot.send_venue(
    chat_id: Union[int, str],
    latitude: float,
    longitude: float,
    title: str,
    address: str,
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

Ставит реакцию бота на сообщение (setMessageReaction), например reaction=[{"type": "emoji", "emoji": "👍"}]; is_big=True — с большой анимацией.

await bot.set_reaction(
    chat_id: Union[int, str],
    message_id: int,
    *,
    reaction: Optional[list] = None,
    is_big: Optional[bool] = None,
    token: Optional[str] = None,
) -> bool

• ▸Бот (как пользователь без Premium) может поставить не больше одной реакции на сообщение и не может использовать платные реакции.
• ▸Реакция custom emoji работает, только если она уже есть на сообщении или разрешена админами чата.

Закрывает опрос, отправленный ботом (stopPoll), и возвращает итоговый объект Poll с результатами.

await bot.stop_poll(
    chat_id: Union[int, str],
    message_id: int,
    *,
    reply_markup: Optional[dict] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

Помощник SDK: вызывает getFile, скачивает файл и возвращает содержимое как bytes. Удобно, чтобы сохранить фото или документ, присланные боту.

await bot.download(file_id: str, *, token: Optional[str] = None) -> bytes

• ▸Действует лимит облачного Bot API в 20 МБ; файл целиком читается в память.
• ▸При HTTP-ошибке выбрасывается ApiError, токен в url заменён на <token>.

Возвращает метаданные файла (getFile), включая file_path, нужный для скачивания. Чтобы получить байты за один шаг, удобнее download().

await bot.get_file(file_id: str, *, token: Optional[str] = None) -> dict

• ▸Ссылка для скачивания действует не менее 1 часа; когда истечёт, вызовите getFile снова.
• ▸Через облачный Bot API бот скачивает файлы до 20 МБ.
• ▸Исходное имя и MIME-тип могут не сохраниться — сохраняйте их из входящего сообщения.

Возвращает фото профиля пользователя (getUserProfilePhotos): total_count и photos (каждое фото в нескольких размерах). Для постраничной выборки — offset и limit (1–100, по умолчанию 100).

await bot.get_user_profile_photos(
    user_id: int,
    *,
    offset: Optional[int] = None,
    limit: Optional[int] = None,
    token: Optional[str] = None,
) -> dict

Отправляет GIF или видео H.264/MPEG-4 AVC без звука как анимацию (sendAnimation). До 50 МБ при загрузке.

await bot.send_animation(
    chat_id: Union[int, str],
    animation: Union[str, bytes, socialift.telegram.InputFile],
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

Отправляет музыкальный файл (sendAudio), который Telegram показывает в плеере. Формат .MP3 или .M4A, до 50 МБ при загрузке; для голосовых сообщений — send_voice.

await bot.send_audio(
    chat_id: Union[int, str],
    audio: Union[str, bytes, socialift.telegram.InputFile],
    *,
    caption: Optional[str] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

Отправляет любой файл как документ (sendDocument) и возвращает Message с объектом document. При загрузке — до 50 МБ.

await bot.send_document(
    chat_id: Union[int, str],
    document: Union[str, bytes, socialift.telegram.InputFile],
    *,
    caption: Optional[str] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸По ссылке гарантированно работают только файлы .PDF и .ZIP.
• ▸С «сырыми» bytes SDK использует имя параметра (document) как имя файла; чтобы задать нормальное имя, используйте InputFile(content=..., filename="report.pdf").

with open("hisobot.pdf", "rb") as f:
    await bot.send_document("@kanal", f.read(), caption="Hisobot")

Отправляет альбом из 2–10 фото, видео, документов или аудио (sendMediaGroup) и возвращает список Message. Для загрузки байтов укажите в элементе "media": "attach://имя" и передайте имя=InputFile(...) дополнительным аргументом.

await bot.send_media_group(
    chat_id: Union[int, str],
    media: list,
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> list

• ▸Документы и аудио группируются только с элементами своего типа.
• ▸Элемент — dict InputMedia*, например {"type": "photo", "media": "<file_id или URL>", "caption": "..."}.

Отправляет фото (sendPhoto): file_id, HTTP(S)-ссылка, bytes или InputFile — при передаче файла SDK сам переходит на multipart-загрузку. has_spoiler=True скрывает фото под спойлером.

await bot.send_photo(
    chat_id: Union[int, str],
    photo: Union[str, bytes, socialift.telegram.InputFile],
    *,
    caption: Optional[str] = None,
    parse_mode: Optional[str] = None,
    has_spoiler: Optional[bool] = None,
    reply_markup: Optional[dict] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸До 10 МБ при загрузке, до 5 МБ по ссылке; ширина + высота ≤ 10000, соотношение сторон ≤ 20.
• ▸Подпись (caption) — 0–1024 символа.
• ▸По file_id из ответа тот же файл можно отправить повторно без загрузки (он действует только для этого бота).

Отправляет стикер (sendSticker): статичный .WEBP, анимированный .TGS или видео .WEBM. Возвращает отправленный Message.

await bot.send_sticker(
    chat_id: Union[int, str],
    sticker: Union[str, bytes, socialift.telegram.InputFile],
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸По ссылке можно отправить только стикеры .WEBP.

Отправляет видео MPEG4 (sendVideo); другие форматы можно отправить документом. duration, width, height, supports_streaming и thumbnail необязательны.

await bot.send_video(
    chat_id: Union[int, str],
    video: Union[str, bytes, socialift.telegram.InputFile],
    *,
    caption: Optional[str] = None,
    duration: Optional[int] = None,
    width: Optional[int] = None,
    height: Optional[int] = None,
    supports_streaming: Optional[bool] = None,
    thumbnail: Union[str, bytes, socialift.telegram.InputFile, NoneType] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸До 50 МБ при загрузке, до 20 МБ по ссылке.
• ▸thumbnail — JPEG меньше 200 кБ, не больше 320×320; учитывается, только если само видео загружается файлом.

Отправляет видеосообщение-«кружок» (sendVideoNote) — квадратное видео MPEG4 длиной до 1 минуты.

await bot.send_video_note(
    chat_id: Union[int, str],
    video_note: Union[str, bytes, socialift.telegram.InputFile],
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸По ссылке отправить нельзя — передайте file_id или файл для загрузки (bytes/InputFile).

Отправляет воспроизводимое голосовое сообщение (sendVoice). Bot API принимает .OGG с OPUS, .MP3 или .M4A; другие форматы могут уйти как аудио или документ.

await bot.send_voice(
    chat_id: Union[int, str],
    voice: Union[str, bytes, socialift.telegram.InputFile],
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸До 50 МБ при загрузке; по ссылке файл должен быть audio/ogg и не больше 1 МБ (файлы 1–20 МБ уходят документом).

Удаляет одно сообщение, в том числе служебное (deleteMessage). При успехе возвращает True.

await bot.delete_message(
    chat_id: Union[int, str],
    message_id: int,
    *,
    token: Optional[str] = None,
) -> bool

• ▸Удалить можно только сообщение, отправленное меньше 48 часов назад.
• ▸В личном чате бот удаляет и свои, и входящие сообщения; в группе чужие — только будучи админом, в супергруппе и канале — с правом can_delete_messages.
• ▸Служебные сообщения о создании супергруппы, канала или темы форума не удаляются.

Удаляет 1–100 сообщений одним запросом (deleteMessages); ограничения те же, что у delete_message. Возвращает True.

await bot.delete_messages(
    chat_id: Union[int, str],
    message_ids: Iterable[int],
    *,
    token: Optional[str] = None,
) -> bool

• ▸Ненайденные сообщения пропускаются.

await bot.delete_messages("@kanal", [41, 42])

Меняет подпись (caption) медиа-сообщения (editMessageCaption). Сообщение указывается так же, как в edit_message_text.

await bot.edit_message_caption(
    *,
    caption: Optional[str] = None,
    chat_id: Union[int, str, NoneType] = None,
    message_id: Optional[int] = None,
    inline_message_id: Optional[str] = None,
    parse_mode: Optional[str] = None,
    reply_markup: Optional[dict] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> Any

• ▸Подпись — 0–1024 символа; возвращает Message или True для inline-сообщения.

Заменяет медиа в сообщении (анимация, аудио, документ, фото, видео) или превращает текстовое сообщение в медиа (editMessageMedia). media — dict InputMedia, например {"type": "photo", "media": "<file_id или URL>"}.

await bot.edit_message_media(
    media: dict,
    *,
    chat_id: Union[int, str, NoneType] = None,
    message_id: Optional[int] = None,
    inline_message_id: Optional[str] = None,
    reply_markup: Optional[dict] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> Any

• ▸В альбоме аудио меняется только на аудио, документ — на документ, фото/видео — на фото или видео.
• ▸Обёртка не принимает дополнительных аргументов, поэтому новый файл через attach:// загружается так: call("editMessageMedia", ..., media={"type": "photo", "media": "attach://p"}, p=InputFile(...)).
• ▸Для inline-сообщения новый файл загрузить нельзя — используйте file_id или URL.

Меняет только inline-клавиатуру (reply_markup), не трогая текст (editMessageReplyMarkup) — например, чтобы обновить кнопки после callback.

await bot.edit_message_reply_markup(
    *,
    reply_markup: Optional[dict] = None,
    chat_id: Union[int, str, NoneType] = None,
    message_id: Optional[int] = None,
    inline_message_id: Optional[str] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> Any

• ▸Возвращает Message или True для inline-сообщения.

Редактирует текст сообщения (editMessageText). Сообщение задаётся парой chat_id + message_id или inline_message_id, если оно отправлено в inline-режиме.

await bot.edit_message_text(
    text: str,
    *,
    chat_id: Union[int, str, NoneType] = None,
    message_id: Optional[int] = None,
    inline_message_id: Optional[str] = None,
    parse_mode: Optional[str] = None,
    reply_markup: Optional[dict] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> Any

• ▸Возвращает изменённый Message, а для inline-сообщения — True.
• ▸Business-сообщения, отправленные не ботом и без inline-клавиатуры, можно редактировать только в течение 48 часов.

await bot.edit_message_text("Yangi matn", chat_id="@kanal", message_id=42)

Закрепляет сообщение в чате (pinChatMessage); disable_notification=True — без уведомления участникам.

await bot.pin_message(
    chat_id: Union[int, str],
    message_id: int,
    *,
    disable_notification: Optional[bool] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> bool

• ▸В группе бот должен быть админом с правом can_pin_messages, в канале — can_edit_messages; в личном чате права не нужны.

await bot.pin_message("@kanal", 42, disable_notification=True)

Открепляет все закреплённые сообщения в чате (unpinAllChatMessages).

await bot.unpin_all_messages(
    chat_id: Union[int, str],
    *,
    token: Optional[str] = None,
) -> bool

• ▸Нужно право can_pin_messages в группе или can_edit_messages в канале; в личном чате — не нужно.

Открепляет сообщение (unpinChatMessage). Без message_id открепляется последнее закреплённое сообщение (по дате отправки).

await bot.unpin_message(
    chat_id: Union[int, str],
    *,
    message_id: Optional[int] = None,
    token: Optional[str] = None,
    **extra: Any,
) -> bool

• ▸Права как у pin_message: в группе can_pin_messages, в канале can_edit_messages.

await bot.unpin_message("@kanal", message_id=42)

Банит пользователя (banChatMember): в супергруппе и канале он не сможет вернуться даже по ссылке, пока бан не снят. revoke_messages=True удаляет его сообщения в группе (в супергруппах и каналах — всегда).

await bot.ban_member(
    chat_id: Union[int, str],
    user_id: int,
    *,
    until_date: Optional[int] = None,
    revoke_messages: Optional[bool] = None,
    token: Optional[str] = None,
) -> bool

• ▸until_date — unix-время; меньше 30 секунд или больше 366 дней от текущего момента — бан навсегда (только для супергрупп и каналов).
• ▸Чтобы просто выгнать (с возможностью вернуться): ban_member, затем unban_member.
• ▸Бот должен быть админом с соответствующими правами.

await bot.ban_member("@guruh", 123456789)
await bot.unban_member("@guruh", 123456789)

Удаляет фото чата (deleteChatPhoto). В личных чатах не работает; бот должен быть админом с соответствующими правами.

await bot.delete_chat_photo(
    chat_id: Union[int, str],
    *,
    token: Optional[str] = None,
) -> bool

Помощник SDK: вызывает promoteChatMember со всеми правами администратора в False и снимает пользователя с админки.

await bot.demote_member(
    chat_id: Union[int, str],
    user_id: int,
    *,
    token: Optional[str] = None,
) -> bool

• ▸Боту нужно право can_promote_members, и снять он может только админов, назначенных им самим (прямо или косвенно).

Возвращает актуальную полную информацию о чате (getChat, ChatFullInfo): тип, название, описание, закреплённое сообщение, права и другое. Также удобный способ узнать числовой id по @username.

await bot.get_chat(chat_id: Union[int, str], *, token: Optional[str] = None) -> dict

chat = await bot.get_chat("@kanal")

Возвращает список администраторов чата как dict ChatMember (getChatAdministrators): статус, права, custom_title.

await bot.get_chat_administrators(
    chat_id: Union[int, str],
    *,
    token: Optional[str] = None,
    return_bots: Optional[bool] = None,
    **extra: Any,
) -> list

• ▸Другие боты по умолчанию не попадают в список; чтобы их получить — call("getChatAdministrators", chat_id=..., return_bots=True), у обёртки нет дополнительных аргументов.
• ▸В Bot API нет метода для списка всех участников; для этого есть клиент аккаунта TelegramAccount.participants.

admins = await bot.get_chat_administrators("@guruh")

Возвращает статус одного участника (getChatMember): creator, administrator, member, restricted, left или kicked, вместе с правами. Часто используется для проверки подписки на канал.

await bot.get_chat_member(
    chat_id: Union[int, str],
    user_id: int,
    *,
    token: Optional[str] = None,
) -> dict

• ▸Для других пользователей работа гарантирована, только если бот — админ этого чата.

member = await bot.get_chat_member("@guruh", 123456789)

Возвращает число участников чата целым числом (getChatMemberCount).

await bot.get_chat_member_count(
    chat_id: Union[int, str],
    *,
    token: Optional[str] = None,
) -> int

Бот покидает группу, супергруппу или канал (leaveChat).

await bot.leave_chat(chat_id: Union[int, str], *, token: Optional[str] = None) -> bool

Назначает пользователя админом или меняет его права (promoteChatMember); права передаются keyword-аргументами: can_delete_messages=True, can_restrict_members=True и т. д.

await bot.promote_member(
    chat_id: Union[int, str],
    user_id: int,
    *,
    token: Optional[str] = None,
    **rights: Any,
) -> bool

• ▸Работает в супергруппах и каналах; бот должен быть админом с нужными правами и может выдать только подмножество своих (can_promote_members).
• ▸False для всех прав — снятие с админки; это делает demote_member.

Ограничивает участника супергруппы через dict permissions (restrictChatMember) — например, {"can_send_messages": False}, чтобы запретить писать. Чтобы снять ограничения, передайте True для всех прав.

await bot.restrict_member(
    chat_id: Union[int, str],
    user_id: int,
    permissions: dict,
    *,
    until_date: Optional[int] = None,
    use_independent_chat_permissions: Optional[bool] = None,
    token: Optional[str] = None,
) -> bool

• ▸until_date: меньше 30 секунд или больше 366 дней от текущего момента — ограничение навсегда.
• ▸Бот должен быть админом с соответствующими правами.

Задаёт кастомный титул администратору супергруппы, назначенному ботом (setChatAdministratorCustomTitle).

await bot.set_admin_title(
    chat_id: Union[int, str],
    user_id: int,
    custom_title: str,
    *,
    token: Optional[str] = None,
) -> bool

• ▸0–16 символов, эмодзи нельзя.

Меняет описание группы, супергруппы или канала (setChatDescription), 0–255 символов.

await bot.set_chat_description(
    chat_id: Union[int, str],
    description: str,
    *,
    token: Optional[str] = None,
) -> bool

• ▸Бот должен быть админом с соответствующими правами.

await bot.set_chat_title("@kanal", "Yangi nom")
await bot.set_chat_description("@kanal", "Tavsif")

Задаёт права по умолчанию для всех обычных участников группы или супергруппы (setChatPermissions), например {"can_send_messages": False} — чат только для чтения.

await bot.set_chat_permissions(
    chat_id: Union[int, str],
    permissions: dict,
    *,
    use_independent_chat_permissions: Optional[bool] = None,
    token: Optional[str] = None,
) -> bool

• ▸Бот должен быть админом с правом can_restrict_members.
• ▸Без use_independent_chat_permissions=True права can_send_other_messages и can_add_web_page_previews включают медиа-права, а can_send_polls — can_send_messages.

Устанавливает новое фото чата (setChatPhoto). Принимается только загружаемый файл (bytes или InputFile), не file_id и не URL.

await bot.set_chat_photo(
    chat_id: Union[int, str],
    photo: Union[bytes, socialift.telegram.InputFile],
    *,
    token: Optional[str] = None,
) -> bool

• ▸В личных чатах не работает; бот должен быть админом с соответствующими правами.

Меняет название чата (setChatTitle), 1–128 символов. В личных чатах не работает.

await bot.set_chat_title(
    chat_id: Union[int, str],
    title: str,
    *,
    token: Optional[str] = None,
) -> bool

• ▸Бот должен быть админом с соответствующими правами.

await bot.set_chat_title("@kanal", "Yangi nom")
await bot.set_chat_description("@kanal", "Tavsif")

Снимает бан в супергруппе или канале (unbanChatMember); пользователь не возвращается автоматически, но может вступить по ссылке.

await bot.unban_member(
    chat_id: Union[int, str],
    user_id: int,
    *,
    only_if_banned: bool = True,
    token: Optional[str] = None,
) -> bool

• ▸В SDK по умолчанию only_if_banned=True (в Bot API — false): действующий участник без бана не будет удалён по ошибке.
• ▸С only_if_banned=False Telegram удаляет пользователя, если он ещё в чате, — после вызова он не участник, но может вступить.

await bot.ban_member("@guruh", 123456789)
await bot.unban_member("@guruh", 123456789)

Одобряет заявку на вступление (approveChatJoinRequest) — например, в ответ на обновление chat_join_request после ссылки с creates_join_request=True.

await bot.approve_join_request(
    chat_id: Union[int, str],
    user_id: int,
    *,
    token: Optional[str] = None,
) -> bool

• ▸Бот должен быть админом с правом can_invite_users; без него не приходят и обновления chat_join_request.

Создаёт дополнительную пригласительную ссылку (createChatInviteLink) с name, expire_date, member_limit или creates_join_request и возвращает dict ChatInviteLink. Например, отдельная ссылка на каждую рекламную кампанию.

await bot.create_invite_link(
    chat_id: Union[int, str],
    *,
    name: Optional[str] = None,
    expire_date: Optional[int] = None,
    member_limit: Optional[int] = None,
    creates_join_request: Optional[bool] = None,
    token: Optional[str] = None,
) -> dict

• ▸name — 0–32 символа, member_limit — 1–99999; вместе с creates_join_request=True member_limit указать нельзя.
• ▸Бот должен быть админом с соответствующими правами.

link = await bot.create_invite_link("@guruh", name="Reklama", member_limit=100)

Отклоняет заявку на вступление (declineChatJoinRequest).

await bot.decline_join_request(
    chat_id: Union[int, str],
    user_id: int,
    *,
    token: Optional[str] = None,
) -> bool

• ▸Бот должен быть админом с правом can_invite_users.

Редактирует неосновную ссылку, созданную ботом (editChatInviteLink): name, expire_date, member_limit, creates_join_request передаются keyword-аргументами. Возвращает обновлённый ChatInviteLink.

await bot.edit_invite_link(
    chat_id: Union[int, str],
    invite_link: str,
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

Создаёт новую основную пригласительную ссылку и возвращает её строкой (exportChatInviteLink). Прежняя основная ссылка отзывается.

await bot.export_invite_link(
    chat_id: Union[int, str],
    *,
    token: Optional[str] = None,
) -> str

• ▸Бот не может использовать ссылки, созданные другими админами. Для дополнительной ссылки, не ломающей существующие, — create_invite_link.
• ▸Бот должен быть админом с соответствующими правами.

Отзывает пригласительную ссылку, созданную ботом, и возвращает её (revokeChatInviteLink). Если отозвана основная ссылка, Telegram автоматически создаёт новую.

await bot.revoke_invite_link(
    chat_id: Union[int, str],
    invite_link: str,
    *,
    token: Optional[str] = None,
) -> dict

Создаёт тему в форум-супергруппе или в личном чате с пользователем (createForumTopic) и возвращает dict ForumTopic с message_thread_id. icon_color и icon_custom_emoji_id — через **extra.

await bot.create_forum_topic(
    chat_id: Union[int, str],
    name: str,
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> dict

• ▸Название — 1–128 символов.
• ▸В супергруппе бот должен быть админом с правом can_manage_topics.
• ▸Писать в тему: send_message(..., message_thread_id=...).

Удаляет тему форума вместе со всеми её сообщениями (deleteForumTopic).

await bot.delete_forum_topic(
    chat_id: Union[int, str],
    message_thread_id: int,
    *,
    token: Optional[str] = None,
) -> bool

• ▸В супергруппе бот должен быть админом с правом can_delete_messages.

Меняет название (name) или иконку (icon_custom_emoji_id) темы (editForumTopic); непереданные поля не меняются.

await bot.edit_forum_topic(
    chat_id: Union[int, str],
    message_thread_id: int,
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> bool

• ▸В супергруппе нужно право can_manage_topics, если тему создал не сам бот.

Отвечает на нажатие inline-кнопки (answerCallbackQuery): необязательное уведомление (text) или окно (show_alert=True). Вызывайте для каждого callback_query, даже без текста.

await bot.answer_callback_query(
    callback_query_id: str,
    *,
    text: Optional[str] = None,
    show_alert: Optional[bool] = None,
    url: Optional[str] = None,
    cache_time: Optional[int] = None,
    token: Optional[str] = None,
) -> bool

• ▸Пока ответа нет, клиенты Telegram показывают на кнопке индикатор загрузки.
• ▸text — 0–200 символов; cache_time (секунды) по умолчанию 0.

Отправляет результаты inline-запроса (answerInlineQuery), когда пользователь пишет @имя_бота запрос в любом чате. results — список dict InlineQueryResult; cache_time, is_personal, next_offset — через **extra.

await bot.answer_inline_query(
    inline_query_id: str,
    results: list,
    *,
    token: Optional[str] = None,
    **extra: Any,
) -> bool

• ▸Не более 50 результатов на запрос; cache_time на сервере по умолчанию 300 секунд.
• ▸Inline-режим включается в @BotFather командой /setinline.

Вызывает любой метод Bot API по имени и возвращает result — для методов без отдельной обёртки, например await bot.call("getChatMenuButton", chat_id=...). Аргументы со значением None отбрасываются, при bytes/InputFile запрос автоматически становится multipart.

await bot.call(method: str, *, token: Optional[str] = None, **params: Any) -> Any

• ▸Ошибки: 401 → AuthError, 403 → PermissionError, 404 или "not found" в описании → NotFoundError, 429 → RateLimitError; остальные — ApiError, сырой ответ в exc.payload.
• ▸В ApiError.url токен заменён на <token>.
• ▸Необёрнутые методы доступны и как атрибуты: bot.get_chat_menu_button(chat_id=1) → getChatMenuButton (только keyword-аргументы).

commands = await bot.call("getMyCommands")

Отправляет произвольный HTTP-запрос и возвращает JSON-ответ — для эндпоинта, у которого в SDK пока нет отдельного метода. Токен и параметры подписи (access_token, для Meta — appsecret_proof через socialift.crypto.appsecret_proof) вы передаёте сами в params или headers.

await bot.request(
    method: str,
    url: str,
    *,
    params: Optional[Mapping[str, Any]] = None,
    data: Optional[Any] = None,
    json: Optional[Any] = None,
    headers: Optional[Mapping[str, str]] = None,
) -> Any

• ▸Значения None в params не отправляются.
• ▸При лимите (RateLimitError) и временных ошибках сервера (HTTP 429, 500, 502, 503, 504) запрос повторяется по RetryPolicy; если есть заголовок Retry-After, SDK ждёт указанное время. Обрыв сети выбрасывается как TransportError.

Короткая форма request("GET", ...).

await bot.get(url: str, **kw) -> Any

Короткая форма request("POST", ...).

await bot.post(url: str, **kw) -> Any

Короткая форма request("DELETE", ...).

await bot.delete(url: str, **kw) -> Any

Проходит по курсорной пагинации Meta (paging.next) и возвращает все элементы data одним списком.

await bot.paginate(
    url: str,
    *,
    params: Optional[Mapping[str, Any]] = None,
    max_items: int = 500,
    page_size: int = 100,
) -> list[dict]

• ▸max_items (по умолчанию 500) — защитный предел: у крупного аккаунта могут быть десятки тысяч записей. page_size — limit одного запроса.

Закрывает HTTP-сессию, созданную самим SDK (переданную извне сессию не трогает). При использовании async with Client(...) вызывается автоматически.

await bot.close() -> None