Информация о текущем авторизованном пользователе.

Изменить отображаемое имя/фамилию/био собственного профиля.

None в поле = не менять. Пустая строка = очистить.

Установить online/offline статус.

Args: offline: True — пометить аккаунт как offline (не показывать "online" зелёный кружок).

Сменить @username аккаунта (пустая строка — снять username).

Расширенная инфа о пользователе (bio, общие чаты, premium, etc).

Args: user: id/@username; None = я сам.

Список активных сессий аккаунта (другие устройства/клиенты).

Полезно для аудита: "кто сейчас залогинен в мой аккаунт".

Завершить чужую активную сессию по hash из get_authorizations.

Свою (current=true) сессию через этот метод завершить нельзя.

Получить текущие privacy-настройки для указанного ключа.

Args: key: один из last_seen, profile_photo, phone_call, phone_p2p, phone_number, added_by_phone, forwards, chat_invite, voice_messages, about, birthday.

Установить privacy для указанного ключа.

Args: key: см. get_privacy. value: 'everyone', 'contacts', 'close_friends', 'nobody', 'nobody_contacts'.

Информация о настроенном 2FA-пароле (включён ли, hint, recovery email).

НЕ возвращает сам пароль — только метаданные.

Шаг 1: запросить SMS-код у Telegram. Очищает предыдущий auth-state.

Возвращает: ok: True если код отправлен code_sent: True phone: куда отправлен (масковано последние 4 цифры) already_authorized: True если сессия уже валидна (код не нужен)

Шаг 2: отправить код (и опц. пароль 2FA).

Args: code: 5-значный SMS-код из Telegram. password_2fa: пароль cloud-2FA если включён. Если опущен и 2FA требуется — вернётся ошибка с просьбой повторить.

Отменить незавершённый auth-flow (если запросил код, но не ввёл).

Подробная инфа о любом entity: пользователе/чате/канале/боте.

Найти entity по @username и вернуть инфу + id.

Глобальный поиск по юзерам/чатам/каналам по имени или @username.

Топ часто-используемых контактов в указанной категории.

Args: category: 'correspondents' (личные чаты), 'bots_pm', 'bots_inline', 'phone_calls', 'forward_users', 'forward_chats', 'groups', 'channels', 'bots_app'.

Получить InputPeer для чата (нужен для raw API вызовов).

Возвращает dict с _, который можно положить в kwargs_json для invoke_raw.

Список фото профиля юзера/группы/канала (метаданные, без скачивания).

Args: offset: пропустить N фото с начала. max_id: вернуть фото старше указанного id.

Скачать аватарку юзера/чата на диск или inline (base64 в ответе).

Args: download_big: True — большая (640x640); False — маленькая (160x160). inline: True — вернуть фото как ImageContent inline (≤ 1 MB), False — записать в файл и вернуть путь.

Общие чаты с указанным юзером.

Список всех контактов аккаунта.

Добавить пользователя в контакты.

Args: user: id или @username существующего юзера. phone: опционально (можно пустое). add_phone_privacy_exception: разрешить юзеру видеть твой номер.

Удалить пользователя из контактов.

Массовый импорт контактов по номерам телефона (без знания Telegram-ID).

Args: contacts: список dict'ов с ключами phone, first_name, last_name.

Заблокировать пользователя — он не сможет писать.

Args: my_stories_from: True — добавить только в story-blocklist.

Разблокировать пользователя.

Список заблокированных юзеров.

Args: my_stories_from: True — story-blocklist; False — основной.

Отправить текстовое сообщение.

Args: chat: id или @username получателя. text: текст сообщения. reply_to: id сообщения, на которое отвечаем. silent: без звука уведомления. parse_mode: 'markdown', 'html' или 'none' для plain-text. link_preview: показывать превью первой ссылки. schedule_unix: если задан — отправить отложенно на UNIX-таймстамп (UTC). comment_to: id поста в канале — отправить как комментарий (требует у канала включённой обсуждаемой группы). clear_draft: очистить draft чата после отправки.

Отредактировать своё сообщение.

Удалить сообщения. По умолчанию — только у себя.

Args: revoke: True — у всех (необратимо). При revoke=True вызывает elicit для подтверждения и параллельно срабатывает PreToolUse hook.

Переслать сообщения из одного чата в другой.

Сообщения чата (новые → старые по умолчанию).

Args: limit: 1-200. offset_id: вернуть старше указанного id (пагинация). min_id / max_id: границы id. from_user: id/@username — фильтровать по отправителю. reverse: True — от старых к новым. ids: получить конкретные сообщения по id (без пагинации). reply_to: показать сообщения треда/комментариев под этим id. filter_type: media-фильтр: photo, video, document, voice, music, gif, url, chat_photo, phone_call, roundvideo, mymentions. scheduled: показать запланированные (а не уже отправленные) сообщения.

