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 服务器错误。