Telegram 公开数据 API | SandBase

Telegram 是突发新闻、加密社区和公开广播频道流动最快的地方——一条由频道帖子、表情反应和评论串组成的信息流,可以直接映射到媒体监测、社区研究和趋势发现等场景。可要用程序去读这些数据,通常意味着搭一个 MTProto 客户端、维护一个会话、解析原始协议消息,才能拿到第一条帖子。

SandBase 的 Telegram 公开数据 API 免去了这些前置成本。它通过普通的 REST 端点读取 Telegram 公开的频道、帖子、评论和搜索——只用一个 SandBase API 密钥,不需要登录 Telegram、也不需要 MTProto 客户端。端点 API 参考是每个参数和响应信封的权威来源;下面展示的业务载荷字段名来自我实际跑的一次 channel-info 调用(测试于 2026-09-27,UTC),仅作为一次观测到的结构展示——请以你所调端点的一份真实响应为准核对,因为负载会随时间变化。

这不是 Telegram 官方的 Bot API 或 MTProto。 当你需要机器人操作、已认证的会员操作,或需要有正式授权协议的数据时,请走 Telegram 官方 API。当你的工作流需要用于研究和监测的公开、只读频道数据时,用 SandBase。想上手?获取 SandBase API 密钥,然后浏览 Telegram 端点。

先说结论

• 一套 API 即可读取 Telegram 公开的频道信息、帖子、评论、频道内搜索和相似频道。
• 本文的 Model API 端点用 POST /v1/api/telegram/<path> 调用——只传该端点的参数,无 MTProto,一个 SANDBASE_API_KEY。
• 端点以自然标识为入口:频道用 channel 用户名,单条帖子或其评论用整数 post_id。
• 只返回公开、只读数据。你这边无需发帖、无需平台登录、不涉及私聊;用 SandBase API 密钥鉴权即可。

你需要哪种 Telegram API?

你的需求	选择	原因
运行机器人、以会员身份操作,或使用账号授权数据	Telegram 官方 Bot API / MTProto	机器人和账号级操作应通过 Telegram 直接进行。
读取公开的频道信息、帖子、评论或搜索	SandBase Telegram 公开数据 API	普通 REST、一个 SandBase 密钥、结构化 JSON,面向只读工作流。
私聊或仅账号可见的数据	两种公开方案都不适用	这类数据不在本篇公开数据指南范围内。

Telegram API 能取到什么

目录建立在一个 web 面上。按用途分组:

• 频道 — 公开频道信息(标题、订阅数、认证、计数器)和相似频道发现。
• 帖子 — 频道的近期帖子,以及按 post_id 读取单条帖子详情。
• 评论 — 某条帖子的评论串。
• 搜索 — 按关键词在频道内搜索。

动手前请以每个端点的线上 API 参考为准核对具体面和参数;可用性因端点而异。

SandBase 上的 Telegram API 页面——带标签的概览和端点列表,每个端点都标了路径。

Telegram 提供什么,SandBase 补什么

公开数据来自 Telegram。SandBase 并不拥有或运营 Telegram,它为符合条件的公开数据工作流提供一层统一的 API。每个能力都成为一个稳定端点,鉴权收敛为单个密钥,响应回来是可预测的 JSON——于是 Agent 可以沿着”读频道 → 读帖子 → 读某条帖子的评论”这一条约定链式调用,而不用维护 MTProto 客户端。

快速上手:第一次调用

SandBase 暴露不止一个 API 面。目录里可能显示 /apis/v1/... 下的 GET 路径;本文使用每个端点 API 参考上标注的带厂商前缀的 Model API 路径。不要擅自改动 HTTP 方法或 URL——以你所选端点的参考为准。

按用户名读取一个公开频道:

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/telegram/web/channel-info",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"channel": "telegram"},
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "Telegram 请求未完成"))

# 参考保证的是信封(id/status/model/outputs[0].data);
# 业务字段随端点而定,用防御式读取,
# 并以一份真实响应核对确切路径。
data = body["outputs"][0]["data"]
print(data.get("title"), data.get("subscribers"), data.get("verified"))

curl -X POST https://api.sandbase.ai/v1/api/telegram/web/channel-info \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "telegram"}'

响应使用一致的信封:一个 id、一个 status、model 名称,以及——在 completed 运行上——一个 outputs 数组,其唯一元素在 data 下承载数据。failed 或 timeout 的运行则带 error 而没有 outputs,所以读取 outputs[0].data 前先根据 status 分支判断,并查阅每个端点参考确认其运行模式(run mode)。这个信封才是端点参考所保证的;data 内部的操作字段按端点各自记录。下面是我那次 channel-info 调用的一段裁剪后的真实响应(测试于 2026-09-27,UTC)——数值会随时间变化,所以请把字段名当作观测到的、而非保证的,并对照真实响应核对:

{
  "id": "b7159c20-ae57-47cb-bf5d-e34ab1020d10",
  "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" }
      }
    }
  ]
}

