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 messaging account。選擇前，建議先讀Telegram API ID、API Hash 與 Bot Token 的差異。

三種身分不可混用：Bot Token 代表機器人；API ID 與 API Hash 識別 Telegram 用戶端應用程式；UnifyPort messaging account 則代表 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
  }'

此操作需要群組管理員權限。應把這項設定與週期執行的審核 worker 分開，worker 不必每次執行都切換群組政策。請以設定群組加入審核模式的現行契約為準。

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 喚醒 worker，而非取代查詢

若希望審核介面快速更新，可以訂閱 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 的 unofficial interface。你仍需要管理員權限、清楚的審核政策、安全的 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：設定群組加入審核模式