REST API——用你自己的代码自动化 Telm

1API 能让你做什么

Telm REST API 让你自己的代码拥有和仪表盘相同的能力：让任何文本通过反垃圾流程、在放行之前查询某个 Telegram 用户、读取和修改群组的防护设置、管理自定义规则和白名单、拉取审核日志和数据分析，以及为实时事件注册 Webhook。

这样一来，Telm 就从一个驻留在群组里的机器人，变成了你可以接入任何地方的基础设施——网站注册表单、CRM 机器人、你自己的 Telegram 机器人，或者一次配置一百个群组的脚本。

• 基础 URL：api.telm.com/api/public/v1——一个稳定的版本化路径（v1 是契约版本）。
• 所有请求和响应都是基于 HTTPS 的 JSON。
• 交互式文档和机器可读的 OpenAPI 3.1 规范都在开发者页面上——把规范导入 Postman、代码生成器或 AI 智能体，几分钟就能搭好集成框架。
• 计量调用在每个响应中都会返回 X-Quota-Limit、X-Quota-Used 和 X-Quota-Reset 响应头。

2请求如何在 Telm 中流转

公开 API 位于独立的路径前缀 /api/public/ 下，与仪表盘分开。每次调用都通过 API key 而不是浏览器会话进行身份验证，并根据你的套餐和配额进行检查，然后在审核你群组的同一个实时引擎上运行，最后以 JSON 返回。

由于 API 与机器人使用相同的引擎和数据，你在仪表盘中能看到或修改的任何内容，都可以用代码完成——你用代码做出的任何修改也会立即出现在仪表盘中。

• 请求是无状态的：每个请求都携带自己的 key，独立成立。
• key 代表你的账号执行操作，只能触及你的账号担任管理员的群组。
• 垃圾检测端点使用的正是线上的规则流程，所以 API 的判定与机器人在群组中的处理一致。

3使用 API key 进行身份验证

每个请求都通过形如 tk_live_ 加随机字符的 API key 进行身份验证，而不是你的仪表盘登录。你在账号中创建 key，并把它作为 Bearer 令牌放在 Authorization 请求头中，或放在 X-API-Key 请求头中发送。

完整的密钥只在创建时显示一次。之后仪表盘只会用简短的前缀列出 key，让你无需保存完整值也能识别它。如果 key 泄露，请撤销它并签发新的 key——撤销会立即生效。

• 以 Authorization: Bearer tk_live_your_key_here 的形式发送 key（X-API-Key 请求头同样可用）。
• key 带有读取或写入权限范围——GET 请求需要读取，任何修改数据的请求需要写入。只读 key 无法创建或编辑。
• 你最多可以同时拥有十个有效的 key，因此可以为每个脚本或服务使用单独的 key。
• 缺少 key 或 key 无效时返回 401；key 缺少所需权限范围时返回 403 insufficient_scope。

4可用的端点

API 围绕垃圾与用户检测、群组管理以及账号自助服务组织。单个垃圾检测端点对所有套餐开放；其余部分属于 Pro 和 Business。

• POST /spam/check——让一段文本通过审核线上流量的同一套规则引擎（所有套餐）。在 Pro 及以上可以选择开启 AI 检查。
• POST /spam/check-batch——一次调用检测最多 20 段文本，仅使用规则（Pro+）。
• POST /users/check——查询某个 Telegram 用户：CAS 状态、Telm 垃圾判定信号以及其在你群组中的信誉（Pro+）。
• GET /groups 和 GET /groups/{id}——列出并读取你的群组（Pro+）。
• GET 和 PATCH /groups/{id}/settings——读取和修改群组的防护设置（Pro+）。
• GET/POST/PUT/DELETE /groups/{id}/rules——管理自定义审核规则（Pro+）。
• GET/POST/DELETE /groups/{id}/whitelist——管理群组白名单（Pro+）。
• GET /groups/{id}/journal 和 GET /groups/{id}/analytics——读取审核日志和数据分析（Pro+）。
• GET/POST/PATCH/DELETE /webhooks——管理实时事件 Webhook（Pro+）。
• GET /usage 和 GET /me——查看你的配额和 key 信息；这些调用从不消耗配额（所有套餐）。

