入群申請與邀請

使用者在客戶端申請加入公開群、成員邀請他人時，如果不能直接入群，會產生一條待處理的入群請求，由群主、管理員或被邀請人處理。

申請、邀請、審批、接受和拒絕都只能由使用者在客戶端操作，你的服務端只能查詢：

你想要	做法
在後臺檢視一個群的申請和邀請	查詢入群申請和邀請
直接讓某人入群	批次新增群成員，不需要對方同意，他在本群沒處理的請求隨之失效
由你的服務端決定能不能入群	加群前回撥，見內容檢查與加群前回撥
改變要不要審批	群設定 `member_invite`、`join_mode`，見群設定；被邀請時要不要本人確認見使用者的入群設定

三種入群方式的流程一覽：

方式	誰發起	什麼時候直接入群	否則產生的請求	誰處理
申請加入公開群	使用者本人	群的 `join_mode` 為 `free`	`application`	群主或管理員
成員邀請	群成員	邀請人有權直接邀請，且被邀請人的入群設定為 `allow_any`	`invite_review`（需審批的普通成員邀請）、`invitation`（等被邀請人確認）	群主或管理員；被邀請人
入群連結	群主或管理員生成，使用者開啟	總是直接入群	無	—

入群流程

申請加入公開群

使用者在客戶端找到公開群並申請加入，可以附上不超過 256 個字元的申請理由。私有群不能申請。
群的申請方式 join_mode 為 free 時，使用者直接入群（joined_via 為 apply），不產生請求記錄；為 approval 時產生一條 application 請求，群主和全部管理員的線上裝置實時收到通知。
任意一位群主或管理員同意後，申請人入群，請求變為 accepted；拒絕時可以附上理由，請求變為 declined，申請人收到通知，24 小時內不能再次申請這個群。
申請人可以撤回自己待處理的申請，請求變為 canceled（cancel_cause 為 withdrawn）。

同一個使用者對同一個群的申請按每天 5 次限流。

成員邀請

成員在客戶端一次可以邀請最多 100 人，可以附上邀請附言。誰能邀請由群設定 member_invite 決定：群主和管理員可以隨時邀請；普通成員在 free 時可以直接邀請，在 approval 時邀請要先經群主或管理員審批，在 disabled 時不能邀請。

普通成員在需要審批的群裡邀請時，產生一條 invite_review 請求，等待群主或管理員審批；審批透過後（請求變為 accepted）按下一步處理被邀請人，拒絕時請求變為 declined。
被邀請人的入群設定為 allow_any 時，他直接入群（joined_via 為 invite），不產生請求記錄；為 need_confirm 時產生一條 invitation 請求，被邀請人的線上裝置實時收到通知。
被邀請人接受後入群，請求變為 accepted；拒絕時請求變為 declined。
邀請人可以撤回自己發出的待處理邀請，群主和管理員可以撤回任何人發出的，請求變為 canceled（cancel_cause 為 withdrawn）。

邀請冷卻：應用策略 group_invite_cooldown_enabled 預設關閉，退群或拒絕邀請後可以立即再邀請。在控制檯“應用策略 → 群組”中開啟後，24 小時內同一個群不能再邀請這個使用者。

關閉冷卻時，本人確認、管理員審批等規則照常；
入群申請被拒絕後的 24 小時冷卻不受這個開關影響；
服務端新增成員不受邀請冷卻限制。

邀請時還會檢查：

被邀請人不在群黑名單中；
群人數和被邀請人加入的群數沒超上限；
開啟黑名單攔截（執行策略的 user_blacklist_enabled）時，被邀請人沒有把邀請人加入黑名單；
開啟“只允許邀請好友”（group_invite_friends_only）時，只能邀請自己的好友。

入群連結

群主和管理員可以在客戶端生成入群連結，有效期 1 到 7 天，客戶端可以把它展示為二維碼。使用者開啟連結後確認即可直接入群（joined_via 為 link），私有群也可以，不需要審批和確認，不產生請求記錄。每個群同時只有一個有效連結，重新生成或撤銷後舊連結立即失效；生成連結的人不再是群主或管理員時，連結也隨之失效。

處理時的檢查

