Search Filters and Pagination¶

tg_messages_search and tg_messages_search_global accept an optional filter — Telegram's server-side kind filter, applied before results leave the server. Values: photos, video, photo_video, document, url, gif, voice, music, round_voice, round_video, my_mentions, geo, contacts, pinned, poll. Telegram's chat_photos and phone_calls/missed_calls filters are not offered: they match service messages, which the message conversion does not yet surface, so every result page would come back empty. This is a different mechanism from tg_messages_list's type parameter: type classifies already-fetched messages client-side (and so supports labels like webpage or invoice that no server filter expresses), while filter restricts the search on the server and covers kinds the client labels cannot (url, pinned, my_mentions).

Both search tools accept minDate/maxDate (unix timestamps) to bound the window, and both return total — the server's full match count across all pages. tg_messages_search additionally takes topicId (restrict to one forum topic) and from (restrict to one sender; same peer formats as peer).

Global search cursor¶

tg_messages_search_global additionally takes scope (users, groups, or channels) to restrict the search to one dialog kind, and paginates through a compound cursor: when the result carries the ready-made nextRate, nextOffsetId and nextOffsetPeer fields (hasMore: true — "probably more"; the terminal signal is an empty page) — copy them into offsetRate, offsetId and offsetPeer verbatim to fetch it; pass either the whole cursor or none of it (the first page). A final or empty page carries no cursor fields. The peers named in each result page are cached with their access hashes, so the returned nextOffsetPeer resolves even for channels the account has never opened. The cache is in-memory, so the cursor does not survive a server restart — a continuation whose peer can no longer be resolved is rejected with a clear error asking to re-run the first page.

History pagination¶

tg_messages_list reads history newest-first and auto-paginates: a limit above Telegram's 100-message page size is fetched in chunks and merged into one response, up to a cap of 1000 messages per call (a larger limit is rejected). total is the server's count from the first page; hasMore: true means older messages remain beyond this response (continue with offsetId). It stays true even when the merged batch is shorter than limit — a service-message-heavy chat can stop the internal scan before the limit fills while older messages still exist. It also accepts fromDate/toDate (unix timestamps): toDate starts the read from the newest message at or before that time (Telegram's offset_date), and fromDate is a client-side floor that stops paging once older messages are reached. A date-bounded read still returns at most limit messages — widen limit (up to 1000) to cover a larger window in one call.