Find Telegram chats and unread conversations
telegram_list_chatsFind known Telegram chats by name or resolve an exact @username, and browse main or archive lists with unread-only filters—without joining chats or marking them read.
Instructions
Find known chats by name, or resolve an exact @username; never join a chat.
Empty query lists main/archive. unread_only includes unread messages, mentions and manual unread marks. Does not mark chats read. Pages use a 10-minute snapshot of at most 500 chat IDs; coverage_limited reports a capped listing. A name query searches known chats across lists. Follow next_cursor even after an empty page.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "telegram_list_chats"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum items returned in this page, from 1 to 20. A shorter page can still have next_cursor. | |
| query | No | Chat-name query across known chats, or an exact @username to resolve. An empty string lists the selected chat_list; no chat is joined. | |
| cursor | No | Opaque next_cursor from this tool's previous page. Omit for the first page; keep the same chat, query and filters when continuing. Never construct or modify it. Follow a returned cursor even after a short or empty page. | |
| chat_list | No | List to browse when query is empty: main or archive. A nonempty name query searches known chats across lists. | main |
| unread_only | No | Include only chats with unread messages, unread mentions or a manual unread mark; does not mark them read. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | ||
| scope | Yes | ||
| next_cursor | Yes | ||
| trust_boundary | No | ||
| coverage_limited | Yes |