入群申请与邀请

用户在客户端申请加入公开群、成员在客户端邀请他人时，如果不能直接入群，会产生一条待处理的入群请求，由群主、管理员或被邀请人处理。本页说明这些流程，以及服务端如何查询一个群的入群请求。

申请、邀请、审批、接受和拒绝都是用户在客户端完成的操作，服务端只能查询，不能代替用户处理。服务端想让某个用户入群时，直接批量添加群成员即可：不需要对方同意，他在本群尚未处理的请求随之失效。

入群流程

申请加入公开群

用户在客户端找到公开群并申请加入，可以附上不超过 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，24 小时内这个群不能再邀请他。用户主动退出一个群后，24 小时内这个群同样不能把他邀请回来。服务端添加成员不受这两项限制。
邀请人可以撤回自己发出的待处理邀请，群主和管理员可以撤回任何人发出的待处理邀请，请求变为 canceled（cancel_cause 为 withdrawn）。

邀请时还会检查：被邀请人不在群黑名单中；群人数和被邀请人加入的群数没有超过上限；应用在运行策略中开启了黑名单拦截（user_blacklist_enabled）时，被邀请人没有把邀请人加入黑名单；开启了“只允许邀请好友”（group_invite_friends_only）时，只能邀请自己的好友。

入群链接

群主和管理员可以在客户端生成入群链接，有效期 1 到 7 天，客户端可以把它展示为二维码。用户打开链接后确认即可直接入群（joined_via 为 link），私有群也可以，不需要审批和确认，不产生请求记录。每个群同时只有一个有效链接，重新生成或撤销后旧链接立即失效；生成链接的人不再是群主或管理员时，链接也随之失效。

处理时的检查

同意申请、通过成员的邀请、接受邀请时会重新检查入群条件：群正常（未封禁、未解散）、用户不在群黑名单中、群人数和用户加入的群数没有超过上限。不满足时操作失败，请求保持待处理，条件满足后（如调高群的人数上限后）可以再次处理。

两位管理员同时处理同一条请求时，后处理的人会被告知这条请求已被处理，不会重复入群。

内容检查与加群前回调

内容安全：申请理由、邀请附言（包括客户端建群时给初始成员的附言）和拒绝申请或邀请的理由，在提交时经过内容安全检查。不通过时操作不生效，客户端收到 403 content_rejected，details.field 为 message 或 reason，见调用方看到的错误；命中替换规则的保存替换后的文字，所以查询到的 message、reason 中可能有 *。
加群前回调：应用开启了加群前回调时，用户在客户端建群时带初始成员、邀请他人、申请加入公开群、通过入群链接加入之前，先请求你的服务端，排在内容检查之后。邀请和建群时被拒绝的人在结果中逐个返回 permission_denied（details.reason 为 app_rejected 或 callback_unavailable，另有 details.app_reason），其他人照常处理，群照常创建；申请加入和通过入群链接加入被拒绝时，整个请求返回 403 permission_denied。群主或管理员同意申请、通过成员的邀请，以及被邀请人接受邀请时不再调用。你的服务端添加群成员不调用加群前回调。

请求的状态与有效期

请求有三种类型 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`

入群申请与邀请 ​

入群流程 ​

申请加入公开群 ​

成员邀请 ​

入群链接 ​

处理时的检查 ​

内容检查与加群前回调 ​

请求的状态与有效期 ​

查询入群申请和邀请 ​

路径参数 ​

查询参数 ​

请求示例 ​

响应 ​

错误 ​

数据结构 ​

入群请求对象 ​