文档

API说明

更新时间:

本文为您介绍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

聊天室状态:

  • 1:已开始

  • 2:已停止

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

聊天室状态:

  • 1:正常

  • 2:解散

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

  • true表示已上麦。

  • false表示未上麦。

[]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

  • true表示已上麦。

  • false表示未上麦。

[]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

  • true表示已上麦。

  • false表示未上麦。

[]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
        }
    ]
}