群组功能-Linux开发集成-SDK开发集成-IM即时通讯-网易云信开发文档

群组功能

群组功能概述

群组功能对应的API为 nim_team_xxx,提供了普通群 (Normal) 以及高级群 (Advanced) 两种形式的群聊功能。高级群拥有更多的权限操作，两种群聊形式在共有操作上保持了接口一致。推荐 APP 开发时只选择一种群类型进行开发。普通群和高级群在原则上是不能互相转换的，他们的群类型在创建时就已经确定。目前版本中，高级群覆盖普通群的全部功能，推荐使用高级群进行开发。

普通群

开发手册中所提及的普通群都等同于DEMO中的讨论组。普通群(讨论组)没有权限操作，适用于快速创建多人会话的场景。每个普通群只有一个管理员。管理员可以对群进行增减员操作，普通成员只能对群进行增员操作。在添加新成员的时候，并不需要经过对方同意。

高级群

高级群在权限上有更多的限制，权限分为群主、管理员、以及群成员。在添加成员的时候需要对方接受邀请。高级群的群成员资料提供了实时同步功能，并提供了群开关设置字段、第三方扩展字段（仅负责存储和透传）和第三方服务器扩展字段（该配置项只能通过服务器接口设置，对客户端只读）。

群操作权限对比

群操作	普通群	高级群
邀请成员	任何人	群主、管理员
踢出成员	群主	群主、管理员(管理员之间无法互相踢)
解散群	群主	群主
退群	任何人	管理员、普通成员
处理入群申请	/	群主、管理员
更改自己的群昵称	/	任何人
更改他人群昵称	/	群主、管理员
更改群名称	任何人	群主、管理员
更改群公告	/	群主、管理员
更改群介绍	/	群主、管理员
更新验证方式	/	群主、管理员
添加(删除)管理员	/	群主
移交群主	/	群主
成员禁言	/	群主、管理员
更新群头像	/	群主、管理员

NIMTeamType枚举说明

枚举	值	说明
kNIMTeamTypeNormal	0	普通群
kNIMTeamTypeAdvanced	1	高级群

NIMTeamUserType枚举说明

枚举	值	说明
kNIMTeamUserTypeNomal	0	普通成员
kNIMTeamUserTypeCreator	1	创建者
kNIMTeamUserTypeManager	2	管理员
kNIMTeamUserTypeApply	3	申请加入用户
kNIMTeamUserTypeLocalWaitAccept	100	本地记录等待正在入群的用户

群聊消息收发和管理与双人聊天完全相同，仅在消息类型上做了区分,详见消息收发。

群通知事件

API 介绍

注册该事件监听群信息变更,包括群组的创建、解散、邀请入群、踢出群组等群相关操作的都通过该事件通知给调用者。

nim_team_event_cb_func参数说明

类型	参数	说明
int	res_code	错误码
int	notification_id	通知类型，详见NIMNotificationId
string	tid	群id
string	result	通知内容，详见`TeamEvent`说明
string	json_extension	扩展字段，预留
void*	user_data	APP的自定义用户数据，SDK只负责传回给回调函数，不做任何处理

TeamEvent说明

类型	参数	说明
NIMNotificationId	kNIMNotificationKeyId	群通知类型，包括创建群、解散群等等（详见`NIMNotificationId`
string	kNIMNotificationKeyData	通知内容，json 字符串，字段定义详见TeamNotificationData

TeamNotificationData说明

类型	参数	说明
string	kNIMNotificationKeyDataIds	通知可能涉及到的群成员ID，比如增加管理员操作可以添加多个账号，收到通知时ids对应其多个账号,json array
string	kNIMNotificationKeyDataInvalidIds	通知可能涉及到的失效的群成员ID，比如邀请入群的成员的群数量超限导致当次邀请失败,json array
string	kNIMNotificationKeyDataId	通知对单个成员操作的id,比如禁言群成员，移交群主等操作的被操作方id
NIMTeamInfo	kNIMNotificationKeyTeamInfo	群信息数据
TeamMemberProperty	kNIMNotificationKeyTeamMember	群成员信息，比如修改自己的群成员属性时，通过`kNIMNotificationIdTeamSyncUpdateMemberProperty`通知类型来通知
string	kNIMNotificationKeyUserNameCards	通知可能涉及到的群成员的用户名片,json array
int	kNIMNotificationKeyDataMute	通知禁言，1：禁言 0：解除禁言
string	kNIMNotificationKeyDataAttach	扩展字段,目前仅kick和invite事件可选(暂不支持)

TeamEvent解析示例

