SDK 文档

服务端 API

群组管理(Web & 小程序)

最近更新时间:2020-08-20 17:46:04

群组综述

即时通信 IM 有多种群组类型,其特点以及限制因素可参考 群组系统。群组使用唯一 ID 标识,通过群组 ID 可以进行不同操作。

群组管理

获取加入的群组列表

需要渲染或刷新【我的群组列表】时,调用该接口获取群组列表,更多详情请参见 Group

注意:

接口返回的群组列表,不包含 TIM.TYPES.GRP_AVCHATROOM(直播群)类型的群组

接口名

tim.getGroupList();

请求参数

参数optionsObject类型,包含的属性值如下表所示:

名称 类型 属性 描述
groupProfileFilter Array<String> <optional> 群资料过滤器。除默认拉取的群资料外,指定需要额外拉取的群资料,支持的值如下:
TIM.TYPES.GRP_PROFILE_OWNER_ID:群主 ID
TIM.TYPES.GRP_PROFILE_CREATE_TIME:群创建时间
TIM.TYPES.GRP_PROFILE_LAST_INFO_TIME:最后一次群资料变更时间
TIM.TYPES.GRP_PROFILE_MEMBER_NUM:群成员数量
TIM.TYPES.GRP_PROFILE_MAX_MEMBER_NUM:最大群成员数量
TIM.TYPES.GRP_PROFILE_JOIN_OPTION:申请加群选项
TIM.TYPES.GRP_PROFILE_INTRODUCTION:群介绍
TIM.TYPES.GRP_PROFILE_NOTIFICATION:群公告
TIM.TYPES.GRP_PROFILE_MUTE_ALL_MBRS (全体禁言设置) v2.6.2起支持

返回值

该接口返回Promise对象:

  • then的回调函数参数为 IMResponse,可在IMResponse.data.groupList中获取群组列表。
  • catch的回调函数参数为 IMError

示例

  • 默认拉取:
    // 该接口默认只拉取这些资料:群类型、群名称、群头像以及最后一条消息的时间。
    let promise = tim.getGroupList();
    promise.then(function(imResponse) {
    console.log(imResponse.data.groupList); // 群组列表
    }).catch(function(imError) {
    console.warn('getGroupList error:', imError); // 获取群组列表失败的相关信息
    });
  • 拉取其他资料:
    // 若默认拉取的字段不满足需求,可以参考下述代码,拉取额外的资料字段。
    let promise = tim.getGroupList({
    groupProfileFilter: [TIM.TYPES.GRP_PROFILE_OWNER_ID],
    });
    promise.then(function(imResponse) {
    console.log(imResponse.data.groupList); // 群组列表
    }).catch(function(imError) {
    console.warn('getGroupList error:', imError); // 获取群组列表失败的相关信息
    });

获取群详细资料

更多详情请参见 Group

接口名

tim.getGroupProfile(options);

请求参数

参数optionsObject类型,包含的属性值如下表所示:

名称 类型 属性 描述
groupID String - 群组 ID
groupCustomFieldFilter Array<String> <optional> 群组的自定义字段过滤器,指定需要获取的群组的自定义字段,详情请参见 自定义字段

返回值

该接口返回Promise对象:

  • then的回调函数参数为 IMResponse,可在IMResponse.data.group中获取群组资料。
  • catch的回调函数参数为 IMError

示例

let promise = tim.getGroupProfile({
  groupID: 'group1',
  groupCustomFieldFilter: ['key1','key2']
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group);
}).catch(function(imError) {
  console.warn('getGroupProfile error:', imError); // 获取群详细资料失败的相关信息
});

创建群组

更多详情请参见 Group

注意:

该接口创建 TIM.TYPES.GRP_AVCHATROOM(直播群) 后,需调用 joinGroup 接口加入群组后,才能进行消息收发流程。

接口名

tim.createGroup(options);

请求参数

参数optionsObject类型,包含的属性值如下表所示:

