Find chats
find_chatsRead-onlyIdempotent
Search Telegram for users, groups, or channels by name, username, or phone number. Apply filters like date range, chat type, or folder to narrow results.
Instructions
Find users/groups/channels by name, username, or phone. Global search (query required) searches all Telegram; with min_date, max_date, or filter, search uses dialog list or a named filter; include_peers filters use last-activity from GetPeerDialogs; flag-based filters use dialog list dates. Success: dict with key chats (list of chat objects). Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Name, username (no @), phone (+country…), or comma-separated multi-queries. Required for global search unless you use min_date/max_date or folder alone. | |
| limit | No | Maximum chats to return (recommended 50 or less). | |
| chat_type | No | Comma-separated chat kinds: private, bot, group, channel. Case-insensitive; extra spaces allowed. | |
| public | No | If true, prefer chats with a public username; if false, without. Does not apply to private DMs. Omit to skip this filter. | |
| min_date | No | Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound. | |
| max_date | No | Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound. | |
| folder | No | Telegram folder name (case-insensitive exact match after normalization). In Telegram's UI these are called folders; internally they are "dialog filters" — saved filter presets that group chats by custom criteria (pinned, unread, business, etc.). See Filters-vs-Folders.md for the technical distinction. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | No | ||
| error | No | ||
| operation | No | ||
| code | No | ||
| params | No | ||
| exception | No | ||
| action | No | ||
| error_code | No | ||
| chats | No |