通过邀请加入群

通过群邀请提交加入操作。无需审批时直接入群；需要审批时只提交入群申请。

POST /app/sdk/groups/invite-join

调用方： SDK 客户端　·　认证： IM Token

请求头：Authorization: Bearer <IM Token>。先通过宿主后端获取 Token，再交给 SDK 使用。

请求参数

JSON Body

参数	类型	必填	说明
`token`	string	是	群邀请接口返回的 token，32–2048 字符，原样提交。不要把完整 popoim:// 二维码内容当作 token。
`request_id`	string	是	本次操作的去重 ID，1–64 位字母、数字、点、下划线、冒号或连字符。同一次操作重试时保持不变。

请求示例

bash

curl 'https://example.com/app/sdk/groups/invite-join' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"token":"<群邀请接口返回的 token>","request_id":"outing-20261018-01"}'

使用说明

membership_status=pending 表示申请已经提交，仍要等待审批；此时不返回 group、membership、permissions、members_preview。
membership_status=active 时返回完整群详情，可以进入群聊。重试时保持 request_id 不变。

返回参数

成功响应的最外层字段如下。下面所有业务字段都位于 data 中。

字段	类型	说明
`code`	integer	0 表示成功；非 0 时查看 msg，不把 data 当成功结果使用。
`msg`	string	成功通常为 ok，失败时为错误说明。
`data`	object	本次请求的业务结果，字段见下表。

data 字段

字段	类型	说明
`changed`	boolean	本次操作是否实际改变了服务器数据；设置值原本相同时为 false。
`event_id`	string \| null	与实时通知对应的事件 ID。没有产生新事件时可为 null；同一事件只处理一次。
`invite_group`	InviteGroup	供加入前预览的群信息。
`membership_status`	string	active 已是成员、pending 入群申请待审批、not_member 尚未入群。
`join_mode`	string	direct 可直接入群；approval 需要群主或管理员审批。
`can_join`	boolean	当前是否可以提交加入操作；已是成员或已有待审批申请时为 false。
`group`	Group	仅 membership_status=active、已经是群成员时返回。群资料。
`membership`	Membership	仅 membership_status=active、已经是群成员时返回。本人的群状态。
`permissions`	GroupPermissions	仅 membership_status=active、已经是群成员时返回。本人当前可执行的群操作。
`members_preview`	MembersPreview	仅 membership_status=active、已经是群成员时返回。最多 15 位群成员的预览。

返回示例

示例展示字段结构；ID、时间和资料仅作说明，请使用实际回包。

展开完整返回示例

json

{
  "code": 0,
  "msg": "ok",
  "data": {
    "changed": true,
    "event_id": "evt_6874dbb8db144f18b8532dc4c938156c",
    "invite_group": {
      "conversation_id": "group_6284173029",
      "group_id": "6284173029",
      "name": "秋日海岸出游",
      "avatar": "https://example.com/uploads/avatars/group/6284173029/1792301400.webp",
      "member_count": 2
    },
    "membership_status": "active",
    "join_mode": "direct",
    "can_join": false,
    "group": {
      "group_id": "6284173029",
      "owner_id": "chenyue",
      "name": "秋日海岸出游",
      "avatar": "https://example.com/uploads/avatars/group/6284173029/1792301400.webp",
      "avatar_custom": false,
      "announcement": "周六 8:30 公司楼下集合，请带好防晒用品。",
      "announcement_author_id": "chenyue",
      "announcement_author_name": "陈悦",
      "announcement_updated_at": 1792301400000,
      "status": "active",
      "all_muted": false,
      "join_approval_required": false,
      "member_count": 2,
      "unread_mode": "fanout",
      "last_mid": "0",
      "last_seq": "0",
      "last_message_at": 0,
      "conversation_updated_at": 1792301400000,
      "created_at": 1792301400000,
      "updated_at": 1792301400000
    },
    "membership": {
      "conversation_id": "group_6284173029",
      "status": "active",
      "role": "owner",
      "remark": "",
      "conversation_state": "hidden",
      "pinnable": false,
      "pinned": false,
      "muted": false,
      "announcement_unread": false,
      "send_forbidden_until": 0,
      "joined_at": 1792301400000,
      "updated_at": 1792301400000
    },
    "permissions": {
      "send_message": true,
      "rename_group": true,
      "edit_announcement": true,
      "edit_remark": true,
      "add_member": true,
      "remove_member": true,
      "manage_admins": true,
      "manage_mute": true,
      "manage_join_approval": true,
      "share_group": true,
      "dissolve_group": true,
      "leave_group": false
    },
    "members_preview": {
      "items": [
        {
          "user": {
            "id": "1024",
            "user_id": "chenyue",
            "username": "chenyue",
            "nickname": "陈悦",
            "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
            "signature": "一起发现沿途的风景",
            "profile_updated_at": 1792301400000
          },
          "presence": {
            "online": true,
            "online_updated_at": 1792301400000
          },
          "display_name": "陈悦",
          "role": "owner",
          "send_forbidden_until": 0,
          "joined_at": 1792301400000,
          "updated_at": 1792301400000
        },
        {
          "user": {
            "id": "1025",
            "user_id": "linzhou",
            "username": "linzhou",
            "nickname": "林舟",
            "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
            "signature": "把每一次出发安排妥当",
            "profile_updated_at": 1792301400000
          },
          "presence": {
            "online": true,
            "online_updated_at": 1792301400000
          },
          "display_name": "林舟",
          "role": "member",
          "send_forbidden_until": 0,
          "joined_at": 1792301400000,
          "updated_at": 1792301400000
        }
      ],
      "has_more": false
    }
  }
}

