Talk RestAPI

实时语音Talk SDK配套的服务器API，适合业务服务器调用。用于房间管理。

公共部分

请求URL

REST API的格式

https://api.youme.im/$ver/$servicename/$command?
appkey=$appkey&
identifier=$identifier&
curtime=$curtime&
checksum=$checksum

参数说明
ver：协议版本号，固定为v1。
servicename：内部服务器名，不同的servicename对应不同的服务器类型，目前值为im。
command：api接口命令字，与servicename组合标识具体的业务功能，详见各api描述。
appkey：app在游密通信云注册申请的appkey,可在游密后台进行查看。
identifier：用户名，调用REST API一般为app管理员账号。
curtime：当前UTC时间戳，从1970年1月1日0点0分0秒开始到现在的秒数(string类型)。
checksum:sha1(appsecret + curtime)，两个参数拼接的字符串，进行sha1计算，转化成16进制字符(string，小写)。其中appsecret可在游密后台进行查看。
注：
checksum有效期：出于安全考虑，每个checksum有效期为5分钟，建议每次请求都生成新的checksum，同时服务器进行NTP同步时间。

HTTP请求包体格式

REST API仅支持POST方法，其请求包体为JSON格式，具体的包体格式参见每个API的详细描述。需要特别注意的是，POST包体不能为空，即使某条协议包体中不需要携带任何信息，也需要携带一个空的JSON对象，即{}。

HTTP返回码

除非发生网络错误（例如502错误），REST API的调用结果均为200，真正的API调用错误码与错误信息是在HTTP应答包体中返回的。

HTTP应答包体格式

REST API的应答包体也是JSON格式，其格式符合如下特征：

{
    "ActionStatus": "OK" // OK表示处理成功，FAIL表示失败
    "ErrorCode": 0,      // 0为成功，其它为失败
    "ErrorInfo": "",     // 失败的情况下，会有描述
    // REST API其他应答内容
}

应答包体中包含ActionStatus、ErrorInfo、ErrorCode三个属性，其含义如下：

错误码	响应串	含义描述
ActionStatus	String	请求处理的结果，OK表示处理成功，FAIL表示失败
ErrorInfo	String	失败原因
ErrorCode	Integer	错误码，0为成功，其他为失败，可查询错误码表得到具体的原因

房间管理

获取Talk频道内的在线人数

根据频道ID查询主播用户所在频道内的在线用户数。

请求URL

https://api.youme.im/v1/im/query_talk_channel_user_count?appkey=123456789&identifier=admin&curtime=123456789&checksum=123456789abcdefg

header
```
Content-Type: application/json
```
body
```
{
"ChannelID": "12345"
}
```
body为json格式，各个字段解释如下：
ChannelID ：用户所在Talk频道ID，字符串。
响应
响应指示设置是否成功。
```
{
"ChannelID": "12345",
"UserCount": 36
}
```
UserCount ：查询到的该频道内的在线人数。

获取Talk某频道用户列表

根据游戏ID和频道ID，查询该频道内的所有用户ID。

请求URL

https://api.youme.im/v1/im/get_talk_user_list_on_a_channel?appkey=123456789&identifier=admin&curtime=123456789&checksum=123456789abcdefg

header
```
Content-Type: application/json
```
body
```
{
" AppID": 1000,
"ChannelID":"1234"
}
```
AppID 游戏ID，整数。
ChannelID 频道ID，app内唯一，字符串。

响应

{
"AppID": 1000,
"ChannelID": "1234",
"Total": 2,
"UserList": [
    {
        "UserID": "u#123"
    },
    {
        "UserID": "u#345"
    }
]
}

查询指定游戏的Talk频道列表

根据游戏ID，查询该游戏当前的所有频道ID。

请求URL

https://api.youme.im/v1/im/get_talk_channel_list?appkey=123456789&identifier=admin&curtime=123456789&checksum=123456789abcdefg

