Search one Telegram chat with filters
telegram_search_chat_messagesSearch messages in a specific Telegram chat by text, sender, media type, date range, or forum topic; use filters alone for attachment-only results and paginate with cursors.
Instructions
Search a known chat by text, sender, media type, dates, or forum topic.
Empty query allows attachment-only searches. sender_id is a positive user ID or negative chat ID. mention means unread mentions; voice includes video notes. Use timezone-qualified dates. Keep every filter unchanged when following cursor.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"chat_id": "<chat_id>"
},
"name": "telegram_search_chat_messages"
}
}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 | Telegram text query within this chat; an empty string applies only the other filters. | |
| 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_id | Yes | Exact nonzero native TDLib chat_id returned by Telegram list/search/history tools. Keep its sign and value; do not convert a Bot API ID or Telegram URL. | |
| date_to | No | Exclusive upper bound for message dates, as ISO 8601 with timezone. Must follow date_from when both are supplied; omit for no upper bound. | |
| topic_id | No | Native forum topic ID returned as topic_id by Telegram history/search; omit for no topic restriction or the chat's main draft. | |
| date_from | No | Inclusive lower bound for message dates, as ISO 8601 with timezone, for example 2026-09-16T00:00:00+01:00. Omit for no lower bound. | |
| sender_id | No | Exact native sender ID from returned message metadata: positive for a user, negative for a chat. Omit to include all senders. | |
| media_type | No | Native message filter. all adds no media filter; voice includes voice and video notes; mention selects unread mentions; pinned selects pinned messages. | all |
| unread_only | No | Return only incoming messages newer than the chat's last-read inbox position. This does not mark messages read. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | ||
| next_cursor | Yes | ||
| scanned_count | Yes | ||
| trust_boundary | No |