本文为您介绍AUI Kits语聊房场景的API说明。
登录
该接口客户可按自身业务需求实现,包括token的生成算法也是可以自定义,不过要确保生成及检验token使用相同的算法。
使用说明
请求协议:http/https
请求Path:/login
是否需要授权:否
请求Method:POST
请求ContentType:JSON
请求参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
username | String | 是 | usernamexxx | 用户名 |
password | String | 是 | passwordxxxx | 密码 |
返回数据
名称 | 类型 | 示例值 | 描述 | ||||
code | Integer | 200 | 业务响应码。参考HTTP响应码 | ||||
expire | String | 2023-02-28T14:38:06+08:00 | 过期时间。使用UTC时间格式 | ||||
token | String | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9*** | 授权凭证。默认使用jwt生成 |
示例
请求示例
{
"username":"usernamexxx",
"password":"passwordxxxx"
}
正常返回示例
{
"username":"usernamexxx",
"password":"passwordxxxx"
}
获取新IM建连的Token
使用说明
请求协议:http/https
请求Path:/api/chatroom/token
是否需要授权:是
请求Method:POST
请求ContentType:JSON
请求参数
名称 | 类型 | 是否必填 | 示例值 | 描述 |
user_id | String | 是 | useridxxxx | 用户UserId,用户自定义,在AppId下单独唯一。 |
role | String | 否 | admin | 角色,默认为空。为admin时,表示该用户可以调用管控接口。 |
返回数据
名称 | 类型 | 示例值 | 描述 | |
code | Integer | 200 | 业务响应码。参考HTTP响应码。 | |
aliyun_im | app_id | String | 用户的AppID。 | |
app_sign | String | 服务器生成的加密串,包含接入域名等信息。 | ||
app_token | String | 登录鉴权。 | ||
auth.user_id | String | 要登录的用户的ID。 | ||
auth.nonce | String | 格式:"AK-随机串",最长64字节。 | ||
auth.timestamp | Long | 过期时间,从1970到过期时间的秒数。 | ||
auth.role | String | 角色,为admin时,表示该用户可以调用管控接口。 |
示例
请求示例
{
"user_id": "useridxxxx",
"role":"admin"
}
正常返回示例
{
"code": 200,
"aliyun_im":{
"appid":"xxxx",
"appsign":"xxxx",
"apptoken":"xxxxxxxxxxxxxxxxxx",
"auth":{
"userid":"xxxx",
"nonce":"xxxxx", // 可为空
"timestamp":xxxxx,
"role":"admin"
}
}
}
创建聊天室
使用说明
请求协议:http/https
请求Path:/api/chatroom/create
是否需要授权:是
请求Method:POST
请求ContentType:JSON
请求参数
名称 | 类型 | 是否必填 | 示例值 | 描述 | |||
title | String | 是 | titlexxxx | 聊天室标题。 | |||
notice | String | 否 | noticexxx | 聊天室公告。 | |||
anchor | String | 是 | anchorxxxx | 群主userId。 | |||
anchor_nick | String | 否 | anchornickxxxx | 群主昵称。 | |||
extends | String | 否 | {"xx":"xxx"} | 扩展字段,SON格式字符串。 |
返回数据
名称 | 类型 | 示例值 | 描述 |
code | Integer | 200 | 业务响应码。参考HTTP响应码。 |
id | String | ee487235-5f9b-4cb3-82ce-45c91c3xxxx | 聊天室ID。 |
created_at | String | 2023-02-27T17:34:00.592750182+08:00 | 创建时间。 |
updated_at | String | 2023-02-27T17:34:00.592750182+08:00 | 修改时间。 |
title | String | titlexxx | 聊天室标题。 |
notice | String | noticexxx | 聊天室公告。 |
cover_url | String | 封面图。预留字段。 | |
anchor_id | String | anchor_idxxx | 群主userId。 |
anchor_nick | String | anchor_nickxxx | 群主昵称。 |
meetingInfo | String | {"xxx":"xxxx"} | 连麦信息。JSON字符串。 |
show_code | Integer | 65611075 | 房间号。 |
extends | String | {"xx":"xxx"} | 扩展字段。 |
status | Integer | 0 | 聊天室状态:
|
chat_id | String | ee487235-5f9b-4cb3-82ce-45c91c3xxxx | IM群ID。 |
示例
请求示例
{
"title": "titlexxx",
"notice": "noticexxx",
"anchor":"主播userId",
"anchor_nick":"主播nick",
"extends":"{\"xx\":\"xxx\"}"
}
正常返回示例
{
"code": 200,
"anchor_id": "主播userId",
"show_code": 65611075,
"extends": "{\"xx\":\"xxx\"}",
"updated_at": "2024-03-14T20:42:59",
"created_at": "2024-03-14T20:42:59",
"meetingInfo": "{\"members\":[{\"index\":1,\"joined\":false,\"user_id\":\"\"},{\"index\":2,\"joined\":false,\"user_id\":\"\"},{\"index\":3,\"joined\":false,\"user_id\":\"\"},{\"index\":4,\"joined\":false,\"user_id\":\"\"},{\"index\":5,\"joined\":false,\"user_id\":\"\"},{\"index\":6,\"joined\":false,\"user_id\":\"\"},{\"index\":7,\"joined\":false,\"user_id\":\"\"},{\"index\":8,\"joined\":false,\"user_id\":\"\"}]}",
"id": "cfa4a59e90ab42cbaf708f218ad1****",
"anchor_nick": "主播nick",
"title": "互动聊天测试",
"chat_id": "cfa4a59e90ab42cbaf708f218ad1****",
"notice": "23232",
"status": 1
}
分页获取聊天室列表
使用说明
请求协议:http/https
请求Path:/api/chatroom/list
是否需要授权:是
请求Method:POST
请求ContentType:JSON
请求参数
名称 | 类型 | 是否必填 | 示例值 | 描述 | |||
user_id | String | 否 | useridxxx | 用户UserId。 | |||
page_num | Integer | 是 | 1 | 页码,默认值:1。 | |||
page_size | Integer | 是 | 10 | 单页显示数量,默认值:10。 |
返回数据
名称 | 类型 | 示例值 | 描述 | ||||
code | Integer | 200 | 业务响应码。参考HTTP响应码。 | ||||
id | String | ee487235-5f9b-4cb3-82ce-45c91c3xxxx | 聊天室ID。 | ||||
created_at | String | 2023-02-27T17:34:00.592750182+08:00 | 创建时间。 | ||||
updated_at | String | 2023-02-27T17:34:00.592750182+08:00 | 修改时间。 | ||||
started_at | String | 2023-02-27T18:54:37+08:00 | 聊天室的开始时间。 | ||||
stopped_at | String | 2023-02-27T19:25:37+08:00 | 聊天室的结束时间。 | ||||
title | String | titlexxx | 聊天室标题。 | ||||
notice | String | noticexxx | 聊天室公告。 | ||||
cover_url | String | 封面图。预留字段。 | |||||
anchor_id | String | anchor_idxxx | 群主userId。 | ||||
anchor_nick | String | anchor_nickxxx | 群主昵称。 | ||||
meetingInfo | String | {"xxx":"xxxx"} | 连麦信息。JSON字符串。 | ||||
show_code | Integer | 65611075 | 房间号。 | ||||
metrics | jsonObject | 统计相关信息。 | |||||
metrics.online_count | Long | 20 | 聊天室在线人数。 | ||||
extends | String | {"xx":"xxx"} | 扩展字段。 | ||||
status | Integer | 0 | 聊天室状态:
| ||||
chat_id | String | ee487235-5f9b-4cb3-82ce-45c91c3xxxx | IM群ID。 |
示例
请求示例
{
"page_size": 10,
"page_num":1,
"user_id": "useridxxxx"
}
正常返回示例
{
"rooms": [
{
"id": "08a5d321d5f74d72bcbd87c5e41a57f4",
"title": "hhh的聊天室",
"status": 1,
"created_at": "2024-03-14T21:06:52",
"updated_at": "2024-03-14T21:06:52",
"extends": "{\n \"anchor_avatar\" : \"https:\/\/img.alicdn.com\/imgextra\/i2\/O1CN01VYKjf81Z1savmhLOr_!!6000000003135-0-tps-174-174.jpg\"\n}",
"chat_id": "08a5d321d5f74d72bcbd87c5e41a****",
"anchor_id": "hhh",
"anchor_nick": "hhh",
"show_code": 32611075,
"metrics": {
"online_count": 0
}
},
{
"id": "cfa4a59e90ab42cbaf708f218ad1****",
"title": "互动聊天测试",
"status": 1,
"notice": "23232",
"meetingInfo": "{\"members\":[{\"index\":1,\"join_time\":1710420349667,\"joined\":true,\"user_id\":\"assd\"},{\"index\":2,\"join_time\":1710420408513,\"joined\":true,\"user_id\":\"33334\"},{\"extends\":\"{\\\"nick\\\":\\\"xx33xx\\\",\\\"ava\\\":\\\"bb333bb\\\"}\",\"index\":3,\"join_time\":1710421936486,\"joined\":true,\"user_id\":\"333310\"},{\"index\":4,\"join_time\":1710420417941,\"joined\":true,\"user_id\":\"33335\"},{\"index\":5,\"join_time\":1710420423408,\"joined\":true,\"user_id\":\"33336\"},{\"index\":6,\"join_time\":1710420428932,\"joined\":true,\"user_id\":\"33337\"},{\"index\":7,\"join_time\":1710420436877,\"joined\":true,\"user_id\":\"33338\"},{\"index\":8,\"join_time\":1710420441424,\"joined\":true,\"user_id\":\"33339\"}]}",
"created_at": "2024-03-14T20:42:59",
"updated_at": "2024-03-14T20:42:59",
"extends": "{\"xx\":\"xxx\"}",
"chat_id": "cfa4a59e90ab42cbaf708f218ad1****",
"anchor_id": "主播userId",
"anchor_nick": "主播nick",
"metrics": {
"online_count": 0
}
},
{
"id": "cd6a4f31f3ad4593924c4081ddb9****",
"title": "admin的聊天室",
"status": 1,
"created_at": "2024-03-14T19:24:29",
"updated_at": "2024-03-14T19:24:29",
"chat_id": "cd6a4f31f3ad4593924c4081ddb9****",
"anchor_id": "admin",
"anchor_nick": "admin",
"show_code": 1612375,
"metrics": {
"online_count": 0
}
},
{
"id": "25f5346e1e1342289ebdf6c1ff92****",
"title": "admin的聊天室",
"status": 1,
"created_at": "2024-03-13T16:10:50",
"updated_at": "2024-03-13T16:10:50",
"chat_id": "25f5346e1e1342289ebdf6c1ff92****",
"anchor_id": "admin",
"anchor_nick": "admin",
"show_code": 1112375,
"metrics": {
"online_count": 0
}
}
],
"code": 200
}
获取单个聊天室
实现原理:参考/api/chatroom/list实现。该接口也会返回已解散的房间信息
使用说明
请求协议:http/https
请求Path:/api/chatroom/get
是否需要授权:是
请求Method:POST
请求ContentType:JSON
请求参数
名称 | 类型 | 是否必填 | 示例值 | 描述 | |||
id | String | 是 | liveIdxxxx | 聊天室ID。 | |||
user_id | String | 否 | useridxxx | UserID。 |
返回数据
参考/api/chatroom/list。只是将列表换为单个对象。
示例
请求示例
{
"id": "675e6783-0bac-4990-b6da-5aa89053****",
"user_id": "Cedric8"
}
正常返回示例
{
"code": 200,
"anchor_id": "主播userId",
"created_at": "2024-03-14T20:42:59",
"title": "互动聊天测试",
"chat_id": "cfa4a59e90ab42cbaf708f218ad1****",
"extends": "{\"xx\":\"xxx\"}",
"updated_at": "2024-03-14T20:42:59",
"meetingInfo": "{\"members\":[{\"index\":1,\"join_time\":1710420349667,\"joined\":true,\"user_id\":\"assd\"},{\"index\":2,\"join_time\":1710420408513,\"joined\":true,\"user_id\":\"33334\"},{\"extends\":\"{\\\"nick\\\":\\\"xx33xx\\\",\\\"ava\\\":\\\"bb333bb\\\"}\",\"index\":3,\"join_time\":1710421936486,\"joined\":true,\"user_id\":\"333310\"},{\"index\":4,\"join_time\":1710420417941,\"joined\":true,\"user_id\":\"33335\"},{\"index\":5,\"join_time\":1710420423408,\"joined\":true,\"user_id\":\"33336\"},{\"index\":6,\"join_time\":1710420428932,\"joined\":true,\"user_id\":\"33337\"},{\"index\":7,\"join_time\":1710420436877,\"joined\":true,\"user_id\":\"33338\"},{\"index\":8,\"join_time\":1710420441424,\"joined\":true,\"user_id\":\"33339\"}]}",
"id": "cfa4a59e90ab42cbaf708f218ad1****",
"show_code": 232275,
"metrics": {
"online_count": 0
},
"anchor_nick": "主播nick",
"notice": "23232",
"status": 1
}
获取 RTC token
使用说明
请求协议:http/https
请求Path:/api/chatroom/getRtcAuthToken
是否需要授权:是
请求Method:POST
请求ContentType:JSON
请求参数
名称 | 类型 | 是否必填 | 示例值 | 描述 | ||
room_id | String | 是 | chatroomIdxxxx | 聊天室ID。 | ||
user_id | String | 是 | useridxxxx | 用户UserId,用户自定义,在AppId下单独唯一。 |
返回数据
名称 | 类型 | 示例值 | 描述 | ||||
code | Integer | 200 | 业务响应码。参考HTTP响应码。 | ||||
authToken | String | ee487235-5f9b-4cb3-82ce-45c91c3xxxx | rtc token。 | ||||
timestamp | Long | 过期时间, 单位:秒。默认24小时有效。 |
示例
请求示例
{
"room_id": "675e6783-0bac-4990-b6da-5aa89053****",
"user_id": "useridxxxx"
}
正常返回示例
{
"code": 200,
"authToken": "xxxxx",
"timestamp": 12323XXXX
}
解散聊天室
使用说明
请求协议:http/https
请求Path:/api/chatroom/dismiss
是否需要授权:是
请求Method:POST
请求ContentType:JSON
请求参数
名称 | 类型 | 是否必填 | 示例值 | 描述 | ||
id | String | 是 | liveIdxxxx | 聊天室ID。 | ||
user_id | String | 是 | useridxxxx | 用户UserId,用户自定义,在AppId下单独唯一。 |
返回数据
名称 | 类型 | 示例值 | 描述 | |||||
success | bool | true | 是否成功。 |
示例
请求示例
{
"id": "675e6783-0bac-4990-b6da-5aa89053****",
"user_id": "useridxxxx"
}
正常返回示例
{
"code": 200,
"success": true
}
上麦
使用说明
请求协议:http/https
请求Path:/api/chatroom/joinMic
是否需要授权:是
请求Method:POST
请求ContentType:JSON
请求参数
名称 | 类型 | 是否必填 | 示例值 | 描述 | ||
id | String | 是 | liveIdxxxx | 聊天室ID。 | ||
user_id | String | 是 | useridxxxx | 用户UserId,用户自定义,在AppId下单独唯一。 | ||
index | Integer | 否 | 3 | 指定麦位,可不传。如果指定了麦位则尽量使用指定的麦位上麦,如果该麦位已有其他用户则选择可用的麦位上麦。 | ||
extends | String | 否 | {"user_avatrar":"xxxx"} | 扩展信息。内容可用端自定义。 |
返回数据
名称 | 类型 | 示例值 | 描述 | |||
code | Integer | 200 | 业务响应码。参考HTTP响应码。 | |||
members | Array | 麦上信息。 | ||||
[]members.user_id | String | |||||
[]members.joined | Boolean | true |
| |||
[]members.index | Integer | 3 | 麦位。 | |||
[]members.extends | String | {"user_avatrar":"xxxx"} | 扩展信息,JSON字符串。内容可用端自定义。 | |||
[]members.join_time | Long | 1710420349667 | 上麦时间。 |
示例
请求示例
{
"id": "d34e834e029f44eb92db5868ee93****",
"user_id": "bbb",
"extends":"{\"aaa\":\"bbb\"}"
}
正常返回示例
{
"code": 200,
"members": [
{
"user_id": "assd",
"joined": true,
"index": 1,
"join_time": 1710420349667
},
{
"user_id": "33334",
"joined": true,
"index": 2,
"join_time": 1710420408513
},
{
"extends": "{\"user_nick\":\"xx33xx\",\"user_avatrar\":\"bb333bb\"}",
"user_id": "333310",
"joined": true,
"index": 3,
"join_time": 1710421224316
},
{
"user_id": "33335",
"joined": true,
"index": 4,
"join_time": 1710420417941
},
{
"user_id": "33336",
"joined": true,
"index": 5,
"join_time": 1710420423408
},
{
"user_id": "33337",
"joined": true,
"index": 6,
"join_time": 1710420428932
},
{
"user_id": "33338",
"joined": true,
"index": 7,
"join_time": 1710420436877
},
{
"user_id": "33339",
"joined": true,
"index": 8,
"join_time": 1710420441424
}
]
}
异常说明
如果返回包括reason, 则表示有业务异常。此时需要通过reason来判断异常原因。
reason = 1: 表示麦位已满
{
"reason": 1,
"code": 200,
"desc": "麦位已满"
}
reason = 2: 表示用户已经上麦
{
"reason": 2,
"code": 200,
"desc": "用户已经上麦"
}
下麦
使用说明
请求协议:http/https
请求Path:/api/chatroom/leaveMic
是否需要授权:是
请求Method:POST
请求ContentType:JSON
请求参数
名称 | 类型 | 是否必填 | 示例值 | 描述 | ||
id | String | 是 | liveIdxxxx | 聊天室ID。 | ||
user_id | String | 是 | useridxxxx | 用户UserId,用户自定义,在AppId下单独唯一。 | ||
index | Integer | 是 | 3 | 指定要下麦的麦位。 |
返回数据
名称 | 类型 | 示例值 | 描述 | |||||
success | Boolean | true | 是否成功。 | |||||
members | Array | 麦上信息。 | ||||||
[]members.user_id | String | |||||||
[]members.joined | Boolean | true |
| |||||
[]members.index | Integer | 3 | 麦位。 | |||||
[]members.join_time | Long | 1710420349667 | 上麦时间。 |
示例
请求示例
{
"id": "cfa4a59e90ab42cbaf708f218ad1****",
"user_id": "333310",
"index":3
}
正常返回示例
{
"code": 200,
"members": [
{
"user_id": "assd",
"joined": true,
"index": 1,
"join_time": 1710420349667
},
{
"user_id": "33334",
"joined": true,
"index": 2,
"join_time": 1710420408513
},
{
"extends": "",
"user_id": "",
"joined": false,
"index": 3
},
{
"user_id": "33335",
"joined": true,
"index": 4,
"join_time": 1710420417941
},
{
"user_id": "33336",
"joined": true,
"index": 5,
"join_time": 1710420423408
},
{
"user_id": "33337",
"joined": true,
"index": 6,
"join_time": 1710420428932
},
{
"user_id": "33338",
"joined": true,
"index": 7,
"join_time": 1710420436877
},
{
"user_id": "33339",
"joined": true,
"index": 8,
"join_time": 1710420441424
}
]
}
获取连麦信息
使用说明
请求协议:http/https
请求Path:/api/chatroom/getMeetingInfo
是否需要授权:是
请求Method:POST
请求ContentType:JSON
请求参数
名称 | 类型 | 是否必填 | 示例值 | 描述 | |||
id | String | 是 | liveIdxxxx | 聊天室ID。 |
返回数据
名称 | 类型 | 示例值 | 描述 | |||||
success | Boolean | true | 是否成功。 | |||||
members | Array | 麦上信息。 | ||||||
[]members.user_id | String | |||||||
[]members.joined | Boolean | true |
| |||||
[]members.index | Integer | 3 | 麦位。 | |||||
[]members.join_time | Long | 1710420349667 | 上麦时间。 |
示例
请求示例
{
"id": "cfa4a59e90ab42cbaf708f218ad1****"
}
正常返回示例
{
"code": 200,
"members": [
{
"user_id": "assd",
"joined": true,
"index": 1,
"join_time": 1710420349667
},
{
"user_id": "33334",
"joined": true,
"index": 2,
"join_time": 1710420408513
},
{
"extends": "",
"user_id": "",
"joined": false,
"index": 3
},
{
"user_id": "33335",
"joined": true,
"index": 4,
"join_time": 1710420417941
},
{
"user_id": "33336",
"joined": true,
"index": 5,
"join_time": 1710420423408
},
{
"user_id": "33337",
"joined": true,
"index": 6,
"join_time": 1710420428932
},
{
"user_id": "33338",
"joined": true,
"index": 7,
"join_time": 1710420436877
},
{
"user_id": "33339",
"joined": true,
"index": 8,
"join_time": 1710420441424
}
]
}