header
```
Content-Type: application/json
```
body
```
{
"AppID": 1000
}
```
body为json格式，各个字段解释如下：
AppID: 游戏ID，整数，必选字段。

响应

{
"AppID": 1000,
"Total": 2,
"ChannelList": [
    {
        "ChannelID": "ch123",
        "UserCount": 12
    },
    {
        "ChannelID": "ch345",
        "UserCount": 5
    }
]
}

踢出指定游戏指定Talk频道的用户

根据游戏ID、频道ID和用户ID，踢出该频道内的指定用户。

请求URL

https://api.youme.im/v1/im/admin_kick_user?appkey=123456789&identifier=admin&curtime=123456789&checksum=123456789abcdefg

header
```
Content-Type: application/json
```
body
```
{
"app_id": 1000,
"channel_id": "ch345",
"kick_user_id": "u#456",
"kick_time": 6000, 
"op_user": "op_user"
}
```
app_id: 游戏ID，整数，必选字段。
channel_id: 频道ID，字符串，必选字段。
kick_user_id: 要踢出的用户游戏ID，字符串，必选字段。
kick_time: 要将该用户踢出频道的时长，单位s，整数。
op_user: 操作人，登记该踢出动作的执行人，字符串。

响应

{
"ActionStatus": "OK",
"ErrorCode": 0,
"ErrorInfo": "",
}

查询指定游戏的Talk频道状态

根据游戏ID、频道ID，查询该频道目前的状态，状态包括不存在、空闲、会议中三种。

请求URL

https://api.youme.im/v1/im/query_talk_channel_status?appkey=123456789&identifier=admin&curtime=123456789&checksum=123456789abcdefg

header
```
Content-Type: application/json
```
body
```
{
"AppID": 1000,
"ChannelID": "ch345"
}
```
AppID: 游戏ID，整数，必选字段。
ChannelID: 频道ID，字符串，必选字段。
响应
```
{
"AppID": 1000,
"ChannelID": "ch345",    
"Status": 1,
}
```
其中状态Status的取值含义是1（不存在）、2（空闲，频道人数是0）、3（会议中，频道人数大于0）。

查询指定游戏的Talk用户状态

根据游戏ID、游戏用户ID，查询该用户目前的状态信息。

请求URL

https://api.youme.im/v1/im/query_talk_user_status?appkey=123456789&identifier=admin&curtime=123456789&checksum=123456789abcdefg

header
```
Content-Type: application/json
```
body
```
{
"AppID": 1000,
"UserID": "u#123"
}
```
AppID: 游戏ID，整数，必选字段。
UserID: 游戏用户ID，字符串，必选字段。
响应
```
{
"AppID": 1000,
"UserID": "u#123",
"Status": [
    {
       "ChannelID": "ch345",
       "UseVideo": 1,
       "UseAudio": 1,
       "VideoFrameRate": 15,
       "VideoBitRate": 470,
       "AudioBitRate": 192
    }
]
}
```
响应中的ChannelID是用户当前的频道ID，UseVideo标识是否使用视频（1在使用，0未使用），UseAudio标识是否使用音频（1在使用，0未使用），VideoFrameRate是视频帧率（单位fps），VideoBitRate和AudioBitRate分别是视频、音频的码率（单位kbps）。

查询指定游戏的Talk用户的通话记录

根据游戏ID、游戏用户ID和日期，查询该用户的通话记录。

请求URL

https://api.youme.im/v1/im/query_talk_user_call?appkey=123456789&identifier=admin&curtime=123456789&checksum=123456789abcdefg

header
```
Content-Type: application/json
```
body
```
{
"AppID": 1000,
"UserID": "u#123",
"QueryDate": 20171124,
"StartSeq": 0,
"Limit": 10
}
```
AppID: 游戏ID，整数，必选字段。
UserID: 游戏用户ID，字符串，必选字段。
QueryDate: 查询日期，整数，格式为YYYYMMDD，必选字段。
StartSeq: 起始序号，整数，默认是0，可选字段。
Limit: 一次限制返回的条数，整数，默认1，最大100，可选字段。
响应
```
{
"AppID": 214,
"UserID": "u#123",
"Call": [
    {
        "ChannelID": "ch345",
        "JoinTime": 1511489108,
        "LeaveTime": 1511489540,
        "CallDuration": 432
    }
]
}
```
响应中的ChannelID是用户通话时的频道ID，JoinTime是加入该频道的时间（UTC时间戳），LeaveTime是离开频道的时间（UTC时间戳），CallDuration是通话时长（单位s）。

