1能与你技术栈其余部分对话的审核
一个完全活在 Telegram 内部的审核机器人很有用，但它也是一座孤岛。它做出的决定——它删除的每一条消息、它筛查的每一个用户、它击退的每一次突袭——都锁在一个聊天窗口里，除非有人打开 Telegram 去看。对于单个社区，这没问题。但对于一个把审核作为更大运营一环的团队来说，这意味着：那个最了解谁在滥用你空间的系统，恰恰是唯一一个无法与你运行的其他任何东西对话的系统。
公开的 REST API 和 Webhook 弥合了这道鸿沟。它们把 Telm 从一个自成一体的机器人，变成一个你可以接入现有工具的组件：你的监控与值班体系、你的合规归档、你自己的产品、你的内部仪表盘。守护你群组的同一个引擎，如今成了你其他系统可以查询、监听并驱动的东西。
本指南将带你走一遍 API 和 Webhook 实际暴露了什么——端点、事件、安全模型——以及团队用它们构建的具体东西。下文的一切都是今天就能用的真实能力；没有需要等待的 SDK，这里描述的也没有一样是产品仅仅计划要做的。
2REST API 与你的密钥
API 位于 `https://api.telm.com/api/public/v1`。它是一个朴素的 REST 接口——你用普通的 HTTPS 请求和 JSON 来调用它，任何语言皆可，不需要专门的客户端库。只要你的代码能发出一个 HTTP 请求，它就能与 Telm 对话。
身份验证通过 API 密钥进行。你在仪表盘的「设置 → API 与 Webhook」下创建密钥，每个密钥在创建时只向你显示一次——请当场把它复制进你的密钥保管库，因为此后再也无法取回。密钥以 `tk_live_` 为前缀，因此在日志和配置里很容易辨认。每个密钥都带有一个作用域——读或写——所以一个只需拉取决策日志的服务可以持有只读密钥，而更改设置的自动化则拿到写密钥。为每个系统各铸一把密钥，吊销一把泄露或退役的密钥绝不会惊动其他密钥。
用量由一份与你套餐挂钩的每日请求配额来管理，因此吞吐量是可预测的，一个失控的脚本也无法耗尽一切。最轻量的检查——文本垃圾扫描——在每个套餐上、在该配额之内都可用；更完整的能力面，从决策日志到设置管理再到 Webhook，则是 Pro 和 Business 套餐的一部分。确切的数字列在文末。
3按需筛查文本与用户
两个端点让你能按需、用自己的代码运行 Telm 的判断，而无需任何消息真正经过某个 Telegram 群组。
`POST /spam/check` 会把一段文本送过守护你社区的那套一模一样的生产引擎——共享的垃圾发送者信号、模式规则、分类器——并返回一个裁决。这是唯一在每个套餐上都可用的调用，这让它天然适合做你自己产品的垃圾过滤器：用守护你 Telegram 空间的同一套检测，去筛查评论、注册简介、支持工单或市场挂牌。加上 `include_ai`，就能为更棘手、更模棱两可的情况纳入一个 AI 裁决（Pro 和 Business 提供），而在这些套餐上，你可以在单次请求里批量处理最多二十条文本，而不必逐条调用。
`POST /users/check` 筛查的是一个人，而非一条消息。它结合全球 CAS 封禁名单，以及 Telm 从众多社区的审核中积累的自有数据集，并返回一个风险等级（Pro 和 Business 上提供），让你能决定施加多少阻力——干净的账号直接放行，可疑的账号留待复核。把它接入你自己的新用户引导流程，就能在你网站或应用的门口拦下一个已知的坏分子，而不是等他加入 Telegram 群组之后才发现。
两个调用都当场作答：你发送文本或用户，就在响应里拿回评估。没有队列要轮询，也没有回调要等待——决定随回复一同到来。
4在事情发生的那一刻被推送
轮询决策日志用于归档没问题，但当你想在某件事发生的一瞬间就对它做出*反应*时，你想要的是被推送，而不是去询问。Webhook（Pro 和 Business 上提供）做的正是这件事：你注册一个端点，一旦相关事件触发，Telm 就会在那一刻向它发出一个 HTTP 请求。这些事件覆盖了要紧的时刻——针对内容的 `spam.detected` 和 `message.suspicious`，以及针对成员的 `user.banned`、`user.kicked`、`user.muted`、`user.joined` 和 `user.left`。
最显而易见的用法，是把一波垃圾攻击变成一次告警。把 `spam.detected` 指向你的监控或值班系统，一次突然的激增就会变成给当班者的一次呼叫，落在你其他事故汇聚的同一个地方——没有人需要盯着 Telegram，也能注意到一场攻击正在开始。同一条事件流还能驱动实时仪表盘、让某个外部系统与封禁保持同步，或触发你喜欢的任何工作流。
由于这些请求是从外部世界进入你的基础设施的，每一次送达都带签名。每个请求都携带一个 `X-Telm-Signature` 响应头，形如 `v1=hex(hmac_sha256(secret, "timestamp.body"))`——即对时间戳和原始正文算出的 HMAC-SHA256，用一个只有你和 Telm 共享的密钥加密。在你这端重新计算这个签名，能证明请求确实来自 Telm、在传输途中未被伪造或篡改；时间戳则让你能拒绝过期的重放。在信任载荷之前先验证签名——这不过几行代码，却是一个安全的 Webhook 接收方里最重要的一步。
5你可以信赖的送达
一个推送模型只有在能应对你端点变慢、正在重启或短暂宕机的时刻时，才值得信赖——而 Telm 的模型做到了。送达是至少一次的：每个事件都带有一个稳定的 `id`，Telm 会一直尝试，直到你的端点确认收到。由于「至少一次」意味着同一个事件可能名正言顺地到达两次，请基于那个 `id` 去重——记下你已处理过的，忽略重复的——那么无论一次送达被重试多少次，你的处理都始终正确。
重试遵循一份逐渐拉长的时间表，而不是猛捶一个正在挣扎的端点：立即，然后在一分钟、五分钟、三十分钟、两小时和六小时后——总共六次尝试，拉开间隔，给正在恢复的服务留出回来的余地。如果一个端点始终坏着——连续二十次失败、且七十二小时内没有一次成功送达——Telm 会自动停止向它发送，并在 Telegram 里通知你，于是一个失效的 URL 会变成一句让你去修接收方的清晰提醒，而不是一大堆失败无声地越积越多。
要把一个新集成做对，你不必去制造真实事件来测试它。一个测试 ping 让你能按需向你的端点发出一次样例送达，确认你的签名校验和处理器都能正常工作；而一份送达历史会显示发送了什么、每一次尝试的结果如何——于是你可以从记录里调试一个行为异常的接收方，而不是靠猜。
6每一个决定的可查询记录
引擎决定的一切都会被记录，而 `GET journal` 会把这份记录交到你的代码手中。每一条记录都是一个决定：裁决、它背后的评分、触发了哪些规则，以及随之而来的行动。由于它采用游标分页，你可以可靠地走遍整段历史——一页接一页，没有遗漏也没有重复——并把它拉进你存放记录的任何地方。
这让决策日志成为合规归档的中坚。那些必须说明某位成员为何被移除的团队——出于平台政策、客户合同或监管要求——会按计划把日志导出到自己的长期存储里，从而拥有一份对每一次执行行动的独立、可查询的记录，而不必依赖在 Telegram 里回滚翻找。这正是仪表盘的 审计日志 呈现给人看的同一份证据，如今也能供你的系统使用。
在它旁边，一个分析端点会返回逐日的序列——一段时间内的数量与趋势——让你能在自己的商业智能工具里，把审核负载与你追踪的其他一切并排绘制成图，而不是从屏幕上读取。决策日志和分析都属于 Pro 和 Business 套餐。
7用代码管理众多群组
API 不只会读取和监听——它还会写入。在 Pro 和 Business 上，你可以 `PATCH` 一个群组的设置，并对它的规则和白名单执行完整的增/查/改/删，全部以编程方式完成。任何你会在仪表盘里手动配置的东西，都可以从脚本里配置。
这正是大规模运行审核变得可行的原因。一个管理着数十个社区的机构或大型运营方，不会想去逐个打开、把同样的改动点一遍；他们想的是把策略定义一次，然后处处套用。有了 API，你只需一次自动化的执行，就能在整支群组舰队里推出一条新规则、调整一个阈值，或往每一份白名单里加上一个地址，并在你的标准演进时让各群组步调一致。
它还让审核策略得以存活在你自己的源代码管理里。把期望的配置保存为代码、通过 API 应用它，那么对你群组治理方式的每一次改动，都会像你基础设施的其余部分一样被评审和版本化——这与去记住你在哪个聊天里切换了哪个设置，相去甚远。
8每个套餐包含什么
分界线很简单。文本垃圾检测在每个套餐上都可用，因此哪怕是免费档，也能把 Telm 的检测当作自己产品里的一个过滤器。完整的能力面——带风险等级的用户筛查、决策日志与分析、设置与规则管理，以及 Webhook——是 Pro 和 Business 套餐的一部分。
每个套餐都有一份每日请求配额，其大小经过设定，让更重的集成落在更重的套餐上：
- **Free** — 每天 100 次 API 请求，仅限垃圾检测。
- **Basic** — 每天 1,000 次 API 请求，仅限垃圾检测。
- **Pro** — 每天 10,000 次 API 请求，外加完整的 API 能力面和 Webhook。
- **Business** — 每天 50,000 次 API 请求，外加完整的 API 能力面和 Webhook。
- 在「设置 → API 与 Webhook」下创建你的密钥，把它们保管在你的密钥保管库里，验证每一个 Webhook 的签名，守护你群组的同一个引擎便成了你自己技术栈的一部分。