响应结构因端点而异——请检查一次真实响应,并逐端点确定精确的字段路径。

端点 API 参考是每个参数名和响应路径的事实来源。

能力地图

能力簇	代表端点	典型用途
频道信息	telegram/web/channel-info	按用户名查频道规模和元数据
频道帖子	telegram/web/channel-posts	读取频道的近期帖子
帖子详情	telegram/web/post-detail	按整数 post_id 读单条帖子
帖子评论	telegram/web/post-comments	互动与情感分析输入
相似频道	telegram/web/similar-channels	频道发现

分页方式因端点而异——channel-posts 返回一个带游标字段的 pagination 对象,你传一个游标请求参数来取更早的帖子。请查阅每个端点的结构。

Telegram 端点列表的一角,在 web 面上。

在 Agent 工作流中链式调用

因为每个端点共享同一套鉴权和同一个响应信封,Agent 可以从一个频道一路走到一条评论,而不用为每个面单独写特例。一个常见的监测模式是这样:

1. 读频道。 用一个 channel 用户名调用 telegram/web/channel-info 拿到标题、订阅数和计数器。
2. 读帖子。 调用 telegram/web/channel-posts 拿近期消息,用返回的游标往前翻更早的。
3. 读评论。 用 channel 加一个整数 post_id 调用 telegram/web/post-comments 拿互动输入。

每一步都返回相同的 { id, status, model, outputs } 结构,所以你的 Agent 只需按 status 分支一次,并在每一步复用同一段读 JSON 的代码。

常见用例

Telegram 频道 API 做受众规模评估

用一个 channel 用户名调用 telegram/web/channel-info 读取标题、订阅数、认证状态和内容计数器。输入:一个 channel 用户名。输出:一条频道记录。端点:channel-info。

Telegram 帖子 API 做内容监测

读取 telegram/web/channel-posts 拿频道的近期消息,再用返回的游标往前翻更早的。输入:一个 channel 用户名。输出:一组帖子加分页。端点:channel-posts。

Telegram 发现 API 找相关频道

用一个 channel 调用 telegram/web/similar-channels 浮现相关频道。输入:一个 channel 用户名。输出:一组相似频道。端点:similar-channels。

为什么放在 API 层来做

你当然可以搭一个 MTProto 客户端、解析原始协议消息,但这条路很脆:你要管会话、处理重连,维护的是一个解析器而不是在做产品。通过一层统一 API 来读,意味着你的代码依赖的是有名字的 JSON 字段和单个响应信封,而不是某个协议内部实现。鉴权是一个密钥,而且因为每个端点都返回相同的 { id, status, model, outputs } 结构,重试、日志和错误处理都可以收进一个你写一次、处处复用的辅助函数里。

正是这种一致性让工作流对 Agent 而言可组合。把一个 channel 换成另一个、把一个 post_id 换成下一个,代码路径完全一样。再加第四个读取——比如某个频道的相似频道——它也照样接在同一个判 status 的辅助函数后面。实际的收益是:你的时间花在”数据对你的研究意味着什么”上,而不是花在维持一个协议客户端去追一个移动靶。当你需要的不止是单次读取时,在线上列表里查到合适的端点,并在接入前确认它的参数。

局限与边界

• 仅公开、只读数据。 不发帖、不做机器人操作、不涉及私有或仅账号可见的数据。
• 速率与量级。 把响应当作尽力而为的读取;作为客户端侧的韧性措施,遇到 HTTP 429 等瞬时错误时按退避策略重试。
• 参数与结构随上游面而定。 channel 是用户名;post_id 是整数;channel-posts 的分页用每端点各自的游标。某些端点会注明特定深度读取需要上游 MTProto。先看一次真实响应、读一遍结构。
• 以线上参考核对端点。 可用性和字段可能变化;在依赖某个具体端点前先确认。
• 这不是 Telegram 官方合作。 SandBase 提供对公开数据的统一访问;请就你的使用场景遵守 Telegram 条款和适用规则。

常见问题

我需要 Telegram 机器人 token 或登录吗? 不需要。你用自己的 SANDBASE_API_KEY 向 SandBase 鉴权。这些读取端点不需要你这边有 Telegram 账号、机器人 token 或 MTProto 会话。

什么标识一个频道或一条帖子? channel 用户名标识一个频道,整数 post_id 标识一条帖子或其上的评论串。

分页怎么做? channel-posts 返回一个带游标字段的 pagination 对象;下一次调用时传一个游标请求参数,取更早的帖子。请查阅每个端点的结构。

我能读私聊或群组吗? 不能。这套 API 只返回公开频道数据。私聊、群组和账号授权内容不在范围内。

从读一个频道开始

创建一个 SandBase API 密钥,调用 channel-info,在扩展到帖子、评论或搜索之前先检查返回的结构。准备好后:

• 获取 SandBase API 密钥
• 浏览 Telegram 端点
• 打开 channel-info API 参考