服务端HTTP接口

简介

服务端接口是聚联云聊天室提供给App后台的HTTP管理接口,其主要目的在于为App后台提供一个后台管理入口。

协议

App服务器请求采用HTTP POST方法+JSON的形式调用服务端接口,平台在鉴权、处理结束后通过HTTP+JSON的形式回复。

签名规则

App服务器每次在请求服务端接口时,均需要在HTTP Header中添加签名供平台校验。(具体请参考签名规则,其中AppKey和AppSecret由业务方在接入平台时获取保存)。若校验不通过,对应的HTTP返回码为401。

全球化服务

服务端接口全球化服务支持业务方对不同区域下的房间进行管理操作,因此在调用接口时,需要携带名为“RegionId”的HTTP Header。如果没有携带,会返回业务错误码2001。

例如查询东南亚地区的某些房间的在线人数: 请求url

http://ap-southeast.hummer.sunclouds.com/chatroom/v1/room/user-count

请求报文示例:

POST /chatroom/v1/room/user-count HTTP/1.1

Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{"room_ids":[1550646577,1550646578]}

现全球化支持的regionId如下:

地域名称机房所在城市Region IDapi域名(业务方所在区域就近调用)
中国深圳/无锡cncn.hummer.sunclouds.com
亚太东南雅加达/新加坡ap_southeastap-southeast.hummer.sunclouds.com
亚太南部孟买ap_southap-south.hummer.sunclouds.com
美国硅谷usus.hummer.sunclouds.com
中东东部迪拜me_eastme-east.hummer.sunclouds.com

接口列表

创建房间

  • 方法名: /chatroom/v1/room/create
  • 请求方法: POST
  • 请求参数
名称类型属性说明
operatorstring必填操作者uid
room_infoObject必填聊天室属性项
  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
room_idnumber房间号
  • HTTP 请求
POST /chatroom/v1/room/create HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{"operator":"1550646577", room_info: {"Name": "MyChatRoom", "Description": "", "Bulletin":"",  AppExtra:""}}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error",
  "room_id": 10646544
}

销毁房间

  • 方法名: /chatroom/v1/room/dismiss
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
  • HTTP 请求
POST /chatroom/v1/room/dismiss HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{"room_id": 10646544}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error"
}

房间踢人

  • 方法名: /chatroom/v1/room/kick-user
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
operatorstring必填操作者uid
uidstring必填被踢uid
reasonstring必填被踢原因
  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
  • HTTP 请求
POST /chatroom/v1/room/kick-user HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{"room_id": 10646544, "operator": "112233", "uid": "445566", "reason": "too much"}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error"
}

聊天室个人禁言

  • 方法名: /chatroom/v1/room/mute-user
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
operatorstring必填操作者uid
uidstring必填被禁言uid
reasonstring选填禁言原因
  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
  • HTTP 请求
POST /chatroom/v1/room/mute-user HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{"room_id": 10646544, "operator": "112233", "uid": "445566", "reason": "too much"}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error"
}

聊天室个人解除禁言

  • 方法名: /chatroom/v1/room/unmute-user
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
operatorstring必填操作者uid
uidstring必填被解除禁言uid
reasonstring选填解除禁言原因
  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
  • HTTP 请求
POST /chatroom/v1/room/unmute-user HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{"room_id": 10646544, "operator": "112233", "uid": "445566"}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error"
}

获取房间禁言列表

  • 方法名: /chatroom/v1/room/query-muted-users
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
muted_usersstring[]当前房间下的禁言uid列表
  • HTTP 请求
POST /chatroom/v1/room/query-muted-users HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{"room_id": 10646544 }
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error",
  "muted_users":["445566", "11223344"] 
}

批量查询房间在线人数

  • 方法名: /chatroom/v1/room/user-count
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idsnumber[]必填房间号列表。每次最多32个。
  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
roomid2cntObject每个房间号对应的人数消息。 real_count : 房间在线人数。virtual_count: 房间的虚拟人气值。

roomid2cnt字段的例子:

  "roomid2cnt": {
    "1550646577": {
      "real_count": 2,
      "virtual_count": 0
    },
    "1550646578": {
      "real_count": 0,
      "virtual_count": 0
    }
  }
  • HTTP 请求
POST /chatroom/v1/room/user-count HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{"room_ids":[1550646577,1550646578]}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error",
  "roomid2cnt": {
    "1550646577": {
      "real_count": 2,
      "virtual_count": 0
    },
    "1550646578": {
      "real_count": 0,
      "virtual_count": 0
    }
  }
}

查询房间在线成员列表

  • 方法名: /chatroom/v1/room/online-user-list
  • 请求方法: POST
  • 请求参数:
