telegram_search_messages
Search cached Telegram channel messages using a text query, with pagination and response format options. Returns matching messages from the current server session cache only.
Instructions
Search for messages in a Telegram channel (from local cache ONLY).
⚠️ CRITICAL LIMITATIONS - READ CAREFULLY:
Session-Only Cache: This tool ONLY searches messages cached in the CURRENT SERVER SESSION.
Messages published/edited BEFORE the server started are NOT available
Cache is CLEARED when the server restarts
This is a Telegram Bot API limitation, not a bug
Cannot Retrieve Historical Messages: The Telegram Bot API does not provide methods to fetch arbitrary messages or search message history.
What IS Cached: ✅ Messages published via publish_message in current session ✅ Messages edited via edit_message in current session ✅ Photos published via publish_photo in current session ✅ Photo captions edited via edit_message_caption in current session
What is NOT Cached: ❌ Messages sent before server started ❌ Messages sent by other bots or users ❌ Messages sent when server was offline
You CAN Still: ✅ Edit messages from previous sessions if you have the message_id ✅ Delete messages from previous sessions if you have the message_id ✅ The message_id is returned when publishing messages - store it if needed later!
Args: channel_id: Channel username (e.g., '@mychannel') or numeric chat ID to search in. query: Search query string. Performs case-insensitive search in message text/caption. If None or empty, returns all cached messages for the channel. limit: Maximum number of results to return. Default is 10. Results are sorted by date (newest first). offset: Number of results to skip. Use for pagination. Default is 0. response_format: Response format. Options: 'json' for structured data, 'markdown' for human-readable text. Default is 'markdown'.
Returns: A dictionary containing: - messages: List of matching messages (may be empty if nothing cached) - count: Number of messages returned in this page - total: Total number of matching messages in cache - offset: Current offset value - limit: Current limit value - has_more: Boolean indicating if more results are available - next_offset: Offset value for the next page (if has_more is True) - query: The search query used - channel_id: The channel searched - status: Operation status If response_format='markdown', returns formatted text content.
Note: If you need to work with older messages, you must keep track of message_id values returned when publishing. There is no way to retrieve message_id for historical messages through the Telegram Bot API.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| offset | No | ||
| channel_id | Yes | ||
| response_format | No | markdown |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||