同意申請、透過成員的邀請、接受邀請時會重新檢查入群條件：群正常（未封禁、未解散）、使用者不在群黑名單中、群人數和使用者加入的群數沒超上限。不滿足時操作失敗、請求保持待處理，條件滿足後（如調高了人數上限）可以再處理。

兩位管理員同時處理同一條請求時，後處理的人會被告知這條請求已被處理，不會重複入群。

內容檢查與加群前回撥

內容安全：申請理由、邀請附言（包括客戶端建群時給初始成員的附言）、拒絕理由在提交時經過內容安全檢查。

不透過時操作不生效，客戶端收到 403 content_rejected，details.field 為 message 或 reason，見呼叫方看到的錯誤。
命中替換規則的儲存替換後的文字，查到的 message、reason 中可能有 *。

加群前回撥：開啟加群前回撥後，以下操作之前先請求你的服務端（排在內容檢查之後）。你的服務端新增群成員不呼叫。

客戶端操作	被拒絕時
建群時帶初始成員、邀請他人	被拒的人在結果中逐個返回 `permission_denied`，其他人照常處理，群照常建立
申請加入公開群、透過入群連結加入	整個請求返回 `403 permission_denied`
同意申請、透過成員的邀請、接受邀請	不呼叫

details.reason 為 app_rejected（你的服務端拒絕）或 callback_unavailable（回撥失敗後按“拒絕”策略處理），另有 details.app_reason。

請求的狀態與有效期

請求有三種型別 kind：

`kind`	說明	由誰處理
`application`	使用者申請加入公開群	群主或管理員
`invite_review`	普通成員在需要審批的群裡發出的邀請	群主或管理員
`invitation`	等待被邀請人確認的邀請	被邀請人

同一個群對同一個使用者的同一類請求只有一條記錄。重複發起（如再次申請、再次邀請）時更新原來的記錄：重新變為待處理，requested_at 更新為最近一次發起的時間，上一次的處理結果被清空。

待處理的請求在最近一次發起後 7 天未處理即過期。請求記錄在發起 30 天後刪除，群解散後隨成員一起刪除。

請求的狀態 status：

`status`	說明
`pending`	待處理
`accepted`	已同意：申請被透過、邀請被接受，或成員的邀請審批透過
`declined`	已拒絕，`reason` 為拒絕理由
`canceled`	已失效，`cancel_cause` 說明原因
`expired`	7 天內未處理，已過期

失效的原因 cancel_cause：

`cancel_cause`	說明
`withdrawn`	被撤回：申請人撤回申請，或邀請人、群主、管理員撤回邀請
`joined`	使用者已透過其他途徑加入了這個群（如被服務端新增、被別人邀請）
`blacklisted`	使用者被加入了群黑名單
`group_private`	公開群改為了私有群，此前的申請全部失效，之後改回公開群也不會恢復（僅 `application`）
`not_eligible`	審批成員的邀請時，被邀請人已不能接收這個群的邀請（僅 `invite_review`）
`dismissed`	群已解散

群被封禁期間，待處理的請求暫停：查詢時顯示為 canceled、cancel_cause 為 null，不能被處理；解封后尚未過期的請求恢復為 pending。

查詢入群申請和邀請

按發起時間從新到舊分頁返回一個群的入群請求，包括全部三種型別，可以按型別和狀態篩選。

請求的狀態在查詢時按當前情況計算（如已過期、群已被封禁），所以一頁的條數可能少於 limit，是否還有下一頁以 next_cursor 為準。

GET/{org_name}/{app_name}/groups/{group_id}/requests

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`group_id`	String	群 ID

查詢引數

引數	型別	必填	說明
`kind`	String	否	只列出這種型別的請求：`application`、`invite_review` 或 `invitation`
`status`	String	否	只列出這種狀態的請求：`pending`、`accepted`、`declined`、`canceled` 或 `expired`
`limit`	Number	否	每頁條數，預設 20，取值 1 到 100
`cursor`	String	否	下一頁的遊標，見分頁

請求示例

bash

curl -X GET "$IM_API/$ORG/$APP/groups/99582688326844416/requests?limit=3" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，items 中每項為一個入群請求物件，next_cursor 為下一頁的遊標，沒有下一頁時為 null。