void ParseTeamEvent(Json::Value values)
{
    Json::Value data = values[kNIMNotificationKeyData];
    if (values.isObject())
    {
        //群信息
        if (data.isMember(kNIMNotificationKeyTeamInfo))
        {
            //参考群信息解析
            ParseTeamInfo(data[kNIMNotificationKeyTeamInfo]);
            ...
        }

        //操作者和被操作者用户名片
        Json::Value name_cards = data[kNIMNotificationKeyUserNameCards];
        if (!name_cards.empty() && name_cards.isArray())
        {
            //参考用户资料托管部分的数据解析
            //ParseNamesCard()
            ...
        }

        switch (notification_id)
        {
        case kNIMNotificationIdTeamKick:
        case kNIMNotificationIdTeamInvite:
        case kNIMNotificationIdTeamAddManager:
        case kNIMNotificationIdTeamRemoveManager:
        case kNIMNotificationIdLocalCreateTeam:
        {
            //ids
            Json::Value ids = data[kNIMNotificationKeyDataIds];
            int len = ids.size();
            for (int i = 0; i < len; i++)
            {
                char* uid = ids[i].asString();
                ...
            }

            //判断是否存在此字段
            if (data.isMember(kNIMNotificationKeyDataInvalidIds))
            {
                ids = data[kNIMNotificationKeyDataInvalidIds];
                int len = ids.size();
                for (int i = 0; i < len; i++)
                {
                    char* invalidUid = ids[i].asString();
                    ...
                }
            }
        }
        break;
        case kNIMNotificationIdTeamLeave:
        case kNIMNotificationIdTeamApplyPass:
        case kNIMNotificationIdTeamInviteAccept:
        case kNIMNotificationIdLocalRejectApply:
        case kNIMNotificationIdLocalRejectInvite:
            {
                //id
                char* id = data[kNIMNotificationKeyDataId].asString();
                ...
            }
            break;
        case kNIMNotificationIdTeamUpdate:
        case kNIMNotificationIdTeamSyncCreate:
        case kNIMNotificationIdLocalGetTeamInfo:
        case kNIMNotificationIdTeamDismiss:
        case kNIMNotificationIdLocalApplyTeam:
        case kNIMNotificationIdLocalGetTeamList:
            break;
        case kNIMNotificationIdTeamOwnerTransfer:
            {
                bool opt = data[kNIMNotificationKeyDataLeave].asBool();
                char* id = data[kNIMNotificationKeyDataId].asString();
                ...
            }
            break;
        case kNIMNotificationIdTeamMemberChanged:
        case kNIMNotificationIdLocalUpdateOtherNick:
        case kNIMNotificationIdTeamSyncUpdateMemberProperty:
        case kNIMNotificationIdLocalUpdateMemberProperty:
            {
                //群成员信息解析，参考ParseTeamMemberProperty
                ParseTeamMemberProperty(data[kNIMNotificationKeyTeamMember]);
                ...
            }
            break;
        case kNIMNotificationIdTeamMuteMember:
        case kNIMNotificationIdLocalMuteMember:
            {
                bool mute = data[kNIMNotificationKeyDataMute].asInt() == 1;
                char* id = data[kNIMNotificationKeyDataId].asString();
                ...
            }
            break;
        default:
            break;
        }
    }
}

NIMNotificationId枚举类型说明

枚举	值	说明
kNIMNotificationIdTeamInvite	0	普通群拉人，{“tinfo”:team_info,"ids":["a1", "a2"],"uinfos":["uinfo1", "uinfo2"]},json串对应`NIMTeamEvent`字段的数据，下同
kNIMNotificationIdTeamKick	1	普通群踢人，{“tinfo”:tinfo,"ids":["a1", "a2"],"uinfos":["uinfo1", "uinfo2"]}
kNIMNotificationIdTeamLeave	2	退出群，{"uinfos":["uinfo1", "uinfo2"]}
kNIMNotificationIdTeamUpdate	3	群信息更新，{"tinfo":tinfo,"uinfos":["uinfo1", "uinfo2"]}
kNIMNotificationIdTeamDismiss	4	群解散，{"uinfos":["uinfo1", "uinfo2"]}
kNIMNotificationIdTeamApplyPass	5	高级群申请加入成功，{"tinfo":tinfo,"id":"a1","uinfos":["uinfo1", "uinfo2"]}
kNIMNotificationIdTeamOwnerTransfer	6	高级群移交群主，{"id":"a1","uinfos":["uinfo1", "uinfo2"]}
kNIMNotificationIdTeamAddManager	7	增加管理员，{"ids":["a1","a2"],"uinfos":["uinfo1", "uinfo2"]}
kNIMNotificationIdTeamRemoveManager	8	移除管理员，{"ids":["a1","a2"],"uinfos":["uinfo1", "uinfo2"]}
kNIMNotificationIdTeamInviteAccept	9	高级群接受邀请进群，{"tinfo":tinfo,"id":"a1","uinfos":["uinfo1", "uinfo2"]}
kNIMNotificationIdTeamMuteMember	10	禁言/解禁群成员，{"uinfos":["uinfo1", "uinfo2"],“tinfo”:tinfo,"id":"a1","mute":1-禁言,0-解禁}
kNIMNotificationIdNetcallMiss	101	未接电话（暂不支持）,{"calltype":1,"channel":6146078138783760761,"from":"id1","ids":["id1","id2"],"time":1430995380471}
kNIMNotificationIdNetcallBill	102	话单（暂不支持）,{"calltype":2,"channel":6146077129466446197,"duration":8,"ids":["id1","id2"],"time":1430995117398}
kNIMNotificationIdTeamSyncCreate	1000	创建群{"tinfo" : tinfo}
kNIMNotificationIdTeamMemberChanged	1001	群成员变更{"team_member" : team_member_info}
kNIMNotificationIdTeamSyncUpdateMemberProperty	1002	同步通知：修改自己的群属性{"team_member" : team_member_info} 目前只需kNIMTeamUserKeyNick和kNIMTeamUserKeyBits,接收到该通知时，`MemberInfo`字段会通知更新的信息
kNIMNotificationIdLocalCreateTeam	2000	本地操作创建群 {"ids" : ["a1", "a2"]}
kNIMNotificationIdLocalApplyTeam	2001	本地操作申请加入群
kNIMNotificationIdLocalRejectApply	2002	本地操作拒绝申请 {"id":"a1"}
kNIMNotificationIdLocalRejectInvite	2003	本地操作拒绝邀请 {"id":"a1"}
kNIMNotificationIdLocalUpdateMemberProperty	2004	本地操作更新群成员属性
kNIMNotificationIdLocalUpdateOtherNick	2005	本地操作更新他人nickname
kNIMNotificationIdLocalGetTeamInfo	2006	普通群踢人，{“tinfo”:tinfo,"ids":["a1", "a2"],"uinfos":["uinfo1", "uinfo2"]}
kNIMNotificationIdLocalGetTeamList	2007	本地操作获取群成员信息
kNIMNotificationIdLocalMuteMember	2008	本地操作对群成员禁言
kNIMNotificationIdLocalNetcallReject	3103	拒绝电话（暂不支持）,{"calltype":1,"channel":6146078138783760761,"from":"id1","ids":["id1","id2"],"time":1430995380471}
kNIMNotificationIdLocalNetcallNoResponse	3104	无应答，未接通电话（暂不支持）,{"calltype":1,"channel":6146078138783760761,"from":"id1","ids":["id1","id2"],"time":1430995380471}

