服务端集成

本文档已不再维护。

直播聊天室提供REST API形式的管理接口，下面是关于服务端直播聊天室的管理功能说明。

环信直播聊天室是基于环信REST聊天室服务开发的针对直播场景的直播聊天室服务，直播聊天室服务端已开源，仓库链接：环信直播聊天室服务端

可将该服务部署到自己的服务器，进行直播聊天室的集成。环信服务器部署的“easemob-im-app-server”服务，使用的appkey为easemob-demo#chatdemoui，仅作为“直播聊天室demo”的服务端使用。

服务端接口请求都需要设置Request Headers:

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

token获取方式请参考：用户体系集成

聊天室

即环信的聊天室功能，每一个直播聊天室，都唯一对应一个聊天室（反过来不成立）。直播聊天室复用了对应聊天室的所有资源，包括聊天室的成员列表等。

强烈不建议调用解散聊天室接口。将直播聊天室对应的聊天室解散，这将导致该直播聊天室不可使用。

关于聊天室REST API，请参考聊天室管理。

直播聊天室

直播聊天室对聊天室进行了包装，复用了聊天室的所有数据，并增加了直播场景特有的属性，如直播聊天室封面URL、直播状态、场次ID等，具体如下：

属性名称	类型	描述
id	String	直播聊天室ID，即对应的聊天室 ID，聊天室唯一标识符，创建直播间时由环信服务器生成返回。
name	String	直播聊天室名称，即对应的聊天室名称，任意字符串。
description	String	直播聊天室描述，即对应的聊天室描述，任意字符串。
maxusers	Integer	直播聊天室成员上限，即对应的聊天室成员上限，创建聊天室的时候设置，可修改。
affiliations_count	Integer	现有成员总数。因聊天室成员离线2分钟自动离开聊天室，故也可认为当前在线人数。
owner	String	直播聊天室主播的username，也是对应聊天室的所有者。例如：{“owner”: “13800138001”}。
cover	String	直播聊天室封面Url。
status	String	直播状态，未直播：offline，直播中：ongoing
showid	String	当前直播场次ID，初始值为0，每开始一场直播，场次ID自增1。
ext	Map	直播聊天室自定义属性
affiliations	Array	现有成员列表，包含了 owner 和 member。例如： “affiliations”:[{“owner”: “13800138001”},{“member”:”v3y0kf9arx”},{“member”:”xc6xrnbzci”}]。

直播场次

直播聊天室是以直播场次为基本单位的。每开始一场新的直播，直播聊天室详情中的场次ID会自增1。可以基于该场次ID记录每场直播的统计信息。

直播聊天室的直播状态：ongoing：正在直播中；offline：未直播。

限制条件：

1、每开始一场直播，直播间的当前状态必须是offline，或者当前直播聊天室主播已离线（该策略主要是为了避免，当主播未正确关闭直播聊天室的直播状态，导致直播聊天室无法被其他主播使用）。如当前状态是ongoing，且当前主播在线，则不允许重新开始一场直播。

2、用户进入一个未在直播的直播聊天室，并成功开始一场直播，则该用户成为该直播聊天室的主播。

主播

直播聊天室的主播，与该直播聊天室对应聊天室的群主是同一人。一个直播聊天室只能有一个主播。

直播聊天室管理

创建直播聊天室

调用说明

HTTP Method: POST
Path: /appserver/liverooms

权限要求

app管理员

请求字段说明

属性名称	类型	是否必选	描述
name	String	是	直播聊天室名称，即对应的聊天室名称，任意字符串。
description	String	否	直播聊天室描述，即对应的聊天室描述，任意字符串。
maxusers	Integer	否	直播聊天室成员上限，即对应的聊天室成员上限，创建聊天室的时候设置，可修改。
owner	String	是	直播聊天室主播的username，也是对应聊天室的所有者。例如：{“owner”: “13800138001”}。
members	Array	否	直播间成员，此属性为可选的，但是如果加了此项，数组元素至少一个
cover	String	否	直播聊天室封面Url。
ext	Map	否	直播聊天室自定义属性

API示例

请求：

curl -X POST http://localhost:8080/appserver/liverooms -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8_bc0eAAAAAAAA' -H 'Content-Type: application/json' -d '{"name":"test1","description":"server create chatroom","maxusers":300,"owner":"hxtest1","cover":"http://172.0.0.1:8080/cover/pictiure"}'

响应：

{
    "id": "107776865009665",
    "name": "test1",
    "description": "server create chatroom",
    "owner": "hxtest1",
    "created": 1582182428511,
    "mute": false,
    "cover": "http://172.0.0.1:8080/cover/pictiure",
    "status": "offline",
    "showid": 0,
    "maxusers": 300,
    "affiliations_count": 1,
    "affiliations": [
        {
            "owner": "hxtest1"
        }
    ]
}

获取直播聊天室详情

调用说明

