Live/im/api
第5行: | 第5行: | ||
微博与接入微博的第三方合作的一种模式是“服务端同步”,即微博直播互动系统和第三方互动系统之间做消息同步,从而实现消息共享的效果。发送消息接口和拉取消息接口(分主动拉取和被动拉取)提供第三方的消息同步到微博的功能。 | 微博与接入微博的第三方合作的一种模式是“服务端同步”,即微博直播互动系统和第三方互动系统之间做消息同步,从而实现消息共享的效果。发送消息接口和拉取消息接口(分主动拉取和被动拉取)提供第三方的消息同步到微博的功能。 | ||
− | == | + | == 互动上行 == |
第35行: | 第35行: | ||
{{api_args|room_id|true|string|房间id}} | {{api_args|room_id|true|string|房间id}} | ||
{{api_args|ts|true|long|时间戳(1970-01-01 00:00:00 起毫秒数)}} | {{api_args|ts|true|long|时间戳(1970-01-01 00:00:00 起毫秒数)}} | ||
− | {{api_args|msg_type|true|int| | + | {{api_args|msg_type|true|int|消息类型, 1 - 评论消息 2 - 点赞消息}} |
{{api_args|content|true|string|消息内容}} | {{api_args|content|true|string|消息内容}} | ||
{{api_args|uid|true|long|发送者ID}} | {{api_args|uid|true|long|发送者ID}} | ||
第70行: | 第70行: | ||
</pre> | </pre> | ||
− | |||
− | |||
− | |||
− | |||
− | == | + | == 互动下行Callback == |
'''概述''' | '''概述''' | ||
第106行: | 第102行: | ||
{{api_args|room_id|true|string|房间id}} | {{api_args|room_id|true|string|房间id}} | ||
{{api_args|ts|true|long|时间戳(1970-01-01 00:00:00 起毫秒数)}} | {{api_args|ts|true|long|时间戳(1970-01-01 00:00:00 起毫秒数)}} | ||
− | {{api_args|msg_type|true|int|消息类型 | + | {{api_args|msg_type|true|int|消息类型 1 - 评论消息 2 - 点赞消息}} |
{{api_args|content|true|string|消息内容}} | {{api_args|content|true|string|消息内容}} | ||
{{api_args|uid|true|long|发送者ID}} | {{api_args|uid|true|long|发送者ID}} | ||
第139行: | 第135行: | ||
</pre> | </pre> | ||
− | |||
− | |||
− | |||
− | |||
− | == | + | == 互动下行Pull == |
'''概述''' | '''概述''' | ||
− | + | 该接口提供第三方从微博直播互动系统拉取房间消息的功能。 | |
第三方发起该请求之后,只要不断开连接,该接口会源源不断的推回房间中最新的消息。如果连接意外断开,只要重连之前累计消息数量不超过商定的阈值,消息都会从上次断开的地方继续推送。 | 第三方发起该请求之后,只要不断开连接,该接口会源源不断的推回房间中最新的消息。如果连接意外断开,只要重连之前累计消息数量不超过商定的阈值,消息都会从上次断开的地方继续推送。 | ||
第207行: | 第199行: | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
== 签名算法== | == 签名算法== | ||
第241行: | 第227行: | ||
签名结果:lEwM4EFRDJ | 签名结果:lEwM4EFRDJ | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
== 数据结构 == | == 数据结构 == | ||
第419行: | 第341行: | ||
</pre> | </pre> | ||
− | |||
− | + | ||
− | + | ||
− | + | == 错误码定义 == | |
− | + | <table class="wiki_table"> | |
− | + | <tr> | |
− | + | <th>错误码</th> | |
− | + | <th>错误说明</th> | |
− | + | </tr> | |
− | + | <tr> | |
− | + | <td>9101</td> | |
− | + | <td>认证失败</td> | |
− | + | </tr> | |
− | + | <tr> | |
− | + | <td>9102</td> | |
− | + | <td>内部错误</td> | |
− | + | </tr> | |
+ | <tr> | ||
+ | <td>9103</td> | ||
+ | <td>数据格式错误</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>9104</td> | ||
+ | <td>消息内容包含垃圾信息</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>9105</td> | ||
+ | <td>已经存在</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>9106</td> | ||
+ | <td>数据不合法。与9103不同的地方在于:9103是数据格式错误, 比如int型的参数传了一个无法解析成int的字符串。而当前错误码表示数据格式本身没有问题, 但是是一个不合法的数据, 比如ID对应的实体不存在</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>9107</td> | ||
+ | <td>房间不允许发言</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>9108</td> | ||
+ | <td>用户不存在</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>9109</td> | ||
+ | <td>房间不存在</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>9110</td> | ||
+ | <td>token解析错误</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>9111</td> | ||
+ | <td>房间状态不正确</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>9112</td> | ||
+ | <td>用户被禁言</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>9113</td> | ||
+ | <td>当前操作不允许</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>1019</td> | ||
+ | <td>当前操作不支持</td> | ||
+ | </tr> | ||
+ | </table> |
2016年10月13日 (四) 15:26的版本
目录 |
概述
微博与接入微博的第三方合作的一种模式是“服务端同步”,即微博直播互动系统和第三方互动系统之间做消息同步,从而实现消息共享的效果。发送消息接口和拉取消息接口(分主动拉取和被动拉取)提供第三方的消息同步到微博的功能。
互动上行
URL
http://api.weibo.com/2/liveim/message/sync.json [POST]
支持格式
JSON
是否需要登录
true 登录授权方式,请参见本WIKI内的 如何登录授权
请求参数
参数字段 | 字段必选 | 字段类型 | 字段说明 |
---|---|---|---|
source | true | string | 申请应用时分配的AppKey,调用接口时候代表应用的唯一身份(采用OAuth授权方式不需要此参数) |
room_id | true | string | 房间id |
ts | true | long | 时间戳(1970-01-01 00:00:00 起毫秒数) |
msg_type | true | int | 消息类型, 1 - 评论消息 2 - 点赞消息 |
content | true | string | 消息内容 |
uid | true | long | 发送者ID |
nickname | true | string | 发送者昵称 |
avatar | true | string | 发送者头像url |
sign | true | string | 对sign之外的其他所有参数进行签名的结果 |
extension | false | string | 消息扩展字段(json object格式,默认为空json object) |
offset | false | long | 发消息的时间距离直播开始的偏移,单位ms。如果不传,或者传的是负数,做0处理,表示当前消息回放时不展示。 |
相关约束
sign是对出sign参数外的其他传递的所有参数的签名,预防请求被劫持篡改。见签名算法。
返回结果
//成功返回
{ "error_code":0, // 0表示成功 其他表示失败。需要看错误消息 "error_msg":"" }
//失败返回
{ "error_code": 91XX, "error_msg": "xxxxxxxxx" }
互动下行Callback
概述
如果第三方使用的是HTTP Callback的方式接受微博消息,那么第三方也需要提供一个类似[发送消息接口]的接口。要求与那个接口使用相同的参数和返回值。
URL
第三方自定义
支持格式
JSON
HTTP请求方式
POST
是否需要登录
true 登录授权方式,请参见本WIKI内的 如何登录授权
请求参数
参数字段 | 字段必选 | 字段类型 | 字段说明 |
---|---|---|---|
source | true | string | 申请应用时分配的AppKey,调用接口时候代表应用的唯一身份(采用OAuth授权方式不需要此参数) |
room_id | true | string | 房间id |
ts | true | long | 时间戳(1970-01-01 00:00:00 起毫秒数) |
msg_type | true | int | 消息类型 1 - 评论消息 2 - 点赞消息 |
content | true | string | 消息内容 |
uid | true | long | 发送者ID |
nickname | true | string | 发送者昵称 |
avatar | true | string | 发送者头像url |
sign | true | string | 对sign之外的其他所有参数进行签名的结果 |
extension | false | string | 消息扩展字段(json object格式,默认为空json object) |
offset | false | long | 发消息的时间距离直播开始的偏移,单位ms。如果不传,或者传的是负数,做0处理,表示当前消息回放时不展示。 |
相关约束
sign是对出sign参数外的其他传递的所有参数的签名,预防请求被劫持篡改。见签名算法。
返回结果
//成功返回
{ "error_code":0, // 0表示成功 其他表示失败。需要看错误消息 "error_msg":"" }
//失败返回
{ "error_code": 91XX, "error_msg": "xxxxxxxxx" }
互动下行Pull
概述
该接口提供第三方从微博直播互动系统拉取房间消息的功能。
第三方发起该请求之后,只要不断开连接,该接口会源源不断的推回房间中最新的消息。如果连接意外断开,只要重连之前累计消息数量不超过商定的阈值,消息都会从上次断开的地方继续推送。
URL
http://api.weibo.com/2/liveim/message/pull.json [POST]
支持格式
JSON
是否需要登录
true 登录授权方式,请参见本WIKI内的如何登录授权
请求参数
参数字段 | 字段必选 | 字段类型 | 字段说明 |
---|---|---|---|
source | true | string | 申请应用时分配的AppKey,调用接口时候代表应用的唯一身份(采用OAuth授权方式不需要此参数) |
room_id | true | string | 房间id |
返回结果 返回的消息以JSON的方式推送,推送的数据结构如下,每条消息是一个单独的JSON-OBJECT。 //成功返回
{ "error_code":0, // 0表示成功 其他表示失败。需要看错误消息 "error_msg":"", } { // 消息体。见附件[数据结构/消息体] } { // 消息体 } ...
//失败返回
{ "error_code": 91XX, "error_msg": "xxxxxxxxx" }
关于错误返回值与错误代码,参见 错误代码对照表
签名算法
输入: - 键值对列表 - 签名是用的secret
输出: 签名结果字符串 算法: - 键值对列表的每一项按照key=value的方式组成该项的字符串,各项的字符串按照对应key的字典序排序(key不相同),然后用半角"&"符号连接形成一个字符串。 - 字符串按照UTF-8编码得到一个字节序列input, secret的字符串按UTF-8编码生成一个字节序列作为key,用hmac-md5的方式计算哈希值的字节序列,哈希值字节序列使用URL-safe-Base64编码,取第6到16个字符作为结果输出。
算法示例
假设输入是: kv-pair: {"a":"1", "c":"jerry", "b":"tom"} secret: 123456
连接成的字符串就是: a=1&b=tom&c=jerry
hmac-md5("a=1&b=tom&c=jerry",123456) 输出得到字节数组:[-117, -27, -78, -5, 73, 68, -64, -50, 4, 21, 16, -55, -55, -39, -31, -15]
转成URL-safe的base64字符串:i-Wy-0lEwM4EFRDJydnh8Q== 取6到16位(初始位为0)子串,包含第6位,不包含第16位,共10位:lEwM4EFRDJ
签名结果:lEwM4EFRDJ
数据结构
房间信息
{ "room_id": string, "room_sys_id": uint64, "name": string, "pic_url": string, "introduction": string, "notification": string, "type": int, "status": int, // 房间当前的状态,0-未开始,1-正在直播,2-已删除,3-结束(可回放),4-推迟,5-结束(不可回放),6-主播离线 "created_at": unit64, // 创建时间,距离1970-01-01 00:00:00的毫秒数 "update_time": uint64, // 最后一次更新时间,单位与创建时间相同 "owner_info": { // 主播的信息 "uid": uint64, "user_system": string // 主播所在的用户体系,"0"表示微博 }, "counters": { // 房间的各种计数子结构 "onlines": int, // 在线人数 "praise_count": int, // 赞数 "play_count": int // 播放次数 }, "setting": { // 房间的一些设置选项 "max_onlines": int, // 房间允许的最大在线人数 "allow_comment": int // 当前房间是否允许发言,0-不允许,1-允许 } // 【!!!】下面的字段作废,即将下线,请使用相应的替换值 "max_onlines": int, //【已作废,使用setting.max_onlines替换】 "owner_uid": uint64, //【已作废,使用owner_info.uid替换】 "owner_user_system": string, //【已作废,用owner_info.user_system替换】 "onlines": int, //【已作废,使用counters.onlines替换】 "praise_count": int, //【已作废,用counters.praise_count替换】 "title": string, //【已作废,使用name替换】 }
用户信息
{ "uid":uint64 //用户的UID "user_system":string //用户所属系统,对用户禁言等操作时会用到 "nickname":string //直播用户昵称 "avatar":string //头像 "join_time": uint64, //用户进入房间时间,GMT时间戳 "role": uint32, //0:普通成员 1:主播 2:管理员 "followers_count":uint64 //用户粉丝数【仅微博用户有该字段】 "attention_count":uint32 //用户关注数【仅微博用户有该字段】 "level":uint32 //用户等级【仅微博用户有该字段】 "is_followed":uint32 //是否关注了该用户 0:未关注 1:关注【仅微博用户有该字段】 "is_vip":uint32 //是否是微博会员 0:否 1:是【仅微博用户有该字段】 "big_v":uint32 //微博认证大V 0:不是 1.蓝V 2.黄V【仅微博用户有该字段】 }
消息体
{ "room_id":string, //房间信息 "msg_type":1, "mid":long, "sender_info":{ // 发送者的用户信息 } "content":string, //消息内容 "extension":string //消息的扩展字段 "offset": long //消息距离视频开始时间间隔 "created_at":long //时间戳 // 其他字段,见“各消息类型的额外字段” }
各消息类型的额外字段
// 聊天消息,msg_type=1 "msg_behavior": uint32 //消息的显示行为 0:默认 1.弹幕 // 点赞消息,msg_type=2 "praises_count":int //msg_type=2的时候 当前总赞数 "inc_praises":long //用户点赞次数 // 禁言,msg_type=4 "shut_info":{ //msg_type=4生效 被禁言的用户信息 "shutted_until": uint32 //禁言结束的剩余时间,单位s "members":[ //被禁言用户列表 { "uid":uint64 //被禁言用户的UID "user_system":string //被禁言用户所属系统 } ] } // 房间变更,msg_type=11 "live_status":int //针对msg_type=11生效,表示直播的状态 "room_info": { // 房间信息结构 } // 加退房间,msg_type=12 "exit_or_enter_room":int //msg_type=12生效 0:退出 1:进入 "room_info": { // 房间信息结构 } // 增加删除管理员,msg_type=14 "admin_info":{ //msg_type=14生效 被增加或删除的用户信息 "uid":uint64 //被禁言用户的UID "user_system":string //被禁言用户所属系统 "type": int //操作类型 1 增加 2 删除 }
错误码定义
错误码 | 错误说明 |
---|---|
9101 | 认证失败 |
9102 | 内部错误 |
9103 | 数据格式错误 |
9104 | 消息内容包含垃圾信息 |
9105 | 已经存在 |
9106 | 数据不合法。与9103不同的地方在于:9103是数据格式错误, 比如int型的参数传了一个无法解析成int的字符串。而当前错误码表示数据格式本身没有问题, 但是是一个不合法的数据, 比如ID对应的实体不存在 |
9107 | 房间不允许发言 |
9108 | 用户不存在 |
9109 | 房间不存在 |
9110 | token解析错误 |
9111 | 房间状态不正确 |
9112 | 用户被禁言 |
9113 | 当前操作不允许 |
1019 | 当前操作不支持 |