名称 类型 属性 默认值 描述
name String - - 必填,群组名称,最长30字节
type String <optional> TIM.TYPES.GRP_WORK 群组类型,包括:
  • TIM.TYPES.GRP_WORK:好友工作群,默认
  • TIM.TYPES.GRP_PUBLIC:陌生人社交群
  • TIM.TYPES.GRP_MEETING:临时会议群
  • TIM.TYPES.GRP_AVCHATROOM:直播群
  • groupID String <optional> - 群组 ID。不填该字段时,会自动为群组创建一个唯一的群 ID
    introduction String <optional> - 群简介,最长240字节
    notification String <optional> - 群公告,最长300字节
    avatar String <optional> - 群头像 URL,最长100字节
    maxMemberNum Number <optional> - 最大群成员数量,缺省时的默认值:好友工作群是6000,陌生人社交群是6000,临时会议群是6000,直播群无限制
    joinOption String <optional> TIM.TYPES.JOIN_OPTIONS_FREE_ACCESS 申请加群处理方式。创建好友工作群/临时会议群/直播群时不能填写该字段。好友工作群该字段固定为:禁止申请加群,临时会议群和直播群该字段固定为:自由加入
  • TIM.TYPES.JOIN_OPTIONS_FREE_ACCESS:自由加入
  • TIM.TYPES.JOIN_OPTIONS_NEED_PERMISSION:需要验证
  • TIM.TYPES.JOIN_OPTIONS_DISABLE_APPLY:禁止加群

  • 创建 TIM.TYPES.GRP_WORK, TIM.TYPES.GRP_MEETING, TIM.TYPES.GRP_AVCHATROOM 类型的群组不能填写该字段。好友工作群禁止申请加群,临时会议群和直播群自由加入。
    memberList Array<Object> <optional> - 初始群成员列表,最多500个。创建直播群时不能添加成员。详情请参见下方 memberList 参数说明
    groupCustomField Array<Object> <optional> - 群组维度的自定义字段,默认没有自定义字段,如需开通请参见 群成员资料


    memberList 参数说明

    名称 类型 属性 描述
    userID String - 必填,群成员的 UserID
    role String <optional> 成员身份,可选值只有 Admin,表示添加该成员并设置为管理员
    memberCustomField Array<Object> <optional> 群成员维度的自定义字段,默认没有自定义字段,如需开通请参见 自定义字段

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponse,可在IMResponse.data.group中获取群组资料。
    • catch的回调函数参数为 IMError

    示例

    // 创建好友工作群
    let promise = tim.createGroup({
      type: TIM.TYPES.GRP_WORK,
      name: 'WebSDK',
      memberList: [{userID: 'user1'}, {userID: 'user2'}] // 如果填写了 memberList,则必须填写 userID
    });
    promise.then(function(imResponse) { // 创建成功
      console.log(imResponse.data.group); // 创建的群的资料
    }).catch(function(imError) {
      console.warn('createGroup error:', imError); // 创建群组失败的相关信息
    });

    解散群组

    群主可调用该接口解散群组。

    注意:

    群主不能解散好友工作群。

    接口名

    tim.dismissGroup(groupID);

    请求参数

    名称 类型 描述
    groupID String 群组 ID

    返回值

    该接口返回Promise对象:

    • then 的回调函数参数为 IMResponse,可在IMResponse.data.groupID中获取被解散的群组 ID。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.dismissGroup('group1');
    promise.then(function(imResponse) { // 解散成功
      console.log(imResponse.data.groupID); // 被解散的群组 ID
    }).catch(function(imError) {
      console.warn('dismissGroup error:', imError); // 解散群组失败的相关信息
    });

    更新群组资料

    接口名

    tim.updateGroupProfile(options);

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 属性 Default 描述
    groupID Object - - 群组 ID
    name Object <optional> - 群名称,最长30字节
    avatar Object <optional> - 群头像 URL,最长100字节
    introduction Object <optional> - 群简介,最长240字节
    notification Object <optional> - 群公告,最长300字节
    maxMemberNum Number <optional> - 最大群成员数量,最大为6000
    muteAllMembers Boolean - - 设置全体禁言,true 表示全体禁言,false 表示取消全体禁言,v2.6.2 起支持
    joinOption String <optional> TIM.TYPES.JOIN_OPTIONS_FREE_ACCESS 申请加群处理方式
  • TIM.TYPES.JOIN_OPTIONS_FREE_ACCESS:自由加入
  • TIM.TYPES.JOIN_OPTIONS_NEED_PERMISSION:需要验证
  • TIM.TYPES.JOIN_OPTIONS_DISABLE_APPLY:禁止加群

  • !TIM.TYPES.GRP_WORK, TIM.TYPES.GRP_MEETING, TIM.TYPES.GRP_AVCHATROOM 类型群组的该属性不允许修改。好友工作群禁止申请加群,临时会议群和直播群自由加入。
    groupCustomField Array<Object> <optional> - 群自定义字段,详情请参见下方groupCustomField参数说明
    默认没有自定义字段,如需开通请参见 自定义字段


    groupCustomField参数说明

    名称 类型 描述
    key String 自定义字段的 Key
    value String 自定义字段的 Value

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponse,可在IMResponse.data.group中获取修改后的群组资料。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.updateGroupProfile({
      groupID: 'group1',
      name: 'new name', // 修改群名称
      introduction: 'this is introduction.', // 修改群公告
      // v2.6.0 起,群成员能收到群自定义字段变更的群提示消息,且能获取到相关的内容,详见 Message.payload.newGroupProfile.groupCustomField
      groupCustomField: [{ key: 'group_level', value: 'high'}] // 修改群组维度自定义字段
    });
    promise.then(function(imResponse) {
      console.log(imResponse.data.group) // 修改成功后的群组详细资料
    }).catch(function(imError) {
      console.warn('updateGroupProfile error:', imError); // 修改群组资料失败的相关信息
    });

    申请加群

    申请加群的接口,申请加入某个群组时调用。

    注意:

    • 好友工作群不允许申请加群,只能通过 addGroupMember 方式添加。
    • TIM.TYPES.GRP_AVCHATROOM(直播群)有两种加群方式:
      • 正常加群,即登录加群。此时 SDK 内的所有接口都能正常调用。
      • 匿名加群,即不登录加群。此时只能收消息,其他任何需要鉴权的接口都不能调用。
    • 只有 TIM.TYPES.GRP_AVCHATROOM(直播群) 支持匿名加群,其他类型的群组不支持。
    • 同一用户同时只能加入一个直播群。【例如】用户已在直播群 A 中,再加入直播群 B,SDK 会先退出直播群 A,然后加入直播群 B。

    接口名

    tim.joinGroup(options);

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 属性 描述
    groupID String - -
    applyMessage String - 附言
    type String <optional> 待加入的群组的类型,加入直播群时该字段必填。可选值:
  • TIM.TYPES.GRP_PUBLIC:陌生人社交群
  • TIM.TYPES.GRP_MEETING:临时会议群
  • TIM.TYPES.GRP_AVCHATROOM:直播群
  • 返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data中包括的属性值如下表所示:

      名称 含义
      status 加群的状态。包括:
      • TIM.TYPES.JOIN_STATUS_WAIT_APPROVAL:等待管理员审核
      • TIM.TYPES.JOIN_STATUS_SUCCESS:加群成功
      • TIM.TYPES.JOIN_STATUS_ALREADY_IN_GROUP:已在群中
      group 加群成功后的群组资料
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.joinGroup({ groupID: 'group1', type: TIM.TYPES.GRP_AVCHATROOM });
    promise.then(function(imResponse) {
      switch (imResponse.data.status) {
        case TIM.TYPES.JOIN_STATUS_WAIT_APPROVAL:
          break; // 等待管理员同意
        case TIM.TYPES.JOIN_STATUS_SUCCESS: // 加群成功
          console.log(imResponse.data.group); // 加入的群组资料
          break;
        case TIM.TYPES.JOIN_STATUS_ALREADY_IN_GROUP: // 已经在群中
          break;
        default: break;
      }
    }).catch(function(imError){
      console.warn('joinGroup error:', imError); // 申请加群失败的相关信息
    });

    退出群组

    群主只能退出好友工作群,退出后该好友工作群无群主。

    接口名

    tim.quitGroup(groupID);

    请求参数

    名称 类型 描述
    groupID String 群组 ID

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.groupID为退出的群组 ID。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.quitGroup('group1');
    promise.then(function(imResponse) {
      console.log(imResponse.data.groupID); // 退出成功的群 ID
    }).catch(function(imError){
      console.warn('quitGroup error:', imError); // 退出群组失败的相关信息
    });

    根据群 ID 搜索群组

    通过 groupID 搜索群组。

    注意:TIM.TYPES.GRP_WORK 类型的群组(好友工作群)不能被搜索。

    接口名

    tim.searchGroupByID(groupID);

    请求参数

    名称 类型 描述
    groupID String 群组 ID

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.group为群组资料。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.searchGroupByID('group1');
    promise.then(function(imResponse) {
      const group = imResponse.data.group; // 群组信息
    }).catch(function(imError) {
      console.warn('searchGroupByID error:', imError); // 搜素群组失败的相关信息
    });

    转让群组

    转让群组。只有群主有权限操作。

    注意:只有群主拥有转让的权限。TIM.TYPES.GRP_AVCHATROOM(直播群)类型的群组不能转让。

    接口名

    tim.changeGroupOwner(options);

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 描述
    groupID String 待转让的群组 ID
    newOwnerID String 新群主的 ID

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.group为群组资料。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.changeGroupOwner({
      groupID: 'group1',
      newOwnerID: 'user2'
    });
    promise.then(function(imResponse) { // 转让成功
      console.log(imResponse.data.group); // 群组资料
    }).catch(function(imError) { // 转让失败
      console.warn('changeGroupOwner error:', imError); // 转让群组失败的相关信息
    });

    处理加群申请

    处理申请加群(同意或拒绝)

    注意:

    如果一个群有多位管理员,当有人申请加群时,所有在线的管理员都会收到 申请加群的群系统通知。如果某位管理员处理了这个申请(同意或者拒绝),则其他管理员无法重复处理(即不能修改处理的结果)。

    接口名

    tim.handleGroupApplication(options);

    请求参数

    参数optionsObject类型,包含的属性值如下:

    名称 类型 属性 描述
    handleAction String - 处理结果 Agree(同意) / Reject(拒绝)
    handleMessage String <optional> 附言
    message Message - 申请加群的【群系统通知消息】的消息实例。该实例可通过以下方式获取:
  • 收到新的群系统通知事件 的回调参数中获取
  • 系统类型会话的消息列表中获取
  • 返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.group为群组资料。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.handleGroupApplication({
      handleAction: 'Agree',
      handleMessage: '欢迎欢迎',
      message: message // 申请加群群系统通知的消息实例
    });
    promise.then(function(imResponse) {
      console.log(imResponse.data.group); // 群组资料
    }).catch(function(imError){
      console.warn('handleGroupApplication error:', imError); // 错误信息
    });

    设置群消息提示类型

    接口名

    tim.setMessageRemindType(options);

    请求参数

    参数optionsObject类型,包含的属性值如下:

    名称 类型 描述
    groupID String 群组 ID
    messageRemindType String 群消息提示类型。详细如下:
  • TIM.TYPES.MSG_REMIND_ACPT_AND_NOTE:SDK 接收消息并抛出 收到消息事件 通知接入侧,接入侧做提示
  • TIM.TYPES.MSG_REMIND_ACPT_NOT_NOTE:SDK 接收消息并抛出 收到消息事件 通知接入侧,接入侧不做提示
  • TIM.TYPES.MSG_REMIND_DISCARD:SDK 拒收消息,不会抛出 收到新消息事件
  • 返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.group为群组资料。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.setMessageRemindType({ groupID: 'group1', messageRemindType: TIM.TYPES.MSG_REMIND_DISCARD }); // 拒收消息
    promise.then(function(imResponse) {
      console.log(imResponse.data.group); // 设置后的群资料
    }).catch(function(imError) {
      console.warn('setMessageRemindType error:', imError);
    });

    群成员管理

    获取群成员列表

    注意:

    • 从v2.6.2版本开始,该接口支持拉取群成员禁言截止时间戳(muteUntil),接入侧可根据此值判断群成员是否被禁言,以及禁言的剩余时间。
    • 低于v2.6.2版本时,该接口获取的群成员列表中的资料仅包括头像、昵称等,能够满足群成员列表的渲染需求。如需查询群成员禁言截止时间戳(muteUntil)等详细资料,请使用 getGroupMemberProfile
    • 该接口是分页拉取群成员,不能直接用于获取群的总人数。获取群的总人数(memberNum)请使用 getGroupProfile

    更多详情请参见 GroupMember

    接口名

    tim.getGroupMemberList(options);

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 属性 默认值 描述
    groupID String - - 群组的 ID
    count Number <optional> 15 需要拉取的数量。最大值为100,避免回包过大导致请求失败。若传入超过100,则只拉取前100个
    offset Number <optional> 0 偏移量,默认从0开始拉取

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.memberList为群成员列表,请参考 GroupMember
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.getGroupMemberList({ groupID: 'group1', count: 30, offset:0 }); // 从0开始拉取30个群成员
    promise.then(function(imResponse) {
      console.log(imResponse.data.memberList); // 群成员列表
    }).catch(function(imError) {
      console.warn('getGroupMemberList error:', imError);
    });
    // 从v2.6.2 起,该接口支持拉取群成员禁言截止时间戳。
    let promise = tim.getGroupMemberList({ groupID: 'group1', count: 30, offset:0 }); // 从0开始拉取30个群成员
    promise.then(function(imResponse) {
      console.log(imResponse.data.memberList); // 群成员列表
      for (let groupMember of imResponse.data.memberList) {
        if (groupMember.muteUntil * 1000  > Date.now()) {
          console.log(`${groupMember.userID} 禁言中`);
        } else {
          console.log(`${groupMember.userID} 未被禁言`);
        }
      }
    }).catch(function(imError) {
        console.warn('getGroupMemberProfile error:', imError);
    });

    获取群成员资料

    注意:

    • 使用该接口前,需要将 SDK 版本升级至v2.2.0或以上。
    • 每次查询的用户数上限为50。如果传入的数组长度大于50,则只取前50个用户进行查询,其余丢弃。

    更多详情请参见 GroupMember

    接口名

    tim.getGroupMemberProfile(options);

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 属性 描述
    groupID String - 群组的 ID
    userIDList Array.<String> - 要查询的群成员用户 ID 列表
    memberCustomFieldFilter Array.<String> <optional> 群成员自定义字段筛选。可选,若不填,则默认查询所有群成员自定义字段

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.memberList为查询成功的群成员列表,请参考 GroupMember
    • catch的回调函数参数为 IMError

    添加群成员

    详细规则如下:

    • TIM.TYPES.GRP_WORK 好友工作群:任何群成员都可邀请他人加群,且无需被邀请人同意,直接将其拉入群组中。
    • TIM.TYPES.GRP_PUBLIC 陌生人社交群/ TIM.TYPES.GRP_MEETING 临时会议群:只有 App 管理员可以邀请他人入群,且无需被邀请人同意,直接将其拉入群组中。
    • TIM.TYPES.GRP_AVCHATROOM 直播群:不允许任何人邀请他人入群(包括 App 管理员)。

    更多详情请参见 GroupGroupMember加群方式差异

    接口名

    tim.addGroupMember(options);

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 描述
    groupID String 群组 ID
    userIDList Array<String> 待添加的群成员 ID 数组。单次最多添加300个成员

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data属性值如下表所示:

      名称 类型 含义
      successUserIDList Array<String> 添加成功的 userID 列表
      failureUserIDList Array<String> 添加失败的 userID 列表
      existedUserIDList Array<String> 已在群中的 userID 列表
      group Group 接口调用后的群组资料
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.addGroupMember({
      groupID: 'group1',
      userIDList: ['user1','user2','user3']
    });
    promise.then(function(imResponse) {
      console.log(imResponse.data.successUserIDList); // 添加成功的群成员 userIDList
      console.log(imResponse.data.failureUserIDList); // 添加失败的群成员 userIDList
      console.log(imResponse.data.existedUserIDList); // 已在群中的群成员 userIDList
      console.log(imResponse.data.group); // 添加后的群组信息
    }).catch(function(imError) {
      console.warn('addGroupMember error:', imError); // 错误信息
    });

    删除群成员

    删除群成员。群主可移除群成员。

    接口名

    tim.deleteGroupMember(options)

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 描述
    groupID String 群组 ID
    userIDList Array<String> 待删除的群成员的 ID 列表
    reason String 踢人的原因,可选参数

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.group为更新后的群组资料。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.deleteGroupMember({groupID: 'group1', userIDList:['user1'], reason: '你违规了,我要踢你!'});
    promise.then(function(imResponse) {
      console.log(imResponse.data.group); // 删除后的群组信息
      console.log(imResponse.data.userIDList); // 被删除的群成员的 userID 列表
    }).catch(function(imError) {
      console.warn('deleteGroupMember error:', imError); // 错误信息
    });

    禁言或取消禁言

    设置群成员的禁言时间,可以禁言群成员,也可取消禁言。TIM.TYPES.GRP_WORK 类型的群组(即好友工作群)不能禁言。

    说明:

    只有群主和管理员拥有该操作权限:

    • 群主可以禁言/取消禁言管理员和普通群成员。
    • 管理员可以禁言/取消禁言普通群成员。

    接口名

    tim.setGroupMemberMuteTime(options)

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 描述
    groupID String 群组 ID
    userID String 群成员 ID
    muteTime Number 禁言时长,单位秒
    例如,设置该值为1000,则表示即刻起禁言该用户1000秒,设置为0,则表示取消禁言

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.group是修改后的群资料。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.setGroupMemberMuteTime({
      groupID: 'group1',
      userID: 'user1',
      muteTime: 600 // 禁言10分钟;设为0,则表示取消禁言
    });
    promise.then(function(imResponse) {
      console.log(imResponse.data.group); // 修改后的群资料
      console.log(imResponse.data.member); // 修改后的群成员资料
    }).catch(function(imError) {
      console.warn('setGroupMemberMuteTime error:', imError); // 禁言失败的相关信息
    });

    设为管理员或撤销管理员

    修改群成员角色,只有群主拥有操作权限。

    接口名

    tim.setGroupMemberRole(options)

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 描述
    groupID String 群组 ID
    userID String 群成员 ID
    role String 可选值:TIM.TYPES.GRP_MBR_ROLE_ADMIN(群管理员)或 TIM.TYPES.GRP_MBR_ROLE_MEMBER(群普通成员)

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.group是修改后的群资料。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.setGroupMemberRole({
      groupID: 'group1',
      userID: 'user1',
      role: TIM.TYPES.GRP_MBR_ROLE_ADMIN // 将群 ID: group1 中的用户:user1 设为管理员
    });
    promise.then(function(imResponse) {
      console.log(imResponse.data.group); // 修改后的群资料
      console.log(imResponse.data.member); // 修改后的群成员资料
    }).catch(function(imError) {
      console.warn('setGroupMemberRole error:', imError); // 错误信息
    });

    修改群名片

    设置群成员名片。

    • 群主:可设置所有群成员的名片。
    • 管理员:可设置自身和其他普通群成员的群名片。
    • 普通群成员:只能设置自身群名片。

    接口名

    tim.setGroupMemberNameCard(options)

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 描述
    groupID String 群组 ID
    userID String<optional> 可选,默认修改自身的群名片
    nameCard String -

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.group是修改后的群资料。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.setGroupMemberNameCard({ groupID: 'group1', userID: 'user1', nameCard: '用户名片' });
    promise.then(function(imResponse) {
      console.log(imResponse.data.group); // 设置后的群资料
      console.log(imResponse.data.member); // 修改后的群成员资料
    }).catch(function(imError) {
      console.warn('setGroupMemberNameCard error:', imError); // 设置群成员名片失败的相关信息
    });

    修改自定义字段

    设置群成员自定义字段。

    注意:

    普通群成员只能设置自己的自定义字段。

    接口名

    tim.setGroupMemberCustomField(options)

    请求参数

    参数optionsObject类型,包含的属性值如下表所示:

    名称 类型 描述
    groupID String 群组 ID
    userID String<optional> 群成员 ID,可选,不填则修改自己的群成员自定义字段
    memberCustomField Array<Object> 群成员自定义字段

    memberCustomField包含的属性值如下表所示:

    名称 类型 描述
    key String 自定义字段的 Key
    value String<optional> 自定义字段的 Value

    返回值

    该接口返回Promise对象:

    • then的回调函数参数为 IMResponseIMResponse.data.group是修改后的群资料。
    • catch的回调函数参数为 IMError

    示例

    let promise = tim.setGroupMemberCustomField({ groupID: 'group1', memberCustomField: [{key: 'group_member_test', value: 'test'}]});
    promise.then(function(imResponse) {
      console.log(imResponse.data.group); // 设置后的群资料
      console.log(imResponse.data.member); // 修改后的群成员资料
    }).catch(function(imError) {
      console.warn('setGroupMemberCustomField error:', imError); // 设置群成员自定义字段失败的相关信息
    });

    群提示消息

    当有用户被邀请加入群组或有用户被移出群组等事件发生时,群内会产生提示消息,接入侧可以根据需要展示给群组用户,或者忽略。
    群提示消息有多种类型,详细描述请参见 Message.GroupTipPayload

    名称 类型 描述
    operatorID String 执行该操作的用户 ID
    operationType Number 操作类型
    userIDList Array<String> 相关的 userID 列表
    newGroupProfile Object 若是群资料变更,该字段存放变更的群资料

    群提示消息的 content 结构。系统会在恰当的时机,向全体群成员发出群提示消息。例如:有群成员退群/进群,系统会给所有群成员发对应的群提示消息。

    群系统通知

    当有用户申请加群等事件发生时,管理员会收到申请加群等系统消息。管理员同意或拒绝加群申请,IM SDK 会将相应的消息通过群系统通知消息发送给接入侧,由接入侧展示给用户。
    群系统通知消息有多种类型,详细描述请参见 群系统通知类型常量及含义

    let onGroupSystemNoticeReceived = function(event) {
      const type = event.data.type; // 群系统通知的类型,详情请参见 Message.GroupSystemNoticePayload 
      const message = event.data.message; // 群系统通知的消息实例,详情请参见 Message
      console.log(message.payload); // 消息内容. 群系统通知 payload 结构描述
    };
    tim.on(TIM.EVENT.GROUP_SYSTEM_NOTICE_RECEIVED, onGroupSystemNoticeReceived);
    
    名称 类型 描述
    operatorID String 执行该操作的用户 ID
    operationType Number 操作类型
    groupProfile Object 相关的群组资料
    handleMessage Object 处理的附言
    例如,user1 申请加入进群需要验证的 group1 时,若 user1 填写了申请加群的附言,则 group1 的管理员会在相应群系统通知中看到该字段

    operationType描述

    名称 描述 接收对象
    1 有用户申请加群 群管理员/群主接收
    2 申请加群被同意 申请加群的用户接收
    3 申请加群被拒绝 申请加群的用户接收
    4 被踢出群组 被踢出的用户接收
    5 群组被解散 全体群成员接收
    6 创建群组 创建者接收
    7 邀请加群 被邀请者接收
    8 退群 退群者接收
    9 设置管理员 被设置方接收
    10 取消管理员 被取消方接收
    255 用户自定义通知 默认全员接收

    群系统通知的 content 结构。系统会在恰当的时机,向特定用户发出群系统通知。例如,user1 被踢出群组,系统会给 user1 发送对应的群系统消息。

    目录