Return the logged-in Telegram account (id, username, first_name, phone).

Doubles as a session check — errors if no valid session exists.

List chats (groups, channels, direct messages).

Args: query: Optional case-insensitive substring filter on the chat title. When set, ALL dialogs are scanned so a match beyond the most-recent limit chats is still found (comparatively expensive, like title resolution); limit then caps the number of matches returned. limit: Max results (default 50, capped at 500). Without query this is also how many dialogs are fetched.

Returns objects with id, title, type ('group'/'channel'/'user'), unread. Use this to find a chat's id/title before calling other tools.

Read recent messages from one chat.

Args: chat: Chat id, @username, or exact/substring title. limit: Max messages (default 30, capped at 200). before_id: Only messages older than this message id (pagination). search: Optional full-text filter within the chat.

Returns message dicts (id, chat_id, date, sender_id, text, has_media, media_type).

Search messages by text — globally or within one chat.

Args: query: Non-empty search string. chat: Optional chat id/@username/title to scope the search. limit: Max results (default 30, capped at 200).

Returns message dicts (id, chat_id, date, sender_id, text, has_media, media_type).

Download media from specific messages to disk.

Args: chat: Chat id/@username/title. message_ids: Message ids whose media should be downloaded. dest_dir: Target directory (default TELEGRAM_DOWNLOAD_DIR).

Returns [{message_id, path}] for messages whose media downloaded successfully; non-media and undownloadable media are skipped. Paths are absolute.

Download the most recent media items from a chat.

Args: chat: Chat id/@username/title. limit: How many recent messages to scan (default 20, capped at 200). kind: Optional filter — 'photo' / 'video' / 'document' / 'other'. dest_dir: Target directory (default TELEGRAM_DOWNLOAD_DIR).

Returns [{message_id, kind, path}] for successfully downloaded media. This is the fast path for pulling images out of a group (e.g. the Arcanara Juni-Treffen photos). Paths are absolute.

Send a text message to a chat as the logged-in user.

This is a real, irreversible send, visible to the chat's members, and cannot be recalled via this API — confirm the chat and text before calling.

Args: chat: Chat id/@username/title. text: Non-empty message text.

Returns {"sent": True, "message_id": }.

Send a local file (image/document) to a chat as the logged-in user.

This is a real, irreversible send, visible to the chat's members, and cannot be recalled via this API — confirm the chat and file before calling.

Args: chat: Chat id/@username/title. file_path: Absolute path to an existing local file. caption: Optional caption text.

Returns {"sent": True, "message_id": }.