5垃圾检测端点详解

POST /spam/check 是 API 的核心，也是唯一一个在任何套餐上都能试用的端点。发送包含待检测文本的 JSON 请求体，响应会返回判定结果、数值分数、置信度以及你可以在自己产品中应用的建议操作。

单段文本最多 10,000 个字符。在 Pro 及以上，你可以为更棘手的情况选择开启 AI 检查，它从单独的每日 AI 检查额度中扣除。对于大批量处理，批量端点一次调用可检测最多 20 段文本，配额按条目计算。

• 根据判定结果和分数决定你自己的产品如何处理——拦截表单提交、标记潜在客户，或在你自己的机器人中自动删除消息。
• 批量端点仅使用规则；AI 阶梯只在单段文本端点上可用。
• 请求体有大小上限（单次检测约 64 KB，批量 256 KB）；超出时返回 413。

6套餐、速率限制与每日配额

访问量通过两种方式计量：每分钟速率限制（突发上限）和在 UTC 午夜重置的每日调用配额。两者都按账号计算，由你所有的 API key 共享。你可以在任何套餐上试用单个垃圾检测端点，但涉及规则、设置、批量检测和 Webhook 的真正集成需要 Pro 或更高套餐。

• Free——每天 100 次调用，仅限垃圾检测。
• Pro——每天 10,000 次调用，完整 API 和 Webhook，外加每天 1,000 次 AI 检查。
• Business——每天 50,000 次调用，完整 API 和 Webhook，外加每天 10,000 次 AI 检查。
• 每分钟速率限制也随套餐提升——Free 每分钟 60 个请求，Pro 600 个，Business 1,800 个。
• GET /usage 和 GET /me 从不计入配额，你随时都可以查看剩余额度。

7错误处理与状态码

API 使用标准的 HTTP 状态码，并在响应体中提供机器可读的错误码。请让你的客户端读取这些错误码，并据此退避或提示升级，而不是盲目重试。

当你超出每日配额时，计量调用会返回 429，附带 daily_quota_exceeded 错误码、Retry-After 响应头，以及列出你的套餐、上限、已用次数、重置时间和升级提示的响应体。需要更高套餐的端点会返回 403 plan_required 以及所需的套餐。

• 401——缺少 API key 或 key 无效。
• 403 plan_required——该端点需要 Pro 或更高套餐。
• 403 insufficient_scope——key 缺少执行修改操作所需的写入权限范围。
• 429 daily_quota_exceeded 或 rate_limit_exceeded——等到重置时间或升级套餐；请遵循 Retry-After 响应头。
• 读取 X-Quota-* 响应头，提前避开上限。

8打造稳健集成的最佳实践

几个好习惯能让集成在规模扩大时依然可靠且安全。

• 把 key 存放在密钥管理工具中，切勿放在客户端代码或 git 仓库里；为每个服务使用单独的 key，这样撤销其中一个不会影响其他服务。
• 留意 X-Quota-Used 和 X-Quota-Limit 响应头（或轮询 GET /usage），在触及上限之前而不是之后降低调用频率。
• 遇到 429 时遵循 Retry-After 退避；遇到 403 plan_required 时显示升级提示，而不是重试。
• 需要实时响应时，优先使用 Webhook 而不是轮询——让 Telm 把事件推送给你。
• 定期轮换 key，一旦怀疑泄露就立即更换。

9常见集成场景

API 的用途远不止审核 Telegram 消息。

• 网站和应用注册：在接受注册或评论之前，让提交的文本或用户名通过 POST /spam/check。
• 你自己的 Telegram 机器人：在处理函数中调用检测端点，在 Telm 不管理的机器人中复用 Telm 的判断能力。
• 批量配置：通过设置和规则端点，用脚本把同样的规则、白名单和设置应用到几十个群组。
• 数据与告警：注册 Webhook，把审核事件实时推送到数据仓库、看板或告警频道。