json

{
  "items": [
    {
      "group_id": "99582688326844416",
      "kind": "invitation",
      "username": "chener",
      "nickname": "陈二",
      "avatar_url": "https://cdn.example.com/avatar/chener.png",
      "inviter": {
        "username": "lisi",
        "nickname": "李四",
        "avatar_url": "https://cdn.example.com/avatar/lisi.png"
      },
      "message": "周末一起去拍日出",
      "reason": "",
      "status": "pending",
      "cancel_cause": null,
      "requested_at": "2026-10-02T19:10:58.660Z",
      "expires_at": "2026-10-09T19:10:58.660Z",
      "handled_at": null,
      "handled_by": null
    },
    {
      "group_id": "99582688326844416",
      "kind": "application",
      "username": "qianyi",
      "nickname": "钱一",
      "avatar_url": "https://cdn.example.com/avatar/qianyi.png",
      "inviter": null,
      "message": "喜欢拍风光",
      "reason": "",
      "status": "pending",
      "cancel_cause": null,
      "requested_at": "2026-10-02T19:10:58.496Z",
      "expires_at": "2026-10-09T19:10:58.496Z",
      "handled_at": null,
      "handled_by": null
    },
    {
      "group_id": "99582688326844416",
      "kind": "invitation",
      "username": "sunqi",
      "nickname": "孙七",
      "avatar_url": "https://cdn.example.com/avatar/sunqi.png",
      "inviter": {
        "username": "lisi",
        "nickname": "李四",
        "avatar_url": "https://cdn.example.com/avatar/lisi.png"
      },
      "message": "欢迎加入",
      "reason": "",
      "status": "accepted",
      "cancel_cause": null,
      "requested_at": "2026-10-02T19:10:46.831Z",
      "expires_at": null,
      "handled_at": "2026-10-02T19:10:46.913Z",
      "handled_by": "sunqi"
    }
  ],
  "next_cursor": "U7pn0kDw8E-YL7NKq_kENEd90r-JeBiz-xsQjenN4Dv_-H8IWD2XbO4kuGJmYuLlerJn-EImW29ht1_vqRfziguogEpszO1CEQrNOjcFsnHultBR7C4nPUPR2XYdu9DaZqeckq6rFTZESsRe2wv5koZrktk6m0rXVuMbRQ"
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`kind`、`status` 的取值不合法，或 `limit` 超出範圍
404	`not_found`	群不存在

資料結構

入群請求物件

欄位	型別	說明
`group_id`	String	群 ID
`kind`	String	請求型別：`application`、`invite_review` 或 `invitation`，見請求的狀態與有效期
`username`	String	請求的目標使用者：申請人或被邀請人
`nickname`	String	目標使用者的暱稱，沒有時為空字串
`avatar_url`	String	目標使用者的頭像地址，沒有時為空字串
`inviter`	Object	邀請人，包含 `username`、`nickname`、`avatar_url`；`application` 或邀請人已被刪除時為 `null`
`message`	String	申請理由或邀請附言，沒有時為空字串。命中內容安全替換規則的為替換後的文字
`reason`	String	拒絕理由，沒有時為空字串。命中內容安全替換規則的為替換後的文字
`status`	String	狀態：`pending`、`accepted`、`declined`、`canceled` 或 `expired`
`cancel_cause`	String	失效的原因，只在 `status` 為 `canceled` 時可能有值，其他情況為 `null`
`requested_at`	String	最近一次發起的時間
`expires_at`	String	過期時間，只在 `status` 為 `pending` 時有值，其他情況為 `null`
`handled_at`	String	處理時間；尚未處理時為 `null`
`handled_by`	String	處理人的使用者名稱：同意或拒絕的群主、管理員，接受或拒絕邀請的被邀請人，撤回的人；自動失效、或處理人已被刪除時為 `null`

入群申請與邀請 ​

入群流程 ​

申請加入公開群 ​

成員邀請 ​

入群連結 ​

處理時的檢查 ​

內容檢查與加群前回撥 ​

請求的狀態與有效期 ​

查詢入群申請和邀請 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

資料結構 ​

入群請求物件 ​