HTTP Method: GET
Path: /appserver/liverooms/{liveroomid}

权限要求

app user

API示例

请求：

curl -X GET http://localhost:8080/appserver/liverooms/107776865009665 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8_bc0eAAAAAAAA' -H 'Content-Type: application/json'

响应：

{
    "id": "107776865009665",
    "name": "test1",
    "description": "server create chatroom",
    "owner": "hxtest1",
    "created": 1582182428511,
    "mute": false,
    "cover": "http://172.0.0.1:8080/cover/pictiure",
    "status": "offline",
    "showid": 0,
    "maxusers": 300,
    "affiliations_count": 1,
    "affiliations": [
        {
            "owner": "hxtest1"
        }
    ]
}

修改直播聊天室

调用说明

HTTP Method: PUT
Path: /appserver/liverooms/{liveroomId}

权限要求

app管理员，当前直播聊天室的主播

可修改字段说明

属性名称	类型	描述
name	String	直播聊天室名称，即对应的聊天室名称，任意字符串。
description	String	直播聊天室描述，即对应的聊天室描述，任意字符串。
maxusers	Integer	直播聊天室成员上限，即对应的聊天室成员上限。
cover	String	直播聊天室封面Url。
ext	Map	直播聊天室自定义属性

API示例

请求：

curl -X PUT http://localhost:8080/appserver/liverooms/107776865009665 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8_bc0eAAAAAAAA' -H 'Content-Type: application/json' -d '{"name":"test1","maxusers":1000,"owner":"hxtest1","cover":"http://172.0.0.1:8080/cover"}'

响应：

{
    "id": "108144876388353",
    "name": "test1",
    "description": "nothing left here",
    "owner": "hxtest1",
    "created": 1582533391279,
    "cover": "http://177.0.0.1:8080/cover",
    "status": "offline",
    "showid": 0,
    "affiliations_count": 1
}

分页获取直播聊天室列表

调用说明

HTTP Method: GET
Path: /appserver/liverooms

权限要求

app user

接口参数

属性名称	类型	描述
limit	int	不设置该参数则默认为10，可选项。
cursor	String	分页返回的游标，可获取下一页数据。获取第一页则不设置。

API示例

请求：

curl -X GET http://localhost:8080/appserver/liverooms?limit=2&cursor=107776865009666 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8_bc0eAAAAAAAA' -H 'Content-Type: application/json'

响应：

{
    "entities": [
        {
            "id": "107741231251457",
            "name": "test1",
            "owner": "hxtest1",
            "status": "ongoing",
            "showid": 1,
            "affiliations_count": 1
        },
        {
            "id": "107776865009665",
            "name": "test1",
            "owner": "hxtest1",
            "cover": "http://177.0.0.1:8080/cover/pictiure",
            "status": "offline",
            "showid": 0,
            "affiliations_count": 1
        }
    ],
    "count": 2,
    "cursor": "107777290731521"
}

分页获取正在直播的直播聊天室列表

调用说明

HTTP Method: GET
Path: /appserver/liverooms/ongoing

权限要求

app user

接口参数

属性名称	类型	描述
limit	int	不设置该参数则默认为10，可选项。
cursor	String	分页返回的游标，可获取下一页数据。获取第一页则不设置。

API示例

请求：

curl -X GET http://localhost:8080/appserver/liverooms/ongoing?limit=2&cursor=107776865009666 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8_bc0eAAAAAAAA' -H 'Content-Type: application/json'

响应：

{
    "entities": [
        {
            "id": "107741231251457",
            "name": "test1",
            "owner": "hxtest1",
            "status": "ongoing",
            "showid": 1,
            "affiliations_count": 1
        },
        {
            "id": "107776865009665",
            "name": "test1",
            "owner": "hxtest1",
            "cover": "http://177.0.0.1:8080/cover/pictiure",
            "status": "ongoing",
            "showid": 1,
            "affiliations_count": 1
        }
    ],
    "count": 2,
    "cursor": "107777290731521"
}

开始直播

调用说明

HTTP Method: POST
Path: /appserver/liverooms/{liveroomId}/users/{username}/ongoing

接口说明

开启直播。开始直播的前提：1、直播聊天室当前状态是未直播的状态；2、直播聊天室当前状态是正在直播，但主播离线，此时其他用户可进入直播间进行直播。否则返回403错误码。

权限要求

app user

API示例

请求：

curl -X POST http://localhost:8081/appserver/liverooms/107780133421057/users/hxtest1/ongoing -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应：

{
    "id": "107780133421057",
    "name": "test1",
    "description": "server create chatroom",
    "owner": "hxtest1",
    "created": 1582185545093,
    "mute": false,
    "cover": "http://172.0.0.1:8080/cover/pictiure",
    "status": "ongoing",
    "showid": 4,
    "maxusers": 300,
    "affiliations_count": 1,
    "affiliations": [
        {
            "owner": "hxtest1"
        }
    ]
}