Гибрид: компактные text-блоки + ResourceLink на каждое сообщение.

Клиент видит дешёвый список и может догрузить полное сообщение через telegram://msg/{chat_id}/{message_id} ресурс.

Поиск сообщений по тексту глобально или в чате.

Закрепить сообщение в чате.

Args: notify: True — отправить уведомление участникам о новом pin. pm_oneside: только в PM — закрепить только у себя, не у собеседника.

Открепить одно сообщение или все pinned в чате.

Args: message_id: если задан — открепить конкретное; None — открепить все.

Поставить реакцию-эмодзи на сообщение.

Args: emoji: 1 эмодзи (👍, ❤️, 🔥). Пустая строка — снять все реакции. big: показать с анимацией "большой реакции". add_to_recent: добавить эмодзи в "недавно использованные".

Сохранить серверный draft в чате (синхронизируется на все устройства).

Args: text: текст; пустая строка очищает draft. parse_mode: подсказка клиенту, как парсить при отправке (фактическое форматирование происходит в момент отправки сообщения).

Очистить draft в чате (синхронизация на все устройства).

Список отложенных сообщений в чате (которые ещё не отправлены).

Принудительно отправить отложенные сообщения сейчас.

Удалить отложенные сообщения (до их отправки).

Послать сигнал активности в чат (печатает / записывает / отправляет).

Args: chat: id или @username чата. action: тип активности — typing для текста, record-audio перед голосовым, cancel чтобы снять текущий статус и т.д. delay_seconds: на сколько секунд держать статус (0 — мгновенный сигнал).

Список всех диалогов (юзеры/боты/группы/каналы — без фильтра).

Args: compact: True — облегчённая форма (id/name/type/is_pinned/unread/...) ~85% меньше payload.

Для типизированных списков см. list_channels, list_groups, list_bots.