API 原型

nim_team_reg_team_event_cb(const char *json_extension, nim_team_event_cb_func cb, const void *user_data);

参数说明

参数	说明
cb	异步通知回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //解析result示例
    Json::Reader reader;
    Json::Value values;
    if (reader.parse(result, values) && values.isObject())
    {
        //解析通知内容,参考ParseTeamEvent
        ParseTeamEvent(values);
        ...
    }
    ...
}
//注册事件监听
nim_team_reg_team_event_cb(0,my_nim_team_event_cb_func,0);


//不需要时，取消事件监听
nim_team_reg_team_event_cb(0,0,0);

获取群组

NIM SDK 在程序启动时会对本地群信息进行同步，所以只需要调用本地缓存接口获取群就可以了。 SDK 提供了批量获取自己的群接口、以及根据单个群 id 查询的接口。同样 SDK 也提供了远程获取群信息的接口。群信息。

TeamInfo群信息字段说明

类型	参数	说明
string	kNIMTeamInfoKeyID	群组id
string	kNIMTeamInfoKeyName	群组名称
NIMTeamType	kNIMTeamInfoKeyType	群组类型，分高级群和普通群，详见NIMTeamType
string	kNIMTeamInfoKeyCreator	群组的拥有者或创建者
int	kNIMTeamInfoKeyLevel	群组等级
string	kNIMTeamInfoKeyProperty	群组属性预留扩展字段，长度限制：6000字符
int	kNIMTeamInfoKeyValidFlag	此群组是否有效，1为有效,0为无效
int	kNIMTeamInfoKeyMemberCount	群成员数量
int64_t	kNIMTeamInfoKeyListTime	群成员列表最新更新时间戳（毫秒）
int64_t	kNIMTeamInfoKeyCreateTime	群组创建时间戳（毫秒）
int64_t	kNIMTeamInfoKeyUpdateTime	群信息最新更新时间戳（毫秒）
bool	kNIMTeamInfoKeyMemberValid	该群的群成员列表是否还有效,1:有效 0: 无效
string	kNIMTeamInfoKeyIntro	群组简介
string	kNIMTeamInfoKeyAnnouncement	群公告
NIMTeamJoinMode	kNIMTeamInfoKeyJoinMode	入群模式，0-不用验证 1-需要验证 2-拒绝所有人入群(仅高级群)
string	kNIMTeamInfoKeyCustom	第三方扩展字段，仅负责存储和透传
string	kNIMTeamInfoKeyServerCustom	服务器预留扩展字段（该配置项只能通过服务器接口设置，对客户端只读）(仅高级群)
string	kNIMTeamInfoKeyIcon	群头像
NIMTeamBeInviteMode	kNIMTeamInfoKeyBeInviteMode	被邀请人同意方式，属性本身只有群主管理员可以修改，0-需要同意(默认),1-不需要同意(仅高级群)
NIMTeamInviteMode	kNIMTeamInfoKeyInviteMode	谁可以邀请他人入群，属性本身只有群主管理员可以修改，0-管理员(默认),1-所有人(仅高级群)
NIMTeamUpdateInfoMode	kNIMTeamInfoKeyUpdateInfoMode	谁可以修改群资料，属性本身只有群主管理员可以修改，0-管理员(默认),1-所有人(仅高级群)
NIMTeamUpdateCustomMode	kNIMTeamInfoKeyUpdateCustomMode	谁可以更新群自定义属性，属性本身只有群主管理员可以修改(仅高级群)
bool	kNIMTeamInfoKeyMuteAll	群全员禁言标记 0:未禁言，1:禁言(仅高级群)(暂不支持)

