Telegram 频道监测 API 教程

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

深色电影质感画面:一个 Telegram 频道基线解析成新帖流和一条评论串,汇入 Agent 内核

做 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 目录 历史 Telegram 目录截图,保留当时的导航背景。它不能证明评论链刚完成复验,也不表示所有端点共用同一种业务 parser。

复用接入,并告诉 Agent 何时停止

已有 SandBase Key 就放在本地环境或密钥管理器。已连接 Agent 应复用配置,拿到一个选定任务,而不是悄悄同时调用资料和帖子来“建基线”。所选公开读取不要求你的 Telegram 登录、Bot token 或 MTProto 会话,这不代表获得私聊访问或账号授权动作权限。

新项目可以把 SKILL.md、quickstart.md 和快速开始交给 Agent,再说明:“读取 telegram 频道至多三条近期公开消息,保留缺失字段和分页元信息,先展示返回字段名称。”密钥不放聊天。看到结果后再决定存储、分析和额外调用。

下面用安装了 requests 的 Python。它先校验输入,再检查凭据,设置连接/读取超时并拒绝跳转。只发送一次,不自动重试;错误文字不带原响应或密钥。超时和 HTTP 失败会让流程停止,而不是自动再消费一次。

一次请求,按任务检查结构

Python
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 实测。缩略订阅数属于历史观测,不是该频道的当前值:

JSON
{
  "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" }
      }
    }
  ]
}

原帖子摘录也不改写:

JSON
{
  "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 参数参考 历史 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 参数参考 历史 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 总览提供所选入口,并区分其他能力的历史导航。先明确下一个问题和预算,再添加分页、评论、分析或调度。

觉得有用?分享给更多人