返回对象字段

数组中的每个对象使用同一套字段。点击名称跳到说明：

邀请中可见的群信息 · 群资料 · 本人的群成员状态 · 本人的群操作权限 · 群成员预览 · 群成员 · 用户资料 · 在线状态

邀请中可见的群信息（InviteGroup）

字段	类型	说明
`conversation_id`	string	群会话 ID。
`group_id`	string	公开群 ID。
`name`	string	群名称。
`avatar`	string	群头像地址。
`member_count`	integer	群成员人数。

群资料（Group）

字段	类型	说明
`group_id`	string	公开群 ID，群相关请求使用这个值。
`owner_id`	string	群主的外部 user_id。
`name`	string	群名称。
`avatar`	string	群头像地址。
`avatar_custom`	boolean	是否由用户上传头像；false 表示服务器生成的组合头像。
`announcement`	string \| null	群公告正文；没有公告时为 null。
`announcement_author_id`	string \| null	最近一次公告发布者的外部 user_id；没有公告时可为 null。
`announcement_author_name`	string \| null	公告发布者的显示名；没有公告时可为 null。
`announcement_updated_at`	integer	公告更新时间；尚未设置时为 0，Unix 毫秒时间戳。
`status`	string	群状态：active 正常、disabled 停用、dissolved 已解散。
`all_muted`	boolean	是否开启全员禁言。
`join_approval_required`	boolean	扫码加入是否需要群主或管理员审批。
`member_count`	integer	当前成员人数。
`unread_mode`	string	未读计算方式：fanout 按成员累计；sequence 按消息序号计算。客户端使用返回的未读数即可。
`last_mid`	string	最新消息 ID；还没有消息时为 "0"。
`last_seq`	string	最新消息在群内的序号；没有消息时为 "0"。
`last_message_at`	integer	最近一条消息的发送时间；没有消息时为 0，Unix 毫秒时间戳。
`conversation_updated_at`	integer	群会话内容最后更新时间，Unix 毫秒时间戳。
`created_at`	integer	建群时间，Unix 毫秒时间戳。
`updated_at`	integer	群资料最后更新时间，Unix 毫秒时间戳。

本人的群成员状态（Membership）

字段	类型	说明
`conversation_id`	string	该群的会话 ID。
`status`	string	active 仍在群中、left 已退出、removed 已被移出、dissolved 群已解散。
`role`	string	owner 群主、admin 管理员、member 普通成员。
`remark`	string	本人设置的群备注；未设置时为空字符串。
`conversation_state`	string	chatting 显示在会话列表，hidden 隐藏。
`pinnable`	boolean	当前是否可以置顶；没有消息时通常为 false。
`pinned`	boolean	本人是否置顶。
`muted`	boolean	本人是否开启免打扰。
`announcement_unread`	boolean	本人是否有未读群公告。
`send_forbidden_until`	integer	本人单独禁言到期时间；0 表示没有单独禁言，Unix 毫秒时间戳。
`joined_at`	integer	本人入群时间，Unix 毫秒时间戳。
`updated_at`	integer	本人成员状态最后更新时间，Unix 毫秒时间戳。

本人的群操作权限（GroupPermissions）