名称类型属性说明
room_idnumber必填房间号
cursornumber必填查询的游标,首次填0,后续填返回值中的cursor值
countnumber必填本次请求最多返回的成员数目
  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
cursornumber查询的游标
uidsstring[]在线成员列表

注意uid的类型是string。因为系统的uid为64位,超过了JSON中数字能表示的范围。

  • HTTP 请求
POST /chatroom/v1/room/online-user-list HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{room_id: 1550646577, cursor: 0, count: 500}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error",
  "cursor": 0,
  "uids": [
    "777",
    "4096038770"
  ]
}

添加或更新指定房间的属性

  • 方法名: /chatroom/v1/room/room-info/update
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
room_infoobject必填更新的房间信息
  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
  • HTTP 请求
POST /chatroom/v1/room/room-info/update HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{room_id: 1550646577, room_info: {"logo": "http://yy.com/xxx.jpg", "theme": "Silver"}}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": ""
}

查询指定房间的全部属性

  • 方法名: /chatroom/v1/room/room-info
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
room_infoobject房间全部属性
  • HTTP 请求
POST /chatroom/v1/room/room-info HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{room_id: 1550646577}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "",
  "infos": {
  "room_info": {
    "logo": "http://yy.com/xxx.jpg",
    "theme": "Silver"
  }
}

添加或更新用户的属性

  • 方法名: /chatroom/v1/room/user-info/update
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
uidstring必填更新目标uid
user_infoobject必填更新的用户信息

注意uid的类型是string。因为系统的uid为64位,超过了JSON中数字能表示的范围。

  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
  • HTTP 请求
POST /chatroom/v1/room/user-info/update HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{room_id: 1550646577, uid: "4096038770", user_info: {"logo": "http://yy.com/xxx.jpg", "nick": "helloworld_4096038770"}}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": ""
}

批量查询房间内用户属性

  • 方法名: /chatroom/v1/room/user-props
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
uidsstring[]必填在线成员列表。每次最多32个。

注意uid的类型是string。因为系统的uid为64位,超过了JSON中数字能表示的范围。

  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
infosobject每个用户的属性

infos返回的例子:

"infos" : {
  "4096038770": {
    "logo": "http://yy.com/xxx.jpg",
    "nick": "helloworld_4096038770"
  }
}
  • HTTP 请求
POST /chatroom/v1/room/user-props HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{room_id: 1550646577, uids: ["4096038770", "4096038771"]}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "",
  "infos": {
    "4096038770": {
      "logo": "http://yy.com/xxx.jpg",
      "nick": "helloworld_4096038770"
    }
  }
}

发送公屏消息

  • 方法名: /chatroom/v1/room/text-chat
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
uidstring必填发送者的uid
chatstring必填发送内容

注意uid的类型是string。因为系统的uid为64位,超过了JSON中数字能表示的范围。

  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
  • HTTP 请求
POST /chatroom/v1/room/text-chat HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{room_id: 1550646577, uid: "4096038770", chat: "Hello world!"}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error",
}

发送广播消息

  • 方法名: /chatroom/v1/room/send-broadcast
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
operatorstring必填发送者的uid
contentstring必填发送的内容

注意uid的类型是string。因为系统的uid为64位,超过了JSON中数字能表示的范围。

  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
  • HTTP 请求
POST /chatroom/v1/room/send-broadcast HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{room_id: 1550646577, operator: "4096038770", content: "Hello world!"}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error",
}

发送单播消息

  • 方法名: /chatroom/v1/room/send-unicast
  • 请求方法: POST
  • 请求参数
名称类型属性说明
room_idnumber必填房间号
operatorstring必填发送者的uid
receiverstring必填接收者的uid
contentstring必填发送的内容

注意uid的类型是string。因为系统的uid为64位,超过了JSON中数字能表示的范围。

  • 返回值
名称类型说明
res_codenumber返回码
res_msgstring返回信息
  • HTTP 请求
POST /chatroom/v1/room/send-unicast HTTP/1.1
Host: ap-southeast.hummer.sunclouds.com
Timestamp: 1541144032646
Nonce: 3432
AppId: 1350626568
RegionId: ap_southeast
Signature: ******************
Content-Type: application/json

{room_id: 1550646577, operator: "4096038770", receiver: "4096038771", content: "Hello world!"}
  • HTTP 回复
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8

{
  "res_code": 0,
  "res_msg": "no error",
}

聊天室保留的属性

名称类型描述
Namestring聊天室名称
Descriptionstring聊天室描述
Bulletinstring聊天室公告
AppExtrastring扩展字段:平台方透传,由业务定义
<