结束直播

调用说明

HTTP Method: POST
Path: /appserver/liverooms/{liveroomId}/users/{username}/offline

接口说明

结束直播。结束直播条件：需要是直播聊天室主播，且直播聊天室当前直播状态是正在直播，可结束直播。否则返回403错误码。

权限要求

直播聊天室主播

API示例

请求：

curl -X POST http://localhost:8081/appserver/liverooms/107780133421057/users/hxtest1/offline -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应：

{
    "id": "107780133421057",
    "name": "test1",
    "owner": "hxtest1",
    "cover": "http://177.0.0.1:8080/cover/pictiure",
    "status": "offline",
    "showid": 4,
    "affiliations_count": 1
}

删除直播聊天室

调用说明

HTTP Method: DELETE
Path: /appserver/liverooms/{liveroomId}

权限要求

直播聊天室主播

API示例

请求：

curl -X DELETE http://localhost:8081/appserver/liverooms/107780133421057 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应：

{
    "id": "107780133421057",
    "name": "test1",
    "description": "server create chatroom",
    "owner": "hxtest1",
    "created": 1583320857682,
    "cover": "http://172.0.0.1:8080/cover/pictiure",
    "status": "offline",
    "showid": 0,
    "affiliations_count": 1
}

转让直播聊天室

调用说明

HTTP Method: PUT
Path: /appserver/liverooms/{liveroomId}/owner/{newOwner}

权限要求

直播聊天室主播

API示例

请求：

curl -X PUT http://localhost:8081/appserver/liverooms/107780133421057/owner/hxtest2 -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应：

{
    "id": "107780133421057",
    "name": "test1",
    "description": "server create chatroom",
    "owner": "hxtest2",
    "created": 1583320900413,
    "cover": "http://172.0.0.1:8080/cover/pictiure",
    "status": "offline",
    "showid": 0,
    "affiliations_count": 1
}

推拉流管理

获取推流地址

调用说明

HTTP Method: GET
Path: /appserver/streams/url/publish

权限要求

app用户

请求参数说明

属性名称	类型	是否必选	描述
domain	String	否	推流域名，未设置则取服务中的默认值
hub	String	否	直播空间名，未设置则取服务中的默认值
streamKey	String	是	流名
expire	Integer	否	获取推流url过期时间，单位为秒，默认600秒后过期

API示例

请求：

curl -X GET 'http://localhost:8080/appserver/streams/url/publish?domain=pili-publish.shenchong.com&hub=shenchong-liveroom&streamKey=hxtest1' -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应：

{
    "data": "rtmp://pili-publish.shenchong.com/shenchong-liveroom/hxtest1?e=1589261045&token=xxx:CSErrjZukoIVxBuwlTT0LWcwVF8="
}

获取直播流播放地址

调用说明

HTTP Method: GET
Path: /appserver/streams/url/play

权限要求

app用户

请求参数说明

属性名称	类型	是否必选	描述
domain	String	否	播放域名，未设置则取服务中的默认值
hub	String	否	直播空间名，未设置则取服务中的默认值
streamKey	String	是	流名
protocol	String	否	播放协议，默认为rtmp；可选的三个值为：rtmp，hls，hdl

API示例

请求：

curl -X GET 'http://localhost:8080/appserver/streams/url/play?domain=pili-publish.shenchong.com&hub=shenchong-liveroom&streamKey=hxtest1' -H 'Authorization: Bearer YWMtVPHfHCeREeqZiOl8' -H 'Content-Type: application/json'

响应：

{
    "data": "rtmp://pili-publish.shenchong.com/shenchong-liveroom/hxtest1"
}

管理员/禁言/黑名单/白名单

对直播聊天室的管理员、禁言、黑名单、白名单等操作，即为对该直播间对应的聊天室的相关操作，直接调用该聊天室的接口即可。聊天室管理

上一页：产品介绍

下一页：Android客户端集成

服务端集成

服务端介绍

Request Headers

聊天室

直播聊天室

直播场次

主播

REST API介绍

直播聊天室管理

创建直播聊天室

调用说明

权限要求

请求字段说明

API示例

获取直播聊天室详情

调用说明

权限要求

API示例

修改直播聊天室

调用说明

权限要求

可修改字段说明

API示例

分页获取直播聊天室列表

调用说明

权限要求

接口参数

API示例

分页获取正在直播的直播聊天室列表

调用说明

权限要求

接口参数

API示例

开始直播

调用说明

接口说明

权限要求

API示例

结束直播

调用说明

接口说明

权限要求

API示例

删除直播聊天室

调用说明

权限要求

API示例

转让直播聊天室

调用说明

权限要求

API示例

推拉流管理

获取推流地址

调用说明

权限要求

请求参数说明

API示例

获取直播流播放地址

调用说明

权限要求

请求参数说明

API示例

管理员/禁言/黑名单/白名单