API 参考
圈组

创建频道

更新时间: 2024/07/17 17:57:34

云信服务端支持创建频道。

功能介绍

频道(Channel)是具体信息通讯的发生地,用于承载服务器(即社群)的话题。以游乐场类比服务器,频道相当于游乐场中的游乐设施。有了服务器这个游乐场地,必须构建游乐设施才能给用户提供服务。

按查看模式(viewMode)来分,频道可分为公开频道和私密频道。

类型 说明

公开频道

  • 不在频道黑名单内的任意圈组服务器成员都能看到公开频道。
  • 支持配置黑名单控制访问权限。黑名单支持配置身份组所有成员或单个成员。

私密频道

  • 不在频道白名单内的任意圈组服务器成员都看不到私密频道。
  • 支持配置白名单,控制对谁可见。白名单支持配置所有身份组成员和单个成员。

支持黑白名单相关操作的服务端 API,参见修改频道黑白名单成员修改频道黑白名单身份组

使用限制

单个服务器的频道数量上限默认为 100 个。

可在云信控制台配置单个服务器的频道数量上限。(在云信控制台选择应用,进入IM 即时通讯 > 功能配置 > 圈组 > 子功能配置 > 单server可创建的channel数即可配置。)

调用时机

频道需要在服务器内创建。调用创建频道接口前,请确保圈组内已经创建了服务器(通过各端 SDK API 或服务端 API)。

URL

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

请求参数

  • POST 请求中 Headers 的设置请参考API调用方式

  • POST 请求中 Body 的设置如下:

参数
类型
必须
说明
accidString操作者的 IM 帐号
serverIdLong服务器 ID
typeString频道类型:
  • 0-消息频道
  • 1-实时互动频道(需要在控制台开通该功能,否则创建会报 403 错误)
  • 100-自定义频道

传入其他值将其它返回 414 状态码

nameString频道名称,长度上限 64 字符
topicString频道主题,长度上限 64 字符
customString频道自定义扩展字段,长度上限 1024 字符
viewModeString查看模式:0-公开(默认),1-私密。
categoryIdString频道分组 ID。如传入 0 则表示当前频道不属于任何频道分组。
syncModeString频道与所在的频道分组是否同步数据
  • 0-不与分组同步模式(默认)
  • 1-与分组同步模式
设置为同步后,如果频道的查看模式、黑白名单、身份组权限等被修改,将自动改为不同步。
visitorModeint频道是否对游客可见
  • 0:对游客可见
  • 1:对游客不可见
  • 2:跟随模式(默认),即如果该频道的查看模式(viewMode)被设置为“公开”则该频道对游客可见,如果被设置为“私密”则对游客不可见
  • 如果频道的 visitorMode 为跟随模式,且同步模式(syncMode)为“与频道分组同步”,则当该频道所属的频道分组的查看模式(viewMode)变更后,该频道对游客的可见性也将变更。例如,在这种情况下,频道分组的查看模式由公开变为私密,则此时该频道对游客从“可见”变为“不可见”。
  • 游客相关功能介绍,请参见游客功能
bidString

安全通的自定义反垃圾(即内容审核)业务的 ID。自定义反垃圾业务主要用来针对圈组的资料信息进行除了默认反垃圾业务以外的内容审核开通安全通后,云信控制台会自动生成默认反垃圾业务。您的应用不需要配置业务 ID 就能默认采用安全通的默认反垃圾业务,如果需要自定义反垃圾业务,请先通过云信官网首页提供的微信、在线聊天和电话等方式跟商务经理发出申请,获取对应的业务 ID。

返回参数

参数 说明
code 状态码
channelInfo 创建的频道,具体字段见下表
channelInfo 字段
类型
说明
owner String 服务器所有者(即创建者)
validFlag int 有效标志:0-无效,1-有效。如果频道已被删除则为无效
reorderweight String 自定义排序权重值,频道自定义排序权重配置相关说明请参见修改频道自定义排序权重值
custom String 自定义字段
updateTime long 频道信息更新时间
type int 频道类型:0-消息频道,1-实时互动频道,100-自定义频道
viewMode int 频道的查看模式:0-公开,1-私密
visitorMode int 频道是否对游客可见,0:对游客可见,1:对游客不可见,2:跟随模式(默认),具体见上文的请求参数
serverId String 频道所属服务器的ID
createTime long 频道创建时间
name String 频道名称
syncMode int 频道与所在的频道分组是否同步数据,0-不与分组同步(默认),1-与分组同步。
topic String 频道主题
channelId long 频道唯一标识
categoryId long 频道分组唯一标识

示例

cURL 请求示例

curlcurl -X POST -H "AppKey: go9dnk49***w0803mgq3" -H "Nonce: 4tggge**323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=zhangsan&serverId=1513535&type=0' 'https://api.netease.im/nimserver/qchat/createChannel.action'

返回示例

http 响应:json

json"Content-Type": "application/json; charset=utf-8"
{
    "code":200,
    "channelInfo":{
        "owner": "test",
        "validFlag": 1,
        "reorderweight": 0,
        "custom": null,
        "updateTime": 1663759233016,
        "type": 1,
        "viewMode": 0,
        "visitorMode": 0,
        "serverId": 1460012,
        "createTime": 1663746443592,
        "name": "testname",
        "syncMode": 0,
        "topic": "test",
        "channelId": 1836129,
        "categoryId": 0
    }
}

状态码

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

状态码 说明 处理建议
200 请求成功 -
403 非法操作或没有权限
  • 检查是否已开通圈组功能
  • 检查是否拥有相应的权限,如频道管理权限
  • 检查频道信息中是否包含违规或敏感内容。如果已开通安全通且被检测到存在违规或敏感信息,可能会被安全通的内容审核判定为“不通过”
404 对象不存在
  • 检查是否存在必传参数为空的问题
  • 检查传入的账号、服务器 ID 或自定义反垃圾业务 ID (bid)是否存在
414 参数错误 根据提示信息,检查传入参数的格式和限制条件
416 调用频率超限 降低调用频率
431 HTTP 重复请求 -
此文档是否对你有帮助?
有帮助
去反馈
  • 功能介绍
  • 使用限制
  • 调用时机
  • URL
  • 请求参数
  • 返回参数
  • 示例
  • cURL 请求示例
  • 返回示例
  • 状态码