注意：当用户退出群或被踢出群或群解散后，kNIMTeamInfoKeyMemberValid 值为false，对于当前用户而言，此群已不再是此用户的有效群。

TeamInfo解析示例

//解析群信息内容
void ParseTeamInfo(const Json::Value& team_info)
{
    if (team_info.isObject())
    {
        NIMTeamType type= (NIMTeamType)team_info[kNIMTeamInfoKeyType].asInt();
        char* teamID = team_info[kNIMTeamInfoKeyID].asString();
        char* ownerID = team_info[kNIMTeamInfoKeyCreator].asString();
        char* name = team_info[kNIMTeamInfoKeyName].asString();
        char* intro = team_info[kNIMTeamInfoKeyIntro].asString();
        char* announcement = team_info[kNIMTeamInfoKeyAnnouncement].asString();
        NIMTeamJoinMode joinMode = (NIMTeamJoinMode)team_info[kNIMTeamInfoKeyJoinMode].asInt();
        char* serverCustom = team_info[kNIMTeamInfoKeyServerCustom].asString();
        int64_t createTimetag = team_info[kNIMTeamInfoKeyCreateTime].asUInt64();
        int64_t updateTimetag = team_info[kNIMTeamInfoKeyUpdateTime].asUInt64();
        char* custom = team_info[kNIMTeamInfoKeyCustom].asString();
        uint memberCount = team_info[kNIMTeamInfoKeyMemberCount].asUInt();
        char* Property = team_info[kNIMTeamInfoKeyProperty].asString();
        bool isValid = team_info[kNIMTeamInfoKeyValidFlag].asUInt() == 0 ? false : true);

        bool isMemberValid = team_info[kNIMTeamInfoKeyMemberValid].asUInt() == 0 ? false : true);
        char* icon = team_info[kNIMTeamInfoKeyIcon].asString();
        NIMTeamBeInviteMode beInviteMode = team_info[kNIMTeamInfoKeyBeInviteMode].asInt();
        NIMTeamInviteMode inviteMode = team_info[kNIMTeamInfoKeyInviteMode].asInt();
        NIMTeamUpdateInfoMode UpdateInfoMode = team_info[kNIMTeamInfoKeyUpdateInfoMode].asInt();
        NIMTeamUpdateCustomMode UpdateCustomMode = team_info[kNIMTeamInfoKeyUpdateCustomMode].asInt();
        bool isAllMemberMute = team_info[kNIMTeamInfoKeyMuteAll].asInt();
        ...
    }
}

TeamMemberProperty群成员信息字段说明

类型	参数	说明
string	kNIMTeamUserKeyID	群组id
string	kNIMTeamUserKeyAccID	群成员账号
NIMTeamUserType	kNIMTeamUserKeyType	群成员类型，详见NIMTeamUserType
int64_t	kNIMTeamUserKeyCreateTime	入群时间戳
int64_t	kNIMTeamUserKeyUpdateTime	群成员信息更新时间戳
bool	kNIMTeamUserKeyValidFlag	群成员是否有效，如果已退群等则为false
string	kNIMTeamUserKeyNick	群成员昵称
int64_t	kNIMTeamUserKeyBits	配置属性，当前仅用来设置消息提醒，1：提醒默认为0
string	kNIMTeamUserKeyCustom	自定义第三方扩展信息
bool	kNIMTeamUserKeyMute	是否禁言，true:禁言，false:取消禁言（默认）

TeamMemberProperty解析示例

//解析群信息内容
void ParseTeamMemberProperty(const Json::Value& prop)
{
    if (prop.isObject())
    {
       char* teamID = prop[kNIMTeamUserKeyID].asString();
       char* userID = prop[kNIMTeamUserKeyAccID].asString();
       NIMTeamUserType type = (NIMTeamUserType)prop[kNIMTeamUserKeyType].asUInt();
       char* nick = prop[kNIMTeamUserKeyNick].asString();
       int64_t bits = prop[kNIMTeamUserKeyBits].asUInt64(); 
       bool isValid = prop[kNIMTeamUserKeyValidFlag].asUInt() == 1;
       int64_t createTimetag = prop[kNIMTeamUserKeyCreateTime].asUInt64();
       int64_t updateTimetag = prop[kNIMTeamUserKeyUpdateTime].asUInt64();
       bool isMute = prop[kNIMTeamUserKeyMute].asUInt() == 1;
       char* custom = prop[kNIMTeamUserKeyCustom].asString();
        ...
    }
}

