泡泡 IM

外观

发送群邀请 ​

向用户发出需要对方确认的入群邀请。每位用户使用独立的 request_id，方便安全重试。

POST /app/sdk/groups/invitations

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

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

请求参数 ​

JSON Body ​

参数类型必填说明
group_idstring是公开群 ID，1–32 位字母、数字、点、下划线或连字符。
invitationsobject[]是1–499 个邀请对象。列表内 user_id 和 request_id 各自不能重复。
invitations[].user_idstring是被邀请人的外部 user_id，1–64 字符，不含控制字符。
invitations[].request_idstring是本次操作的去重 ID，1–64 位字母、数字、点、下划线、冒号或连字符。同一次操作重试时保持不变。

请求示例 ​

bash
curl 'https://example.com/app/sdk/groups/invitations' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"group_id":"6284173029","invitations":[{"user_id":"linzhou","request_id":"outing-invite-20261018-01"}]}'

使用说明 ​

  • 这里只发出邀请，对方同意之前不是群成员。对方通过处理申请接口确认。
  • skipped.reason：unavailable 用户不可用、already_member 已在群中、already_pending 已有待处理邀请。

返回参数 ​

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

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

data 字段 ​

字段类型说明
event_idstring | null与实时通知对应的事件 ID。没有产生新事件时可为 null；同一事件只处理一次。
created_countinteger本次新建邀请的数量。
invitationsInvitationResult[]每条成功返回的邀请及是否新建。
skippedSkipped[]没有发出邀请的用户及原因。

返回示例 ​

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

展开完整返回示例
json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "event_id": "evt_6874dbb8db144f18b8532dc4c938156c",
    "created_count": 1,
    "invitations": [
      {
        "created": true,
        "item": {
          "notice_id": "3101",
          "type": "group_invitation",
          "direction": "sent",
          "status": "pending",
          "message": "我是行政部陈悦，一起确认秋日海岸出游安排吧。",
          "source": "group_member_picker",
          "created_at": 1792301400000,
          "updated_at": 1792301400000,
          "handled_at": null,
          "actor": {
            "id": "1024",
            "user_id": "chenyue",
            "username": "chenyue",
            "nickname": "陈悦",
            "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
            "signature": "一起发现沿途的风景",
            "profile_updated_at": 1792301400000
          },
          "recipient": {
            "id": "1025",
            "user_id": "linzhou",
            "username": "linzhou",
            "nickname": "林舟",
            "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
            "signature": "把每一次出发安排妥当",
            "profile_updated_at": 1792301400000
          },
          "subject": {
            "id": "1025",
            "user_id": "linzhou",
            "username": "linzhou",
            "nickname": "林舟",
            "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
            "signature": "把每一次出发安排妥当",
            "profile_updated_at": 1792301400000
          },
          "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
          },
          "permissions": {
            "accept": true,
            "reject": true
          }
        }
      }
    ],
    "skipped": []
  }
}

返回对象字段 ​

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

逐个邀请的结果 · 申请或邀请 · 用户资料 · 群资料 · 申请处理权限 · 未处理的用户

逐个邀请的结果（InvitationResult） ​

字段类型说明
createdboolean是否新建此邀请；已存在或重试时可能为 false。
itemNotice对应的群邀请。

申请或邀请（Notice） ​

字段类型说明
notice_idstring申请 ID；读取时为十进制字符串，提交处理请求时使用正整数。
typestringfriend_request 好友申请、group_join_request 入群申请、group_invitation 群邀请。
directionstringreceived 表示收到的申请，sent 表示本人发出的申请。
statusstringpending 待处理、accepted 已同意、rejected 已拒绝、expired 已过期、revoked 已撤销。
messagestring申请说明；可能为空字符串。
sourcestring申请来源，例如 search、profile、qr；由具体业务产生。
created_atinteger申请创建时间，Unix 毫秒时间戳。
updated_atinteger申请最后更新时间，Unix 毫秒时间戳。
handled_atinteger | null申请处理时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
actorUser发起人资料。
recipientUser接收人资料。
subjectUser | null群邀请中被邀请人的资料；其他申请通常为 null。
groupGroup | null关联群资料；好友申请为 null。
permissionsNoticePermissions当前账号能否同意或拒绝。

用户资料（User） ​

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

群资料（Group） ​

字段类型说明
group_idstring公开群 ID，群相关请求使用这个值。
owner_idstring群主的外部 user_id。
namestring群名称。
avatarstring群头像地址。
avatar_customboolean是否由用户上传头像；false 表示服务器生成的组合头像。
announcementstring | null群公告正文；没有公告时为 null。
announcement_author_idstring | null最近一次公告发布者的外部 user_id；没有公告时可为 null。
announcement_author_namestring | null公告发布者的显示名；没有公告时可为 null。
announcement_updated_atinteger公告更新时间；尚未设置时为 0，Unix 毫秒时间戳。
statusstring群状态：active 正常、disabled 停用、dissolved 已解散。
all_mutedboolean是否开启全员禁言。
join_approval_requiredboolean扫码加入是否需要群主或管理员审批。
member_countinteger当前成员人数。
unread_modestring未读计算方式：fanout 按成员累计；sequence 按消息序号计算。客户端使用返回的未读数即可。
last_midstring最新消息 ID；还没有消息时为 "0"。
last_seqstring最新消息在群内的序号；没有消息时为 "0"。
last_message_atinteger最近一条消息的发送时间；没有消息时为 0，Unix 毫秒时间戳。
conversation_updated_atinteger群会话内容最后更新时间，Unix 毫秒时间戳。
created_atinteger建群时间，Unix 毫秒时间戳。
updated_atinteger群资料最后更新时间，Unix 毫秒时间戳。

申请处理权限（NoticePermissions） ​

字段类型说明
acceptboolean当前账号是否可以同意此申请。
rejectboolean当前账号是否可以拒绝此申请。

未处理的用户（Skipped） ​

字段类型说明
user_idstring未处理的外部用户 ID。
reasonstring未处理原因，具体取值见本页操作说明。

错误处理 ​

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

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

Copyright © 泡泡 IM