Только broadcast-каналы (без supergroup'ов).

Args: archived: 'main' — основной список, 'archive' — только архив, 'both' — всё. Default 'both' — включает архивные. limit: верхняя граница по сырому фетчу диалогов до фильтрации. only_unread: True — только с unread_count > 0. is_pinned: 'any' / 'pinned' / 'unpinned'. min_participants / max_participants: фильтр по подписчикам. compact: default True — payload в ~5x меньше.

Группы и супергруппы.

Args: include_supergroups: False — только old-style basic groups. is_pinned/min_participants/max_participants/compact — см. list_channels.

PM-боты в диалогах.

Личные чаты с юзерами (без ботов).

Счётчики диалогов по типам — без payload, 1 запрос.

Возвращает: total / pm_users / bots / channels / supergroups / basic_groups / archived / pinned / unread.

Получить informация о N конкретных диалогах одним вызовом.

Полезно для batch-проверки is_pinned/unread перед массовой операцией.

Список несохранённых черновиков по всем чатам.

Переместить диалог в архив (folder=1).

Вернуть диалог из архива в основной список (folder=0).

Закрепить/открепить диалог в шапке списка.

Список кастомных папок диалогов (Folders в UI Telegram).

Создать/обновить кастомную папку диалогов.

Args: filter_id: уникальный id папки (2-255). 1 — резерв All. title: название (отображается в табе). emoticon: эмодзи иконки. included_chats: список id/@username включённых чатов. contacts/non_contacts/groups/broadcasts/bots: автоматически включать чаты этой категории. exclude_muted/read/archived: исключать соответствующие.

Удалить кастомную папку диалогов.

Пометить сообщения чата прочитанными.

Args: max_id: до какого id (0 — все). clear_mentions: ещё и сбросить @упоминания.

Замьютить уведомления чата.

Args: mute_until_unix: до какого UNIX timestamp (UTC). None = навсегда (2^31). show_previews: показывать текст превью в notification. silent: без звука уведомлений. stories_muted: True — также замьютить stories этого источника.

Снять mute с чата (вернуть дефолтные настройки).

Покинуть чат/канал или удалить личный диалог.

Args: revoke: True — удалить переписку и у собеседника (только PM).

Удалить N диалогов одним MCP-вызовом.

Для supergroups = leave + delete dialog. Для PM = clear history (revoke=False) или revoke=True (PM only — у собеседника тоже).

Args: chat_ids: список int/str id диалогов. revoke: только для PM — удалить и у собеседника. auto_floodwait_retry: при FloodWait sleep'ить и продолжать. max_total_wait_seconds: верхний предел total sleep.

Выйти из N каналов/супергрупп одним вызовом.

Перенести N диалогов в архив.

Создать обычную группу с указанными участниками.

Создать канал (broadcast=True) или супергруппу (megagroup=True).

Args: broadcast: True — broadcast-канал (только админы пишут). megagroup: True — супергруппа.

Переименовать чат/канал.

Установить описание чата (about/bio).

Установить аватарку чата/канала из файла.

Включить/выключить forum-режим (темы) в супергруппе.

Требует ≥200 участников. После включения супергруппа становится "форумом".

Список участников группы/канала.

Args: limit: 1-200. filter_admin/kicked/banned/bots/recent: показать только эту категорию. aggressive: для каналов с >200 участников — итерировать через индексные search-страницы (медленнее, но даёт больше).

Кикнуть участника из чата (он сможет вернуться).

Забанить участника навсегда — он не сможет вернуться.

Снять бан с участника.

Ограничить права участника супергруппы (read-only mute и т.п.).

В ChatBannedRights каждый bool=True означает ЗАПРЕТ соответствующего действия. send_*=False → разрешено отправлять (стандартный участник). send_*=True → запрещено (mute).

Args: until_unix: до какого UNIX timestamp; None = навсегда.

Назначить участника администратором с заданными правами.

Снять права админа (все флаги в False).

Войти в публичный канал/группу (по @username или ссылке-приглашению).

Выйти из канала/супергруппы.

Создать invite-ссылку на чат/канал.

Args: expire_unix: до когда действует. None = бессрочно. usage_limit: на сколько использований. request_needed: True — кандидаты ждут approval. title: метка ссылки (для аудита в админке).

Журнал действий админов в супергруппе/канале.

Статистика канала/супергруппы (только если ты админ).

Отправить файл. Telethon сам определит тип (фото/видео/документ).

Args: file_path: путь к локальному файлу. caption: подпись (поддерживает форматирование, см. parse_mode). parse_mode: 'markdown', 'html' или 'none'. force_document: True — отправить как документ, не сжимать. voice_note: True — отправить голосовое (требует .ogg/.mp3). video_note: True — отправить video-кружок. ttl_seconds: self-destruct таймер (только для PM, 1-60 сек). clear_draft: очистить draft чата после отправки. supports_streaming: для видео — отметить как streamable. custom_filename: заменить имя файла при отправке.

Отправить альбом из 2-10 фото/видео одной группой.

Caption ставится только на первое медиа альбома.

Скачать медиа из сообщения.

Args: download_dir: куда писать (если roots заявлены — путь валидируется). thumb_index: если задан — скачать только превью указанного индекса. inline: True — вернуть Image/Audio inline (≤1 MB) вместо файла.

Метаданные медиа в сообщении (тип, размер, mime, dimensions, duration).

Отправить геолокацию.

Args: live_period: если задан (60-86400) — отправить как live-локацию.

Отправить визитку контакта.

Отправить интерактивный «кубик».

Args: emoji: 🎲 (кубик), 🎯 (дартс), 🏀 (баскетбол), ⚽ (футбол), 🎰 (слот), 🎳 (боулинг). Telegram пришлёт случайный результат.

Отправить голосовое сообщение (.ogg/.mp3 → opus voice note).

Отправить video-кружок (.mp4 → круглое видео ≤60s, диаметр 384px).

Транскрибировать голосовое в текст (Telegram Premium фича).

Возвращает текст или partial-транскрипцию + флаг pending.

Список установленных стикерсетов.

Получить стикерсет по short_name (например 'AnimatedEmojies').

Возвращает метаданные сета + список первых 10 стикеров (id + emoji).

Установить стикерсет аккаунту.

Args: archived: True — добавить в архивированные (не показывать активно).

Удалить стикерсет из аккаунта.

Поиск стикерсетов по имени (Telegram-каталог).

Args: exclude_featured: исключить из выдачи featured-наборы.

Отправить стикер по document_id (получи через get_sticker_set).

Args: document_id: id стикер-документа. access_hash: access_hash набора (поле set.access_hash). sticker_set_short_name: short_name набора-источника.

Создать и отправить опрос.

Args: options: 2-10 вариантов ответа. anonymous: голоса без видимости кто как голосовал. multiple_choice: можно выбрать несколько вариантов. quiz: режим викторины (один правильный ответ + объяснение). correct_option_index: индекс правильного варианта (для quiz=True). explanation: пояснение, показываемое после голосования (quiz). close_period_seconds: автозакрытие через N секунд (5-600 на момент API layer 215). close_unix: автозакрытие на UNIX-таймстамп. revoting_disabled: True — нельзя сменить голос (для викторин). shuffle_answers: True — порядок вариантов рандомизируется на каждом устройстве.