Telegram 群组入群申请：搭建可靠的审批队列

可靠的 Telegram 入群审批队列不能只依赖推送事件。系统应定时拉取待处理申请，把返回的申请 id 作为审核所需的成员标识，再明确提交 approve 或 reject。group.join_request webhook 可以让队列更快刷新，但该推送只是尽力而为，因此待处理列表才是事实来源。

关键结论

• Telegram 官方 Bot API 可提供 chat_join_request 更新，但机器人必须是管理员，并拥有 can_invite_users 权限。
• 在 UnifyPort 中，先用 group_id 和 enabled: true 开启审批，再用同一个 group_id 查询待处理队列。
• 批准或拒绝时，要把列表返回项的 id 放进 member_ids。
• group.join_request 只负责低延迟提醒；最终状态必须通过列表接口核对。
• 除非准入规则足够明确且可以审计，否则应保留人工决定环节。

先选清楚账号模型

如果机器人身份符合群组管理方式，Telegram 的官方 Bot API已经定义 ChatJoinRequest、approveChatJoinRequest 和 declineChatJoinRequest。机器人必须是群管理员，并拥有 can_invite_users 管理员权限。对于只处理 Telegram、且本来就由机器人管理的群组，这是直接的选择。

如果审核必须通过现有 Telegram 账号完成，或海外业务团队希望与其他消息平台保持统一接入方式，可以使用已连接的 UnifyPort 消息账号。选型前可先阅读Telegram API ID、API Hash 与 Bot Token 的区别。

不要把三种身份混为一谈：Bot Token 代表机器人；API ID 和 API Hash 标识 Telegram 客户端应用；UnifyPort 消息账号则代表 API 操作所使用的已连接账号。

搭建 Telegram 入群申请审批队列

1. 开启入群审批

只有群组要求审批后，才会出现待处理队列。调用审批模式接口，传入已连接账号 ID、目标 group_id 和布尔值 enabled：

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-approval-mode" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group_example",
    "enabled": true
  }'

该操作要求账号拥有群管理员权限。配置动作应与周期运行的审核任务分开，审核任务不应每次执行都切换群组策略。当前请求结构以设置群组入群审批模式为准。

2. 定时拉取待处理列表

通过查询参数传入 group_id：

curl \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-requests?group_id=group_example" \
  -H "X-Api-Key: <YOUR_API_KEY>"

本地只保存业务真正需要的审核状态，例如申请 ID、目标群组、决定状态、审核人和本地时间。不要假定列表出现某条申请之前，一定已经收到对应 webhook。

字段转换很简单：查询群组入群申请返回项包含 id，更新接口要把这个值作为 member_ids 的元素。不要改用显示名称，也不要自行猜测 Telegram 标识。

3. 明确记录审核决定

建议至少维护四种本地状态：

本地状态	含义	下一步
pending	上游仍存在，尚未审核	展示给审核人员
approved	审核人员同意	提交 approve
rejected	审核人员拒绝	提交 reject
stale	再次核对时已不存在	关闭记录，不再操作

团队可以结合外部收集的问题答案、白名单或人工检查做决定，但要把这些标为自己的业务规则，而不是 Telegram 或 UnifyPort 字段。不要只凭不可信的昵称或个人简介自动放行。

4. 批量批准或拒绝

把一个或多个返回的 ID、目标群组和明确动作一起提交：

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/groups/join-requests/update" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group_example",
    "action": "approve",
    "member_ids": ["member_example", "member_other"]
  }'

拒绝申请时保持相同结构，把动作改成 "reject"。该接口同样要求群管理员权限。设计重试和批处理前，请先核对批准或拒绝入群申请的当前说明。

每次更新后都重新查询列表。这样即使两名审核人员几乎同时操作，本地界面也能回到上游的当前状态。

5. 让 group.join_request 唤醒任务，而不是取代查询

如果希望审核界面快速更新，可以为 webhook 订阅 group.join_request。该事件表示有人申请加入已开启审批的群组，但它是尽力而为的推送。安全流程应是：

1. 接收事件；
2. 验证并确认 webhook；
3. 把相关审核流程加入刷新队列；
4. 调用列表接口；
5. 根据返回的待处理列表展示决定项。

推送负责降低延迟，主动核对负责恢复事实。实现接收端时，可结合Webhook HMAC 重放防护与重试指南处理签名和幂等。

分开处理入群申请与成员变更

入群申请不等于成员已经加入。收到 group.join_request 时，不要立刻把申请人标成群成员。应先执行批准、重新核对，再通过成员变更事件处理后续状态。

这样也能避免审计日志重复：“申请加入”“审核通过”“成员加入”是三件不同的事实。批准后的成员事件可参考Telegram Communities 成员加入与移除事件。

上线检查清单

• 确认已连接账号拥有群管理员权限。
• 只在服务端安全保存 X-Api-Key。
• 把开启审批作为一次管理配置。
• 即使没有 webhook，也要周期查询待处理列表。
• member_ids 只使用列表返回的申请 id。
• 在自有审计日志记录审核人员与决定原因。
• 每次批准或拒绝后重新查询列表。
• 把事件用作刷新提示前，先验证 webhook 签名。
• 不要把入群申请事件当成成员已经变化的证明。

限制与取舍

如果目标身份就是群管理员机器人，而且流程只服务 Telegram，优先考虑官方 Bot API。它有官方文档和专门的批准、拒绝方法。

如果现有账号身份或跨平台一致的 API 模式更重要，可以考虑 UnifyPort 的非官方接口。团队仍需管理员权限、明确的审核规则、安全的 API Key 管理和主动核对机制。接口不会替团队判断谁值得信任；尽力而为的事件投递也意味着查询路径必须保留。

常见问题

Telegram 机器人能批准入群申请吗？

可以。官方 Bot API 提供批准和拒绝方法，但机器人必须是群管理员，并拥有 can_invite_users 权限。

可以只处理 group.join_request webhook 吗？

不建议。它适合做快速通知，收到后仍应查询待处理申请。UnifyPort 文档明确把该推送定义为尽力而为，把主动查询定义为可靠来源。

member_ids 应该填什么？

填写列表接口每个返回项的 id，不要从显示名称推导。

一次调用能批准多个申请吗？

可以。更新接口接受一个或多个 member_ids，action 可以是 approve 或 reject。

批准后还要做什么？

重新查询待处理列表、更新本地队列，并把后续成员变更与原始入群申请分开处理。

下一步

先阅读群组入群申请列表 API Reference，再围绕这个核对循环接入审批模式和更新接口。

来源

核对日期：2026 年 8 月 24 日。

• Telegram Bot API：ChatJoinRequest 与审批方法
• UnifyPort：查询群组入群申请
• UnifyPort：批准或拒绝入群申请
• UnifyPort：设置群组入群审批模式