虎牙开放平台文档开放API 协议说明
一、协议说明
1.command命令请求json格式
{
"command":"subscribeNotice",
"data":["getMessageNotice","getVipEnterBannerNotice","getSendItemNotice", "getOnTVAwardNotice", "getOpenNobleNotice", "getOpenGuardianNotice"],
"reqId":"请求端的某一次请求的唯一标识",
"extUuid":"小程序uuid", //新版本追加的参数；订阅高级事件时，该值是必填的。
}
1.1目前支持两种命令：
**注：**
- **开放API相关的能力，目前只对企业认证的开发者开放。**
- **如开发者需要使用开放API相关功能，请提供企业名称、盖章版的企业营业执照、授权书、联系人信息、数据用途和订阅的数据，然后邮件联系平台（hy-ext@huya.com）提交权限申请审核，审核通过后才能成功订阅开放数据。**
- **订阅高级事件时，主播必须安装了该extUuid的小程序，才能订阅成功，否则提示订阅失败。**
- **订阅事件中同时含有普通事件和高级事件，如果不符合高级事件订阅条件，则所有的订阅事件均订阅失败。**
- (1)subscribeNotice: 订阅消息命令；
- (2)unsubscribeNotice: 取消订阅消息命令；
- (3)各个字段介绍：
- command：即上面的两种命令中的一种；
- data：命令的参数，目前支持以下几种消息
- 普通事件
- getMessageNotice: 弹幕消息
- getVipEnterBannerNotice: 高级用户进场消息
- getSendItemNotice: 送礼消息
- getOnTVAwardNotice: 上电视中奖
- getOpenNobleNotice: 开通续费贵族
- getOpenGuardianNotice: 开通续费守护
- getUserMutedNotice: 房管禁言
- getShareLiveNotice: 分享直播间
- getExpressionEmoticonNotice: 大表情/发送梗相关通用消息
- getUserDoButtonLikeNotice: 用户点赞事件消息
- 高级事件
- getVipBarNotice:用户进入贵宾席前100
- getConferVFansNotice:授予钻粉
- getOpenSuperFansNotice:开通续费超粉
- getFansBadgeNotice:首次获得粉丝徽章
- reqId：在发送命令是客户端生成的唯一id，只是用于对应命令与命令对应的rsp；
- extUuid:小程序uuid，订阅高级事件时，该值是必填的
- (4)可以在同一个websocket连接中通过发送命令，来同时订阅多个事件，也可以取消订阅，更加灵活
2.通用回包结构，包括命令回包（订阅/取消订阅），以及所有的订阅通知消息通用返回json数据格式
{
"notice:"xxxxxxxxx"; //对应通知类型，command：表示命令回包；getMessageNotice：弹幕事件；getSendItemNotice：送礼事件；getVipEnterBannerNotice：进场事件
"data":{}, //data对应的数据根据notice来解析，不同的notice对应不同的结构
"statusCode":xxx, //返回码，成功200
"statusMsg":"xxxxxxx" //其他错误返回的描述信息
}
3.命令回包对应data字段，对应notice：command
{
"command":"subscribeNotice", //对应的命令（订阅/取消订阅），subscribeNotice：订阅； unsubscribeNotice：取消订阅
"data":["getMessageNotice","getVipEnterBannerNotice"，"getSendItemNotice"], //command执行操作的对应的开放平台开放的接口数组
"failedList":[""], //当ret等于1 部分失败时对应data中的失败列表
"reqId":"请求端的某一次请求的唯一标识", //客户端command请求的唯一标识，客户端生成的，服务器回填，用于标识某一次comman请求与对应的请求rsp
"ret":xxx, //错误码，命令执行的返回码，全部成功为0，部分成功为1，全部失败为-1；
"msg":"xxxxx" //对应ret的msg信息
}
4.弹幕事件对应通用回包结构data字段，对应notice：getMessageNotice
{
"badgeName":"小九", //粉丝徽章名称
"content":"测试弹幕", //弹幕内容
"fansLevel":7, //粉丝等级
"msgType":0, //弹幕类型，0-常规弹幕，1-功能性弹幕(诸如部分投票/战队支持等相关弹幕)，2-上电视弹幕
"nobleLevel":4, //贵族等级
"unionId":"xxxxxx", //unionId为用户唯一Id
"roomId":10004859, //房间号
"sendNick":"我是一颗小虎牙", //发送弹幕的用户昵称
"senderAvatarUrl":"", //发送弹幕的用户头像
"senderGender":1, //发送弹幕的用户性别，0-女，1-男，其他未知
"senderLevel":10 //用户等级
}
5.送礼事件对应通用回包结构data字段，对应notice：getSendItemNotice
{
"badgeName":"小九",
"fansLevel":5,
"itemId":20206,
"itemName":"荧光棒",
"nobleLevel":2,
"presenterNick":"009一个字啊",
"roomId":10004859,
"sendItemComboHits":4, //送礼连击数
"sendItemCount":1,
"sendNick":"我是一颗小虎牙",
"senderAvatarurl":"http://huyaimg.msstatic.com/avatar/1025/06/fc11540e8d823369d21988b7b52996_180_135.jpg"，
"senderLevel":10, //用户等级
"totalPay":10, //此次送礼支付总额（单位：分）
"unionId":"xxxxxx"
}
6.高级用户进场事件对应通用回包结构data字段，对应notice：getVipEnterBannerNotice
{
"badgeName":"小九",
"fansLevel":5,
"nobleLevel":6,
"nobleName":"帝皇",
"unionId":"xxxxxx",
"roomId":10004859,
"userAvatarUrl":"http://test.huyaimg.msstatic.com/avatar/1060/b5/f3cccacf0a4efdcb0dacfaf6ed32b3_180_135.jpg?1510058616",
"userNick":"仙剑其夏装",
"userLevel":10 //用户等级
}
7.上电视中奖事件，对应notice：getOnTVAwardNotice
{
"roomId":1234567, //房间号
"title":"上电视主题", //房间主播设置的上电视主播
"awardName":"奖品名称", //房间主播设置的奖品名称
"awardNum":1, //房间主播设置的上电视最大中奖数量
"endTime":1545466778, //结束时间
"awardUserList":[{"unionId":"xxxxxxxxxx", "userNick":"xxxxxx", "userLevel":10, "awardName":"xxxxx", "content":"xxxxx", }] //中奖列表
}
8.开通续费贵族事件，对应notice：getOpenNobleNotice
{
"startTime":1561910400, //贵族生效unix时间戳
"endTime":1569686399, //贵族失效unix时间戳
"openFlag":1, //1代表首次(非贵族开通任一贵族,或者低等级贵族更换高等级的贵族操作,都并入到首开)，2代表续费
"months":1, //开通月数
"nobleLevel":6,
"nobleName":"帝皇",
"presenterNick":"‘九九\"啊哈哈",
"roomId":10004859,
"unionId":"unKbNwiZUXelTGihqCaRum3ky5QbomoGog",
"userAvatarUrl":"",
"userLevel":14, //用户等级
"userNick":"xxxxxxxx"
}
9.开通续费守护事件，对应notice：getOpenGuardianNotice
{
"startTime":1561910400, //守护生效unix时间戳
"endTime":1569686399, //守护失效unix时间戳
"guardianType":0, //守护类型，0-守护，1-铁铁，其它待拓展
"openDays":60, //开通或者续费天数
"lastGuardianLevel":1, //开通或者续费之前的守护等级
"openGuardianLevel":3, //开通或续费后守护等级
"presenterNick":"‘九九\"啊哈哈",
"roomId":10004859,
"unionId":"unKbNwiZUXelTGihqCaRum3ky5QbomoGog",
"userAvatarUrl":"",
"userLevel":14, //用户等级
"userNick":"xxxxxxxx"
}
10.房管禁言事件，对应notice：getUserMutedNotice
{
"auditorNick":"xxxxxxxxx", //房管昵称
"auditorRole":2, //房管身份标识，1超管，2普通房管或公会管理
"auditorUnionId":"unJPqBTOU3FEM/Ti3ckv6zB4EjTmbJE2Ij", //房管unionId
"mutedTime":604800, //封禁时长，单位秒s
"autoUnmutedTime":1563528843, //自动解禁时间，unix时间戳
"mutedAction":0, //封禁操作(0-禁言，1-封入黑名单)
"mutedReasonType":0, //理由类型(0-默认理由，1-恶意刷屏，2-谩骂，3-刷广告，4-其他理由)
"mutedReasonDetail":"", //理由详情（有可能为空）
"mutedUserNick":"xxxxxxxx", //被封禁用户昵称
"mutedUserText":"xxxxxxxxxxxxxxxxx", //公屏区的封禁内容，或者表示封禁入口途径（比如从榜单封禁）
"mutedUserUnionId":"und91n4GT9DHuG/IkTIJV7gV7S2IB3C5Q8", //被封禁用户的unionId
"roomId":12214
}
11.分享直播间事件，对应notice：getShareLiveNotice
{
"actionUrl":"xxxxxxxxxxxxxx", //直播间跳转链接
"content":"", //分享内容
"imageUrl":"", //分享图片的url
"presenterUnionId":"xxxxxxxxxxxxxxx",
"roomId":16780937,
"shareType":0, //分享类型，默认0
"sharerNick":"会飞的小小菠萝呀",
"sharerUnionId":"xxxxxxxxxxxxxxxx",
"subtitle":"", //直播间副标题
"title":"房间号16780937 -【星秀】大家好~欢迎大家来到小天儿的直播间" //直播间标题
}
12.用户进入贵宾席前100事件，对应notice：getVipBarNotice
{
"badgeName": "xxxx", //主播的徽章名
"fansLevel": 1, //徽章等级
"nobleLevel": 0, //贵族等级
"nobleName": "", //贵族名称
"presenterNick": "xxxx", //主播昵称
"rank": 2, //贵宾席排名（瞬时）
"roomId": 16780937, //主播房间号
"unionId": "unJPqBTOU3FEM/Ti3ckv6zB4EjTmbJE2Ij", //贵宾用户unionId
"userAvatarUrl": "xxxxxxxxxxxxxxxxxxxx", //贵宾用户头像
"userLevel": 9, //贵宾用户等级
"userLogoDecoUrl": "xxxxx", //贵宾用户头像装饰url
"userNick": "xxxxx" //主播昵称
}
13.授予钻粉事件，对应notice：getConferVFansNotice
{
"badgeName": "xxxx", //主播的徽章名
"expiredTime": 1605422613, //钻粉失效的时间戳: -1表示永久有效
"fansLevel": 1, //徽章等级
"openTime": 1602830597, //开通时间
"presenterNick": "xxxx", //主播昵称
"rank": 22, //用户徽章排名
"roomId": 16780937, //主播房间号
"score": 20, //用户该徽章的亲密度
"unionId": "unJPqBTOU3FEM/Ti3ckv6zB4EjTmbJE2Ij", //用户unionId
"userAvatarUrl": "xxxxxxxxxxxxxxxxxxxx", //用户头像
"userLevel": 9, //用户等级
"userNick": "xxxxx", //用户昵称
"vlogo": "xxxxxxxxxxxxxxxxxxxx" //钻粉logo
}
14.开通续费超粉事件，对应notice：getOpenSuperFansNotice
{
"expiredTime": 1602863598, //用户超粉到期时间戳
"freeMonth": 3, //赠送月数
"openType": 2, //操作类型：1开通、2续费
"payMonth": 12, //开通月数
"presenterNick": "xxxx", //主播昵称
"roomId": 16780937, //主播房间号
"unionId": "unJPqBTOU3FEM/Ti3ckv6zB4EjTmbJE2Ij", //用户unionId
"userAvatarUrl": "xxxxxxxxxxxxxxxxxxxx", //用户头像
"userLevel": 9, //用户等级
"userNick": "xxxxx", //用户昵称
"yearFlag": 1 //本次是否续费或开通年超粉标志类型：1为年超粉，0为普通
}
15.首次获得粉丝徽章事件，对应notice：getFansBadgeNotice
{
"badgeName": "xxxx", //主播的徽章名
"fansLevel": 1, //徽章等级
"openTime": 1602830597, //开通时间
"presenterNick": "xxxx", //主播昵称
"rank": 99, //用户徽章排名
"roomId": 16780937, //主播房间号
"score": 10, //用户该徽章的亲密度
"unionId": "unJPqBTOU3FEM/Ti3ckv6zB4EjTmbJE2Ij", //用户unionId
"userAvatarUrl": "xxxxxxxxxxxxxxxxxxxx", //用户头像
"userLevel": 9, //用户等级
"userNick": "xxxx" //用户昵称
}
16.大表情/发送梗相关通用消息，对应notice：getExpressionEmoticonNotice
{
"msgType":1, // 消息类型，1-序列帧(诸如直播间发送大表情)； 2-自定义图(诸如直播间发送梗)
"roomId":668,
"unionId":"xxxxxxxxxxx",
"sendNick":"xxxxx",
"senderAvatarUrl":"xxxxx",
"senderGender":1,
"senderLevel":16,
"badgeName":"xxxxx",
"nobleLevel":2,
"fansLevel":3,
"detail": // 详细信息，根据msgType字段不同进行解析
{
"emoticon":[{"content":"[骰子]"}]
}
}
根据msgType字段类型不同，detail字段json格式也不同。
1-序列帧，诸如直播间发送大表情，json格式如下:
(1) emoticon-对象数组，数组中每个对象定义大表情信息
(2) 具体对象数组中字段定义：
content-大表情
"detail":
{
"emoticon":[{"content":"[骰子]"}]
}
2-自定义图，诸如直播间发送梗，json格式如下：
(1) emoticon-对象数组，数组中每个对象定义梗信息
(2) 具体对象数组中字段定义：
content-梗
"detail":
{
"emoticon":[{"content":"[老板大气]"}]
}
{
likeCombos: 6, //点赞连击
likeCounts: 1, //点赞数
roomId: 556612, //主播房间号
unionId: 'xxxxx', //用户unionId
userAvatarUrl: 'xxxxx', //用户头像
userNick: 'xxxxx' //用户昵称
}
二、返回json数据例子：
1.发送命令的rsp：
{
"data":
{
"command":"subscribeNotice",
"data":["getMessageNotice","getVipEnterBannerNotice","getSendItemNotice"],
"failedList":[""],
"msg":"sucess",
"reqId":"123456789",
"ret":0
},
"notice":"command",
"statusCode":200,
"statusMsg":""
}
2.高级用户进场消息
{
"data":
{
"nobleLevel":4,
"nobleName":"公爵",
"roomId":10007263,
"unionId":"opQ0/FU7vxxRFnbSNoIaCyBXjKhkZ70mYy",
"userAvatarUrl":"",
"userNick":"xxxxxxx",
"userLevel":10
},
"notice":"getVipEnterBannerNotice",
"statusCode":200,
"statusMsg":""
}
3.弹幕消息
{
"data":
{
"badgeName":"小九",
"content":"哈哈哈哈哈哈",
"fansLevel":9,
"nobleLevel":4,
"roomId":10007263,
"sendNick":"xxxxxxx",
"senderAvatarUrl":"",
"senderGender":1,
"senderLevel":10,
"showMode":0,
"unionId":"opQ0/FU7vxxRFnbSNoIaCyBXjKhkZ70mYy"
},
"notice":"getMessageNotice",
"statusCode":200,
"statusMsg":""
}
4.送礼消息
{
"data":
{
"fansLevel":3,
"badgeName":"小九",
"nobleLevel":2,
"itemName":"血瓶",
"presenterNick":"xxxxxxx",
"roomId":10007263,
"sendItemComboHits":1,
"sendItemCount":1,
"sendNick":"xxxxxxx",
"senderAvatarurl":"",
"senderLevel":10,
"unionId":"opQ0/FU7vxxRFnbSNoIaCyBXjKhkZ70mYy"
},
"notice":"getSendItemNotice",
"statusCode":200,
"statusMsg":""
}
5.上电视中奖消息
{
"data":
{
"awardName":"1111",
"awardNum":2,
"awardUserList":[{"awardName":"1111","content":"看我独占电视","unionId":"unAa+8o5UV3yIM/I1fqsH2/SfgyIs0YLQS","userNick":"虎牙直播-xxxxx", "userLevel":10}],
"endTime":1556260699,
"roomId":10006965,
"title":""
},
"notice":"getOnTVAwardNotice",
"statusCode":200,
"statusMsg":""
}
6.大表情/发送梗相关通用消息
(1) 大表情
{
"notice:"getExpressionEmoticonNotice";
"data":
{
"msgType":1,
"roomId":668,
"unionId":"xxxxxxxxxxx",
"sendNick":"xxxxx",
"senderAvatarUrl":"xxxxx",
"senderGender":1,
"senderLevel":16,
"badgeName":"xxxxx",
"nobleLevel":2,
"fansLevel":3,
"detail":
{
"emoticon":[{"content":"[骰子]"}]
}
},
"statusCode":200,
"statusMsg":""
}
(2) 直播间发送的梗
{
"notice:"getExpressionEmoticonNotice";
"data":
{
"msgType":2,
"roomId":668,
"unionId":"xxxxxxxxxxx",
"sendNick":"xxxxx",
"senderAvatarUrl":"xxxxx",
"senderGender":1,
"senderLevel":16,
"badgeName":"xxxxx",
"nobleLevel":2,
"fansLevel":3,
"detail":
{
"emoticon":[{"content":"[老板大气]"}]
}
},
"statusCode":200,
"statusMsg":""
}