字段	类型	说明
`send_message`	boolean	本人当前是否可以发送消息。界面可据此显示操作入口，服务器仍会再次检查权限。
`rename_group`	boolean	本人当前是否可以修改群名。界面可据此显示操作入口，服务器仍会再次检查权限。
`edit_announcement`	boolean	本人当前是否可以编辑群公告。界面可据此显示操作入口，服务器仍会再次检查权限。
`edit_remark`	boolean	本人当前是否可以修改个人群备注。界面可据此显示操作入口，服务器仍会再次检查权限。
`add_member`	boolean	本人当前是否可以添加成员。界面可据此显示操作入口，服务器仍会再次检查权限。
`remove_member`	boolean	本人当前是否可以移出成员。界面可据此显示操作入口，服务器仍会再次检查权限。
`manage_admins`	boolean	本人当前是否可以设置或取消管理员。界面可据此显示操作入口，服务器仍会再次检查权限。
`manage_mute`	boolean	本人当前是否可以设置全员或成员禁言。界面可据此显示操作入口，服务器仍会再次检查权限。
`manage_join_approval`	boolean	本人当前是否可以修改入群审批设置。界面可据此显示操作入口，服务器仍会再次检查权限。
`share_group`	boolean	本人当前是否可以分享群二维码。界面可据此显示操作入口，服务器仍会再次检查权限。
`dissolve_group`	boolean	本人当前是否可以解散群。界面可据此显示操作入口，服务器仍会再次检查权限。
`leave_group`	boolean	本人当前是否可以退出群。界面可据此显示操作入口，服务器仍会再次检查权限。

群成员预览（MembersPreview）

字段	类型	说明
`items`	GroupMember[]	最多 15 位成员；完整列表使用群成员接口。
`has_more`	boolean	是否还有未包含在预览中的成员。

群成员（GroupMember）

字段	类型	说明
`user`	User	成员资料。
`presence`	Presence \| null	成员在线状态；没有状态时为 null。
`display_name`	string	成员显示名。
`role`	string	owner 群主、admin 管理员、member 普通成员。
`send_forbidden_until`	integer	单独禁言到期时间；0 表示未单独禁言，Unix 毫秒时间戳。
`joined_at`	integer	入群时间，Unix 毫秒时间戳。
`updated_at`	integer	成员资料或成员状态的最后更新时间，Unix 毫秒时间戳。

用户资料（User）

字段	类型	说明
`id`	string	IM 内部用户 ID，以十进制字符串返回。调用用户相关接口时使用下面的 user_id。
`user_id`	string	宿主系统提供的用户 ID，例如 chenyue；用于识别同一个人。
`username`	string \| null	可用于精确搜索的账号；没有设置时为 null。
`nickname`	string	显示昵称。
`avatar`	string	头像地址。
`signature`	string	个性签名；未设置时为空字符串。
`profile_updated_at`	integer	公开资料最后更新时间，Unix 毫秒时间戳。

在线状态（Presence）

字段	类型	说明
`online`	boolean	当前是否在线。
`online_updated_at`	integer	在线状态最后更新时间，Unix 毫秒时间戳。

错误处理

先检查 HTTP 状态，再检查 code。业务失败可能仍为 HTTP 200；非 0 的 code 都不能当成功。完整错误码见请求约定。

返回群与成员接口列表 · HTTP 请求约定

用户预置与 Token

首页与会话

消息

上传与下载

用户、好友与申请

群与成员

搜索

音视频通话

随附宿主账号

设备与推送

举报与诊断

通过邀请加入群

请求参数

JSON Body

请求示例

使用说明

返回参数

data 字段

返回示例

返回对象字段

邀请中可见的群信息（InviteGroup）

群资料（Group）

本人的群成员状态（Membership）

本人的群操作权限（GroupPermissions）

群成员预览（MembersPreview）

群成员（GroupMember）

用户资料（User）

在线状态（Presence）

错误处理

通过邀请加入群 ​

请求参数 ​

JSON Body ​

请求示例 ​

使用说明 ​

返回参数 ​

data 字段 ​

返回示例 ​

返回对象字段 ​

邀请中可见的群信息（InviteGroup） ​

群资料（Group） ​

本人的群成员状态（Membership） ​

本人的群操作权限（GroupPermissions） ​

群成员预览（MembersPreview） ​

群成员（GroupMember） ​

用户资料（User） ​

在线状态（Presence） ​

错误处理 ​

通过邀请加入群

请求参数

JSON Body

请求示例

使用说明

返回参数

data 字段

返回示例

返回对象字段

邀请中可见的群信息（InviteGroup）

群资料（Group）

本人的群成员状态（Membership）

本人的群操作权限（GroupPermissions）

群成员预览（MembersPreview）

群成员（GroupMember）

用户资料（User）

在线状态（Presence）

错误处理