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

快速接入

使用指南

API手册

场景方案

状态码

常见问题

异常处理

服务器RestAPI

Talk RestAPI

公共部分

请求URL

HTTP请求包体格式

HTTP返回码

HTTP应答包体格式

房间管理

获取Talk频道内的在线人数

获取Talk某频道用户列表

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

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

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

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

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

查询Talk频道上麦用户列表

向Talk频道发送文本消息

房间内用户身份切换