> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Telegram 如何往前翻历史、往后取新消息？搜索也能用 before 吗？

> 使用 telegram.web.fetch_channel_posts 返回的整数游标 before_cursor 或 after_cursor 分别向旧或向新翻页；telegram.web.fetch_channel_search 无游标与日期参数，需在本地按时间筛选。

用 `telegram.web.fetch_channel_posts` 翻 Telegram 频道时，把上一次响应返回的整数游标原样传回：`before` 读更旧的消息，`after` 读更新的消息。频道内搜索 `telegram.web.fetch_channel_search` 没有 `before`、`after` 或日期参数；要覆盖某个时间段，先读取有限的一批消息，再按返回的发布时间筛选。

## `before` 和 `after` 分别怎么用？

在 `telegram.web.fetch_channel_posts` 中，`before` 请求更旧的消息，`after` 请求更新的消息。第一次请求时 `before` 和 `after` 均不填写。下一次请求按想要的方向，把上一次响应里的 `data.pagination.before_cursor` 或 `data.pagination.after_cursor` 原样传回，两个游标都是整数。不要把游标当页码加一，也不要在同一个请求里同时填 `before` 和 `after`。

## `limit=100` 是只取一页吗？

不是。`limit` 范围 1–100，默认 20。当 `limit` 大于 20 时，`telegram.web.fetch_channel_posts` 会自动向较旧消息翻页，因此 `limit=100` 不保证单页返回 100 条。需要控制范围时先用 `limit` 20，保存每次请求和原始响应。达到 `limit` 不等于频道历史已经读完。

## 频道内搜索怎样筛选？

`telegram.web.fetch_channel_search` 必填 `channel` 和 `query`，`limit` 为 1–100。频道内搜索没有 `before`、`after` 或日期参数，不要把消息列表的翻页字段加到搜索请求里。搜索范围只是指定的频道，不是整个 Telegram。需要时间范围时，先取得有限的一批消息，在本地按返回的发布时间筛选，并报告实际扫描的范围，不声称完整覆盖。

## 什么情况停止翻页？

游标缺失或重复、响应失败或达到你的请求上限时，停止翻页，保存本次扫描范围和停止原因。读取旧消息时，用最后一个有效的 `before_cursor` 记录断点。归档每次的原始响应，从 `data.messages` 读取完整的消息对象，在每个消息对象里核对正文和消息 ID。

例如周一保存了频道最新的一批消息。要回看上周的公告，用周一响应的 `before_cursor` 请求更旧的消息。要检查到周二为止有没有新公告，用周一响应的 `after_cursor` 请求更新的消息。较旧和较新的记录分开保存，最后按频道内的消息 ID 核对重叠。

[完整归档流程](/zh/guides/telegram-channel-archive)