本地获取群列表

SDK最新版本在当用户不在该群组或该群组已经解散时，本地数据库不再清除该缓存的数据，所以同时提供了查询有效群和查询所有群（包含无效群）的接口。

1. 获取有效群信息列表

API 原型

 void nim_team_query_all_my_teams_info_async(const char *json_extension,nim_team_query_all_my_teams_info_cb_func cb,const void *user_data);

参数说明

参数	说明
cb	通知结果回调
json_extension	扩展字段，可选，用于查询包含无效群，格式如:{"include_invalid":1},默认查询有效群
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_query_all_my_teams_info_cb_func(int team_count, const char *result, const char *json_extension, const void *user_data)
{
    //解析result
    Json::Value json;
    Json::Reader reader;
    if (reader.parse(result, json) && json.isArray())
    {
        int len = json.size();
        for (int i = 0; i < len; i++)
        {
            //解析为TeamInfon内容，参考ParseTeamInfo
            参考ParseTeamInfo(json[i]);
            ...
        }
        ...
    }
}
//获取有效群信息列表
nim_team_query_all_my_teams_info_async(0,my_nim_team_query_all_my_teams_info_cb_func,0);

//获取所有群信息列表，包括无效群
Json::FastWriter fw;
Json::Value param;
param["include_invalid"] = true;
nim_team_query_all_my_teams_info_async(0,my_nim_team_query_all_my_teams_info_cb_func,fw.write(param));

2. 获取本人所在群列表

API 介绍

仅获取本人所在群的群id列表，

API 原型

void nim_team_query_all_my_teams_async(const char *json_extension,nim_team_query_all_my_teams_cb_func cb,const void *user_data);

参数说明

参数	说明
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_query_all_my_teams_cb_func(int team_count, const char *result, const char *json_extension, const void *user_data)
{
    //result:json 数组 ["tid1","tid2"]
    ...
}
//获取本人所在群id列表
nim_team_query_all_my_teams_async(0,my_nim_team_query_all_my_teams_cb_func,0);

获取群信息

SDK提供了同步和异步两个版本来获取本地的群信息，也提供了直接获取云端的群信息的接口。

1. 获取本地群信息（同步版本）

API 原型

  char* nim_team_query_team_info_block(const char *tid);

参数说明

参数	说明
tid	所要获取的群id

示例

//获取本地群信息
char* tid = "1243354";
char* tinfo = nim_team_query_team_info_block(tid);
//解析群信息：ParseTeamInfo
if (tinfo != null)
{
    Json::Reader reader;
    Json::Value values;
    if (reader.parse(tinfo,valuses) && values.isObject())
    {
        //参考ParseTeamInfo
        ParseTeamInfo(values);
        ...
    }
}
free(tinfo);//需要释放内存

2.获取本地群信息（异步版本）

API 原型

