Telegram 频道监测 API 教程
用 Python 独立读取公开 Telegram 频道资料或三条消息样本,校验直接业务对象,保留缩略计数,明确游标和监控边界。

做 Telegram 监控前,先让一次响应回答一个小问题:这是不是你想读的公开频道,或者它近期的小样本里有哪些消息?频道资料和消息页的结构不同;订阅量看起来很大,不等于拿到了精确受众人数。保存一个游标,也不意味着已经实现可靠且不重复的监控。
本次 2026-11-08 修订核对当前契约和保存的公开参考,没有执行新的业务请求。2026-09-27 UTC 的原摘录继续保留,包括旧文里同一 run ID 被复用的问题。新示例只做一次选定读取,不创建调度,不遍历每帖评论,也不声称重新实测了增量监控。
先说结论
- 选择
telegram/web/channel-info或telegram/web/channel-posts;必需请求字段是 channel,不是 username。- 本例帖子请求使用裸 handle 和明确 limit 3。默认值是 20;超过 20 会由服务端自动向旧帖分页。
- outputs[0].data 直接就是业务对象:资料字段,或 messages 与 pagination。不要再套一层 data,也不要套用其他 provider 的 status_code 规则。
- 保留缩略计数与未知值,消息 ID 必须连同频道记录;续页属于另一个尚未测试的决定。
沿用封面是概念插画,名称、卡片、数字和监控/评论链只是示意,不是本次测量或已经执行的动作。图中 handle、认证徽标和 REAL-TIME 标签不构成身份或时效证据。
第一次只选一个任务
| 要回答的问题 | 端点 | 请求例子 | 先看什么 |
|---|---|---|---|
| 核对公开频道资料 | 频道资料 | {"channel":"telegram"} | title、username 与可用资料字段 |
| 查看少量近期消息 | 频道帖子 | {"channel":"telegram","limit":3} | messages 与 pagination |
资料 schema 明确接受裸名称、@handle 或 t.me 链接并自动归一化。帖子 schema 描述的是频道用户名。为同时落在两个契约范围内,共用示例只接收 telegram 这样的裸 handle。这是本地输入限制,不是在说资料端点不接受链接。返回资料里的 username 也不能拿来替换请求字段 channel。
帖子 limit 是 1–100 的整数,默认 20,超过 20 时明确会由服务端自动获取更旧的页面。因此一个 HTTP 请求也可能比读者想象的读取量更大。本例固定为 3,省略 before 和 after。三条是请求的小样本范围,不保证一定有三条,更不表示覆盖全部近期活动。
历史 Telegram 目录截图,保留当时的导航背景。它不能证明评论链刚完成复验,也不表示所有端点共用同一种业务 parser。
复用接入,并告诉 Agent 何时停止
已有 SandBase Key 就放在本地环境或密钥管理器。已连接 Agent 应复用配置,拿到一个选定任务,而不是悄悄同时调用资料和帖子来“建基线”。所选公开读取不要求你的 Telegram 登录、Bot token 或 MTProto 会话,这不代表获得私聊访问或账号授权动作权限。
新项目可以把 SKILL.md、quickstart.md 和快速开始交给 Agent,再说明:“读取 telegram 频道至多三条近期公开消息,保留缺失字段和分页元信息,先展示返回字段名称。”密钥不放聊天。看到结果后再决定存储、分析和额外调用。
下面用安装了 requests 的 Python。它先校验输入,再检查凭据,设置连接/读取超时并拒绝跳转。只发送一次,不自动重试;错误文字不带原响应或密钥。超时和 HTTP 失败会让流程停止,而不是自动再消费一次。
一次请求,按任务检查结构
import os
import re
import requests
def first_request(task, channel):
if task not in ("info", "posts"):
raise ValueError("Choose info or posts")
# This example accepts bare handles only; it does not normalize links.
if not isinstance(channel, str) or not re.fullmatch(r"[A-Za-z0-9_]+", channel):
raise ValueError("Use a nonempty bare channel handle")
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY in the local environment")
route = "channel-info" if task == "info" else "channel-posts"
params = {"channel": channel}
if task == "posts":
params["limit"] = 3
try:
response = requests.post(
f"https://api.sandbase.ai/v1/api/telegram/web/{route}",
headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
json=params, timeout=(10, 90), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"HTTP {response.status_code}; request stopped")
body = response.json()
except ValueError:
raise RuntimeError("Response was not valid JSON") from None
except requests.RequestException:
raise RuntimeError("Network request failed or timed out") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented output")
payload = outputs[0].get("data")
if not isinstance(payload, dict):
raise RuntimeError("Missing business object")
if task == "info":
if any(not isinstance(payload.get(field), str) or not payload[field]
for field in ("title", "username")):
raise RuntimeError("Missing reference channel identity fields")
else:
if not isinstance(payload.get("channel"), str) or not payload["channel"]:
raise RuntimeError("Missing response channel")
messages = payload.get("messages")
if not isinstance(messages, list) or any(not isinstance(m, dict) for m in messages):
raise RuntimeError("Missing or malformed messages array")
if not isinstance(payload.get("pagination"), dict):
raise RuntimeError("Missing reference pagination object")
return payload
if __name__ == "__main__":
result = first_request("posts", "telegram")
print("Business fields:", sorted(result))独立读取资料时,把最后赋值改为 result = first_request("info", "telegram"),保留后面的 print。不要在帖子调用后直接追加它,除非明确需要第二次请求。请求体不加 model,操作由完整 POST 路由决定。
本地资料检查要求 title 和 username 为非空字符串;帖子检查要求响应 channel、对象组成的 messages 数组和 pagination 对象。这些是针对所选参考的保护条件,不是所有 Telegram 路由的统一 schema。明确返回空 messages 可接受;集合缺失、结构错误或运行未完成会报错,不伪装成“频道刚好没内容”。计数、媒体、正文和布尔标记等可选字段按原样返回。
原证据继续保留,也说明它的疑点
旧文将下方资料摘录标为 2026-09-27 UTC 实测。缩略订阅数属于历史观测,不是该频道的当前值:
{
"id": "8c815356-e1f6-4668-959c-375f9471822f",
"status": "completed",
"model": "telegram/web/channel-info",
"outputs": [
{
"data": {
"title": "Telegram News",
"username": "telegram",
"subscribers": "9.46M",
"verified": true,
"counters": { "photos": "16", "videos": "228", "links": "378" }
}
}
]
}原帖子摘录也不改写:
{
"id": "8c815356-e1f6-4668-959c-375f9471822f",
"status": "completed",
"model": "telegram/web/channel-posts",
"outputs": [
{
"data": {
"messages": [
{
"id": 460,
"date": "2026-08-26T19:12:34+00:00",
"text": "…",
"views": "1.48M",
"is_forwarded": false,
"reactions": []
}
],
"pagination": { "after_cursor": 460, "before_cursor": 441, "has_more_before": true, "limit": 20 }
}
}
]
}两段原记录的 model 不同,却共用 8c815356-e1f6-4668-959c-375f9471822f。这是原文的调用归属疑点;本轮不能仅凭这个共享 ID 证明做过两次独立执行,也不会猜一个新 ID 来替换其中任何一段。
另有独立保存的公开样例:资料时间为 2026-10-07T17:37:02.535Z,帖子为 2026-10-07T17:37:14.205Z。保存输入都是 channel telegram,帖子另外带 limit 3。这些参考支持当前直接资料对象和 messages/pagination 的读取方式,但它们是 11 月 8 日阅读的历史材料,不是本修订刚执行的结果。短 README 与完整样例可能展示不同缩略订阅值,也不能合并成测出的增长曲线。
历史 channel-posts 参数与信封参考。before/after 是当前有文档的输入,但本修订都没有发送,也没有验证续页或增量轮询。
订阅量和播放标签不是精确触达
原摘录里的 9.46M 订阅和 1.48M views 都是展示字符串,其他保存样例可能是另一缩略值。应把原字符串和获取背景放在一起。把 M 转成百万只是近似换算,无法恢复被省略的精度,也不能证明两个快照使用完全一致的取整规则。
订阅量是频道层级显示值,views 是某条消息的观测值。它不是独立读者人数,也不是转化量。不要拿两个舍入后的数字相除,再把结果命名为精确互动率;显示标签变化也不等于精确测出了多少新增受众。
没有 views 就保留未知,空 reactions 是返回的空数组,不能推广成所有位置都无互动。false 是明确布尔值,null 则可能表示不适用,二者不要混同。短参考省略 views 或 type,也不等于端点永远不返回这些字段;示例不会为了报表完整而补零。
消息 ID 要和频道一起保存
数字消息 ID 属于某个频道。以后存多个频道的数据时,匹配键应包含 channel 和 message ID,而不是一张全局 ID 字典。请求 handle、响应 channel、返回资料里的身份先分别保存,确认是预期来源后再关联。helper 不会为了匹配输入而悄悄重写响应身份。
is_forwarded 和 forwarded_from 描述的是这条消息的归属线索,不是让 Agent 自动查询来源频道的命令。text_html 是带标记的内容,展示层要明确处理,不能直接当安全 HTML 插进页面。本例只打印字段名,不渲染 HTML,不打开链接预览,也不下载图片或视频。
媒体对象只能说明参考实际给出的内容。photos 或 videos 为空,不能直接推导所有媒体均可获取,尤其要留意 has_unsupported。返回 URL 是资源引用,不是文件已经下载的证据,也不自动赋予转载权。
游标方向有文档,续页尚未实测
所选 schema 将 after 描述为较新帖子的整数游标,before 为较旧帖子的整数游标,分别取自上一结果的 pagination.after_cursor 与 pagination.before_cursor,默认值均为零。保存的帖子样例还包括 has_more_before、count、limit 和 pages_fetched。返回了就保留,不从消息 ID 或预期条数编出这些值。
当前示例不发游标、不递增 ID,也不抓下一页。它不承诺记住 after_cursor 后就一定不会重复、不会漏帖。真正接入增量监控,还要测试续页行为、决定何时持久化游标,并处理采集失败。多次调用、重试与评论读取都是额外工作量,不是隐形的初始化。
历史 post-comments 参数参考。评论不属于本轮两个选定任务;图不能证明每条消息都有可读评论区,也不表示回复已重新获取。
先算单次读取,再考虑监控
2026-11-08 免费 inspect 显示,两个端点均为 $0.001,符合组织内合格 API 每日共享 100 次额度,00:00 UTC 重置。资格不等于还剩多少次或账户余额。本轮未测真实扣费,也不保证免费成功。
选一个请求标价 $0.001;分别选资料和帖子才是 $0.002,尚未考虑额度。旧代码对符合条件的每条消息追加评论请求,定时轮询又会继续累加。limit 超过 20 还改变单个帖子请求内部的获取行为,所以 HTTP 调用次数也不能直接代表底层页面数或返回消息量。
原代码归档而非继续照抄
所有原 Python 在历史归档逐字保留并附哈希,包括自动评论遍历、宽松空值回退、游标推进和监控骨架。它们记录旧文章,不作为当前运行指引。本次用一次明确读取替换主流程,同时保留原实测摘录可供审阅。
常见问题
请求字段是 username 吗? 不是,应使用 channel。资料中的 username 是输出字段,不会改变当前输入契约。
为什么选 limit 3? 让首请求足够小,并避开文档说明的超过 20 自动回补旧页行为。这不代表频道覆盖完整。
可以计算精确受众增长吗? 仅凭缩略显示字符串不行。保留源值及日期,不把近似订阅量或 views 当成精确增长、独立读者数。
拿到首个结果后做什么? Telegram API 总览提供所选入口,并区分其他能力的历史导航。先明确下一个问题和预算,再添加分页、评论、分析或调度。
觉得有用?分享给更多人