查询Talk频道上麦用户列表

根据Talk频道ID，查询该频道里的上麦的用户。

请求URL

https://api.youme.im/v1/im/get_talk_speaker_list_on_a_channel?appkey=123456789&identifier=admin&curtime=123456789&checksum=123456789abcdefg

header
```
Content-Type: application/json
```
body
```
{
"ChannelID": "ch123"
}
```
AppID: 游戏ID，整数，可选字段，当不传入时，则取请求的AppKey所对应的AppID。
ChannelID: 频道ID，字符串，必选字段。

响应

{
"AppID": 1000,
"ChannelID": "ch123",
"Total": 2,
"UserList": [
    {
        "UserID": "u#123"
    },
    {
        "UserID": "u#345"
    }
]
}

向Talk频道发送文本消息

根据Talk频道ID，向该频道内的用户发送文本消息。

请求URL

https://api.youme.im/v1/im/push_mcu_msg?appkey=123456789&identifier=admin&curtime=123456789&checksum=123456789abcdefg

header
```
Content-Type: application/json
```
body
```
{
"meeting_id": "12345",
"user_id": "admin",
"receiver_id": "",
"content":"测试消息222"
}
```
meeting_id: 频道ID，字符串，必选字段，消息要发往的频道。
user_id: 用户ID，字符串，可选字段，透传给客户端，标记发送消息的用户，如“admin”。
receiver_id: 如为""，则广播给频道内所有用户，若为指定用户，则发送给指定用户。
content: 消息内容，字符串，必选字段，长度不要超过2048字节。
响应
无特殊响应字段。

房间内用户身份切换

切换频道内用户用户身份。

请求URL

https://api.youme.im/v1/im/change_user_ Identity?appkey=123456789&identifier=admin&curtime=123456789&checksum=123456789abcdefg

header
```
Content-Type: application/json
```
body
```
{
"ChannelID": "12345"，
"UserID": "leef",
“IdentityType”:  1 ,
“RequstId”:  1591177759251
}
```
UserID: 用户ID，字符串，必选字段。
ChannelID: 频道ID，字符串，必选字段。
IdentityType: 身份类型，整形，必选字段（1 自由讲话者， 2 需要通过抢麦等请求麦克风权限之后才可以讲话， 3听众， 4 指挥， 5主播， 6 嘉宾）。
RequstId: 请求唯一ID，整形(递增)，可选字段。
响应
```
{
"ChannelID": "12345"，
"UserID": "leef",
“ResponetId”:  1591177759251,
“Code”: 0
}
```
UserID: 用户ID，字符串，必选字段。
ChannelID: 频道ID，字符串，必选字段。
ResponetId: 对应请求唯一ID（RequstId），整形(递增)，可选字段。
code: 处理结果状态码，整形。code 含义：
0 处理成功，
401 频道不存在，
402 用户不存在，
403 请求ID小于已经处理的请求，
500 服务器错误。

语言

Talk服务器RestAPI

Talk服务器RestAPI

Talk RestAPI

公共部分

请求URL

HTTP请求包体格式

HTTP返回码

HTTP应答包体格式

房间管理

获取Talk频道内的在线人数

获取Talk某频道用户列表

查询指定游戏的Talk频道列表

踢出指定游戏指定Talk频道的用户

查询指定游戏的Talk频道状态

查询指定游戏的Talk用户状态

查询指定游戏的Talk用户的通话记录

查询Talk频道上麦用户列表

向Talk频道发送文本消息

房间内用户身份切换