Telegram 群組加入申請：建立可靠審批隊列

可靠的 Telegram 群組審批隊列不應只依賴推送事件。系統要定期列出待處理申請，把每項回傳資料的 id 當作審批用的成員識別碼，再明確提交 approve 或 reject。group.join_request webhook 可以令畫面更快更新，但這個訊號只屬盡力傳送，所以查詢結果才是事實來源。

重點

• Telegram 官方 Bot API 可提供 chat_join_request 更新，但 bot 必須是管理員，並具備 can_invite_users 權限。
• 在 UnifyPort，以 group_id 和 enabled: true 開啟審批，再用相同 group_id 查詢待處理隊列。
• 批准或拒絕時，把清單回傳項目的 id 放入 member_ids。
• group.join_request 只作低延遲提示；最後狀態要靠清單端點核對。
• 除非加入規則清楚而且可以稽核，否則應保留人手決定。

寫程式前先選擇身份模型

如果群組適合由 bot 管理，Telegram 的官方 Bot API已定義 ChatJoinRequest、approveChatJoinRequest 及 declineChatJoinRequest。Bot 必須是群組管理員，並擁有 can_invite_users 管理權限。對只處理 Telegram 的流程，這是直接的方案。

如果審批必須透過現有 Telegram 帳戶執行，或者跨境團隊希望與其他訊息平台使用一致的整合方式，可以使用已連接的 UnifyPort messaging account。選擇前可先閱讀Telegram API ID、API Hash 與 Bot Token 的分別。

三種身份不應混淆：Bot Token 代表 bot；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. 定期查詢待處理清單

透過 query parameter 傳入 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 簽署。
• 不把加入申請事件當作成員已變更的證明。

限制與取捨

如果預期身份就是群組管理員 bot，而且流程只處理 Telegram，官方 Bot API 通常更適合。它有官方文件及專用批准、拒絕方法。

如果現有帳戶身份或跨平台一致 API 模式更重要，可考慮 UnifyPort 的 unofficial interface。你仍需要管理員權限、清楚的審批政策、安全的 API Key 管理及主動核對。介面不會替團隊判斷誰值得信任；事件採盡力傳送，也表示查詢路徑不可移除。

常見問題

Telegram bot 可以批准群組加入申請嗎？

可以。官方 Bot API 提供批准及拒絕方法，但 bot 必須是管理員，並具備 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：設定群組加入審批模式