void nim_team_query_team_info_async(const char *tid,const char *json_extension,nim_team_query_team_info_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	所要获取的群id
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_query_team_info_cb_func(const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //解析群信息
    Json::Reader reader;
    Json::Value values;
    if (reader.parse(result,valuses) && values.isObject())
    {
        //参考ParseTeamInfo
        ParseTeamInfo(values);
        ...
    }
    ...
}
//获取本地群信息
char* tid = "1243354";
nim_team_query_team_info_async(tid,0,my_nim_team_query_team_info_cb_func,0);

3.获取云端群信息

API 原型

void nim_team_query_team_info_online_async(const char *tid,    const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	所要获取的群id
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    ...
}
//获取云端群信息
char* tid = "1243354";
nim_team_query_team_info_online_async(tid, 0,my_nim_team_event_cb_func,0);

获取云端禁言列表

API 原型

void nim_team_query_mute_list_online_async(const char *tid,    const char *json_extension,nim_team_query_mute_list_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	所要获取的群id
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_query_mute_list_cb_func(int res_code, int member_count, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //result：返回TeamMemberProperty的数组
    Json::Value values;
    Json::Reader reader;
    if (reader.parse(result, values) && values.isArray())
    {
        auto size = values.size();
        for (int i = 0; i < size; i++)
        {
            //解析为TeamMemberProperty定义数据，参考ParseTeamMemberProperty
            ParseTeamMemberProperty(values[i]);
            ...
        }
    }
    ...
}
//获取云端的群禁言列表
char* tid = "1243354";
nim_team_query_mute_list_online_async(tid,0,my_nim_team_query_mute_list_cb_func,0);

群成员信息

SDK支持获取群成员列表信息，也支持获取单个群成员的信息。获取单个群成员信息分别提供同步版本和异步版本的接口，以方便开发者调用。

获取群成员列表

SDK支持查询指定群的有效群成员列表，也支持查询已经退出群的本地群成员。

API 原型

 void nim_team_query_team_members_async(const char *tid,bool include_user_info,const char *json_extension,nim_team_query_team_members_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	所要获取的群id
include_user_info	是否获取群成员信息，如果为false，返回的数据仅`kNIMTeamUserKeyAccID`,`kNIMTeamUserKeyID`有效
cb	通知结果回调
json_extension	扩展字段，可选，用于查询包含无效群成员，格式如:{"include_invalid":1},默认查询有效群
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_query_team_members_cb_func(const char *tid,int member_count,bool include_user_info,const char *result,const char *json_extension,const void *user_data)
{
    //result：返回TeamMemberProperty的数组
    Json::Value values;
    Json::Reader reader;
    if (reader.parse(result, values) && values.isArray())
    {
        auto size = values.size();
        for (int i = 0; i < size; i++)
        {
            //解析为TeamMemberProperty定义数据，参考ParseTeamMemberProperty
            ParseTeamMemberProperty(values[i]);
            ...
        }
    }
    ...
}


//获取群有效群成员信息
char* tid = "1243354";
nim_team_query_team_members_async(tid,0,my_nim_team_query_team_members_cb_func,0);

//获取所有群成员列表，包括无效群成员
Json::FastWriter fw;
Json::Value param;
param["include_invalid"] = 1;
nim_team_query_team_members_async(tid,0,my_nim_team_query_team_members_cb_func,fw.write(param));

获取群成员信息

1. 获取群成员信息（同步版本）

API 原型

 char *nim_team_query_team_member_block(const char *tid, const char *user_id);

参数说明

参数	说明
tid	所要获取的群id
user_id	所要获取的群成员id

示例

//获取群成员test1信息
char* tid = "1243354";
char* uid = "test1";
char* tinfo = nim_team_query_team_member_block(tid,uid);
Json::Value values;
Json::Reader reader;
if (reader.parse(tinfo, values) && values.isObject())
{
    //解析为TeamMemberProperty定义数据，参考ParseTeamMemberProperty
    ParseTeamMemberProperty(values);
    ...
}
free(tinfo);//需要外部释放

2.获取群成员信息（异步版本）

API 原型

void nim_team_query_team_member_async(const char *tid,const char *user_id,const char *json_extension,nim_team_query_team_member_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	所要获取的群id
user_id	所要获取的群成员id
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_query_team_member_cb_func(const char *tid,    const char *user_id,const char *result,const char *json_extension,const void *user_data)
{
    Json::Value values;
    Json::Reader reader;
    if (reader.parse(result, values) && values.isObject())
    {
        //解析为TeamMemberProperty定义数据，参考ParseTeamMemberProperty
        ParseTeamMemberProperty(values);
        ...
    }
    ...
}
//获取群成员test1信息
char* tid = "1243354";
char* uid = "test1";
nim_team_query_team_member_async(tid,uid,0,my_nim_team_query_team_member_cb_func,0);

创建群组

创建群组可分为普通群和高级群，目前版本的高级群覆盖了所有的普通群功能。TeamInfo 包含群组的详细信息，通过设置该对象可以指定群类型，群组权限，群资料等信息；如果设置了 invitation_postscript，会发送给群中的每个成员。

API 原型

 void nim_team_create_team_async(const char *team_info,const char *jsonlist_uids,const char *invitation_postscript,const char *json_extension, nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
team_info	所创建群的基本信息，如群名，群公告等等
jsonlist_uids	创建群组时同时需要加入群的用户账号，不包括自己账号，系统自动会发送邀请给`ids`所有成员
invitation_postscript	邀请附言信息
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}
//以测试账号test1,test2为例
Json::FastWriter fw;
Json::Value ti;
ti[kNIMTeamInfoKeyName] = "teamName";
ti[kNIMTeamInfoKeyAnnouncement] = "群公告";
ti[kNIMTeamInfoKeyIntro] = "群简介";
ti[kNIMTeamInfoKeyType] = kNIMTeamTypeAdvanced;

Json::Value ids; //json array
ids.append("test1");
ids.append("test2");

nim_team_create_team_async(fw.write(ti), fw.write(ids), "邀请附言信息",0, my_nim_team_event_cb_func,0);

加入群组

用户可以通过被动接受邀请和主动加入两种方式进入群组。

邀请用户入群

API 介绍

请求完成后，如果是普通群，被邀请者将直接入群；如果是高级群，云信服务器会下发一条系统消息到目标用户，目标用户可以选择同意或者拒绝入群。

API 原型

void nim_team_invite_async(const char *tid,const char *jsonlist_uids,const char *invitation_postscript,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	群id
jsonlist_uids	创建群组时同时需要加入群的用户账号，不包括自己账号
invitation_postscript	邀请附言信息,如果不为空，此信息会通知给被邀请的好友
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}
//以测试账号test1,test2为例
char* tid = "1231232";
Json::FastWriter fw;
Json::Value ids; //json array
ids.append("test1");
ids.append("test2");

nim_team_invite_async(tid,fw.write(ids),0,"附言信息",0,my_nim_team_event_cb_func,0);

注意：普通群需要在邀请好友入群后，同时给这个群发一条消息，好友才会收到邀请通知。

收到通知后，高级群用户可以进行以下操作：

同意群邀请(仅限高级群)：void nim_team_accept_invitation_async(const char *tid,const char *invitor,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

代码示例

//以测试群1231232,邀请者账号testAccount为例
char* tid = "1231232";
char* invitor_uid = "testAccount";//填写邀请方的id
nim_team_accept_invitation_async(tid, invitor_uid, 0,my_nim_team_event_cb_func,0);

拒绝群邀请(仅限高级群)：void nim_team_reject_invitation_async(const char *tid,const char *invitor,const char *reason, const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

代码示例

//以测试群1231232,邀请者账号testAccount为例
char* tid = "1231232";
char* invitor_uid = "testAccount";//填写邀请方的id
nim_team_reject_invitation_async(tid, invitor_uid, "拒绝原因", 0,my_nim_team_event_cb_func,0);

用户主动申请入群

API 介绍

发送请求后，云信服务器会下发一条系统消息给群管理员，管理员可以选择通过或者拒绝申请。仅高级群支持。

API 原型

 void nim_team_apply_join_async(const char *tid,const char *reason,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	群id
reason	申请附言信息,如果不为空，此信息会通知给被群管理人员
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}
//以测试群1231232为例
cha* tid = "1231232";
nim_team_apply_join_async(tid, "申请附言",0,my_nim_team_event_cb_func,0);

群管理人员可以进行一下操作:

通过申请(仅限高级群): void nim_team_pass_join_apply_async(const char *tid,const char *applicant_id,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

代码示例：


//以测试群1231232,测试账号test1为例
char* tid = "1231232";
char* uid = "test1";//申请者的账号
nim_team_pass_join_apply_async(tid, uid,0,my_nim_team_event_cb_func,0);

拒绝申请(仅限高级群): void nim_team_reject_join_apply_async(const char *tid,const char *applicant_id,const char *reason,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

代码示例：

//以测试群1231232,测试账号test1为例
char* tid = "1231232";
char* uid = "test1";//申请者的账号
char*  reason = "因为你不够美";//拒绝理由
nim_team_reject_join_apply_async(tid, uid, reason,0,my_nim_team_event_cb_func,0);

退出群组

退出群组包括主动退出群组和被动退出。群管理员和群主都拥有踢出群的权限。被踢出群后，会收到系统通知，通过群通知事件通知给用户。

API 原型

void nim_team_leave_async(const char *tid,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	群id
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}
//以测试群1231232为例
char* tid = "1231232";
nim_team_leave_async(tid,0,my_nim_team_event_cb_func,0);

解散群

高级群群主拥有解散群的权限，其他成员均没有此权限。仅高级群支持。

API 原型

void nim_team_dismiss_async(const char *tid,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	群id
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}
//以测试群1231232为例
char* tid = "1231232";
nim_team_dismiss_async(tid,0,my_nim_team_event_cb_func,0);

踢人出群

群主可以踢出任何群成员，高级群管理员可以踢出普通群成员。

API 原型

void nim_team_kick_async(const char *tid,const char *jsonlist_uids,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	群id
jsonlist_uids	被踢出的群成员id集合
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}
//以测试群1231232,测试账号test1,test2为例
char* tid = "1231232";
Json::FastWriter fw; //序列化json
Json::Value ids; //json array
ids.append("test1");
ids.append("test2");

nim_team_kick_async(tid, fw.write(ids), 0,my_nim_team_event_cb_func,0);

群成员禁言

支持管理员和群主对普通成员的禁言、解除禁言操作。

API 原型

void nim_team_mute_member_async(const char *tid,const char *member_id,bool set_mute,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	群id
member_id	禁言/解除禁言的群成员id
set_mute	是否禁言，true:禁言，false:解除禁言
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}
//以测试群1231232,测试账号test1为例
char* tid = "1231232";
char* uid = "test1");
nim_team_mute_member_async(tid, uid, true, 0,my_nim_team_event_cb_func,0);

编辑群组资料

API 介绍

普通群成员都可以修改群名等信息，高级群只有管理员才有权限修改。

API 原型

void nim_team_update_team_info_async(const char *tid,const char *json_info,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	群id
json_info	群信息，详见TeamInfo定义字段，只填入需要修改的字段，不需要修改的不填
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}
//以修改群名称为例
char* tid = "1231232";
Json::FastWriter fw;
Json::Value ti;
ti[kNIMTeamInfoKeyName] = "newTeamName";
ti[kNIMTeamInfoKeyID] = tid;

nim_team_update_team_info_async(tid,fw.write(ti),0,my_nim_team_event_cb_func,0);

修改群成员信息

SDK提供允许管理员修改他人在群内的昵称，也允许用户修改自己在群内的信息

更新本人的群成员资料

API 介绍

群内成员可以修改本人的资料信息。

API 原型

void nim_team_update_my_property_async(const char *info,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
info	群信成员息,详见TeamMemberProperty，最好能先通过接口获取本人的完整的群成员信息，然后再将需要修改的字段更新为新的值，`kNIMTeamUserKeyID`、`kNIMTeamUserKeyAccID`字段必填
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}

//以修改群名称为例
char* tid = "1231232";

//群成员信息最好是先通过接口获取本人的完整的群成员信息，然后再将需要修改的字段更新为新的值，此处仅为示例。
Json::FasterWriter fw;
Json::Value tmi;
tmi[kNIMTeamUserKeyID] = tid;
tmi[kNIMTeamUserKeyNick] = "newNick";
tmi[kNIMTeamUserKeyAccID] = "myUid";  //本人账号;
nim_team_update_my_property_async( fw.write(tmi),0,my_nim_team_event_cb_func,0);

修改其他成员的群昵称

API 介绍

群管理员和群主可以修改其他成员的群昵称。

API 原型

void nim_team_update_other_nick_async(const char *info,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
info	群成员信息，详见TeamMemberProperty，`kNIMTeamUserKeyID`、`kNIMTeamUserKeyAccID`字段必填，`kNIMTeamUserKeyNick`可为空
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}

//以修改群名称为例
char* tid = "1231232";

//群成员信息最好是先通过接口获取完整的群成员信息，然后再将需要修改的字段更新为新的值，此处仅为示例。
Json::FasterWriter fw;
Json::Value tmi;
tmi[kNIMTeamUserKeyID] = tid;
tmi[kNIMTeamUserKeyNick] = "newNick";
tmi[kNIMTeamUserKeyAccID] = "test1"; //账号;
nim_team_update_other_nick_async( fw.write(tmi),0,my_nim_team_event_cb_func,0);

群组权限管理

SDK提供了对高级群的权限管理功能，仅管理员和群主可以进行操作。可以增加，移除管理员，转让群主等。

添加管理员

API 介绍

将 jsonlist_admin_ids 中包含的账号全部设置为群管理员

API 原型

void nim_team_add_managers_async(const char *tid,const char *jsonlist_admin_ids,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	群id
jsonlist_admin_ids	群成员账号id集合
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}

//以测试群1231232,测试账号test1,test2为例
char* tid = "1231232";
Json::FasterWriter fw;
Json::Value ids; //json array
ids.append("test1");
ids.append("test2");

nim_team_add_managers_async(tmi, fw.write(ids),0,my_nim_team_event_cb_func,0);

移除管理员

API 介绍

将 managerIdArray 中包含的账号全部移除群管理员身份

API 原型

 void nim_team_remove_managers_async(const char *tid,const char *jsonlist_admin_ids,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	群id
jsonlist_admin_ids	群成员账号id集合
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}

//以测试群1231232,测试账号test1,test2为例
char* tid = "1231232";
Json::FasterWriter fw;
Json::Value ids; //json array
ids.append("test1");
ids.append("test2");

nim_team_remove_managers_async(tmi, fw.write(ids),0,my_nim_team_event_cb_func,0);

移交群主

API 介绍

将群主转让给其他群成员。is_leave为true时，移交成功后，同时退出本群。

API 原型

void nim_team_transfer_team_async(const char *tid,const char *new_owner,bool is_leave,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);

参数说明

参数	说明
tid	群id
new_owner	新的群主账号id
is_leave	是否移交群主成功后退出该群。true:移交群主并退出该群，false:移交群主但不退出本群
cb	通知结果回调
json_extension	扩展字段，预留
user_data	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
    //同nim_team_reg_team_event_cb
    ...
}

//以测试群1231232,测试账号test1
char* tid = "1231232";
char* newOwnerId = "test1";
nim_team_transfer_team_async(tid, newOwnerId,true,0,my_nim_team_event_cb_func,0);

IM即时通讯

产品介绍

服务端API文档

SDK开发集成

iOS开发集成

Android开发集成

Windows开发集成

Linux开发集成

Web开发集成

Unity开发集成

Cocos2d-x开发集成

更新日志

Demo更新日志

群组功能

群组功能概述

群通知事件

获取群组

本地获取群列表

获取群信息

获取云端禁言列表

群成员信息

获取群成员列表

获取群成员信息

创建群组

加入群组

邀请用户入群

用户主动申请入群

退出群组

解散群

踢人出群

群成员禁言

编辑群组资料

修改群成员信息

更新本人的群成员资料

修改其他成员的群昵称

群组权限管理

添加管理员

移除管理员

移交群主

IM即时通讯

产品介绍

服务端API文档

SDK开发集成

iOS开发集成

Android开发集成

Windows开发集成

Linux开发集成

Web开发集成

Unity开发集成

Cocos2d-x开发集成

更新日志

Demo更新日志

群组功能

群组功能概述

群通知事件

获取群组

本地获取群列表

获取群信息

获取云端禁言列表

群成员信息

获取群成员列表

获取群成员信息

创建群组

加入群组

邀请用户入群

用户主动申请入群

退出群组

解散群

踢人出群

群成员禁言

编辑群组资料

修改群成员信息

更新本人的群成员资料

修改其他成员的群昵称

群组权限管理

添加管理员

移除管理员

移交群主

相关文档

相关产品