服务端
API 参考
圈组

创建高级群

更新时间: 2024/05/24 10:47:31

创建高级群,创建时即可通过设置群成员列表邀请用户入群。

功能描述

  • 建群成功会返回 tid,云信服务器产生,群唯一标识,该字段需要保存,以便于加人与踢人等后续操作。
  • 如果创建时邀请的成员中存在加群数量超过限制的情况,会返回 faccid(加群失败成员的 IM 账号)。
  • 每个用户可创建的群数量有限制,限制值由 IM 套餐的群组配置决定,具体可前往云信控制台查看。

API 使用限制

单个应用中 1 秒内所有的高级群操作 API 合计最多可调用 100 次,超过后限制调用,会返回 416 错误码。

除发送群消息 API 外,其他所有高级群 API 都属于高级群操作 API。

URL

POST https://api.netease.im/nimserver/team/create.action  HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求参数

  • POST 请求中 Headers 的设置请参考API 调用方式
  • POST 请求中 Body 的设置如下:
参数类型必填说明
tnameString群名称,最大长度 64 位字符
ownerString群主帐号,accid,最大长度 32 位字符
membersString邀请的群成员列表,\["aaa","bbb"\](JSONArray 对应的 accid,如果解析出错会报 414)
members 与 owner 总和上限为 200。members 中无需再加 owner 自己的账号
announcementString群公告,最大长度 1024 位字符
introString群描述,最大长度 512 位字符
msgString邀请发送的文字,最大长度 150 位字符
magreeInteger创建群时,若 members 不为空,那么邀请其入群是否需要同意
0,不需要被邀请人同意加入群(默认);1,需要被邀请人同意才可以加入群只有当 beinvitemode = 0 时,magree 才能设为 1,即 时,magree =1 才生效。
joinmodeInteger群创建完成后,通过 SDK 侧操作申请入群的验证方式
0,不用验证;1,需要群主或管理员的验证;2,不允许任何人加入
customString自定义高级群扩展属性,第三方可以跟据此属性自定义扩展自己的群属性,建议为 JSON,最大长度 1024 位字符
icon String群头像,最大长度 1024 位字符
beinvitemode Integer群创建完成后,邀请入群时是否需要被邀请人的同意
0,需要同意(默认);1,不需要同意
invitemode Integer邀请权限,即谁可以邀请他人入群
0,群主和管理员(默认);1,所有人
uptinfomode Integer客户端修改群信息权限,即谁可以修改群信息
0,群主和管理员(默认);1,所有人
upcustommode Integer客户端修改群自定义属性权限,即谁可以修改群自定义属性
0,群主和管理员(默认);1,所有人
teamMemberLimit Integer最大群成员数(包含群主),[2,200(默认)]
isNotifyCloseOnline Integer是否关闭群通知消息在线发送
0,否;1,是
isNotifyClosePersistent Integer是否关闭存储离线/漫游/历史的群通知消息
0,否;1,是
attach String自定义扩展字段,最大长度 512 位字符
bid String反垃圾业务 ID,JSON 字符串,{"textbid":"","picbid":""},若不填则使用原来的反垃圾配置

返回参数

参数 类型 说明
code Integer 状态码
tid Long 云信服务器产生,群唯一标识
faccid String 入群失败的账号(accid)列表,如果创建时邀请的成员中存在加群数量超过限制的情况,会返回入群失败的 accid 以及附言(msg)

示例

请求示例(curl)

curlcurl -X POST -H "AppKey: go9dnk4*****03mgq3" -H "Nonce: 4tggg****323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'tname=%E6%88%91%E7%9A%84%E7%BE%A4&owner=zhangsan&members=%5B%22lisi%22%2C%22wangwu%22%5D&msg=%E8%AF%B7%E5%8A%A0%E7%BE%A4&magree=0&joinmode=0' 'https://api.netease.im/nimserver/team/create.action'

请求成功返回示例

json"Content-Type": "application/json; charset=utf-8"
{
    "code":200, 
    "tid":"11001" 
    "faccid":{  //如果创建时邀请的成员中存在加群数量超过限制的情况,会返回faccid
         "accid":["a","b","c"],  //用户accid
         "msg":"team count exceed"
     }
}

请求失败返回示例

"Content-Type": "application/json; charset=utf-8"
{
"code": 414,  // 参数错误
"desc": "owner not register" 
}

状态码

该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码

状态码 说明 处理建议
200 请求成功 -
403 禁止操作 群名等信息违规,未通过审查,请检查相关信息
414 参数错误 根据提示信息,检查传入参数的格式和限制条件
416 调用频率超出限制 降低访问频率
806 人数超过规定限制:
创建者加群数量超过限制(最大默认5000)或者创建群时群成员数超出限制(最大默认200)
根据对应提示信息做出处理
此文档是否对你有帮助?
有帮助
去反馈
  • 功能描述
  • API 使用限制
  • URL
  • 请求参数
  • 返回参数
  • 示例
  • 请求示例(curl)
  • 请求成功返回示例
  • 请求失败返回示例
  • 状态码