Messages
乒乓消息接口使用手册
乒乓消息接口简介
- 微博开放平台乒乓消息接口为应用、企业、媒体提供与微博用户进行消息交互的能力。
乒乓消息接口使用步骤
- 1、蓝V用户开启新消息推送
- 蓝V用户授权指定应用接收其新消息,并开启新消息推送(内测期间请使用蓝V官方账号微博私信@XXX 申请)。
- 2、应用连接、推送开始
- 应用调用messages/receive接口指定需要接收推送新消息的蓝V,若蓝V已指定该应用且开启服务,则连接成功,当有微博用户对蓝V产生新消息时,推送服务将此新消息格式化后推送给该应用。
- 3、回复接收到的新消息
- 应用调用messages/reply接口对接收到的指定新消息进行回复,可根据语义识别后自动回复或由人工回复。每条新消息需在72小时内回复,且只能回复一次。
乒乓消息推送接口
功能: 乒乓消息推送接口,连接微博推送服务,接收推送给指定蓝V用户的新消息
接口调用地址:https://api.weibo.com/2/messages/receive.json
HTTP请求方式:GET
是否需要登陆:是
接口请求参数 | |||
---|---|---|---|
参数名称 | 值得类型 | 是否必填 | 说明描述 |
source | string | true | 申请应用时分配的AppKey,调用接口时候代表应用的唯一身份。 |
uid | int64 | true | 需要接收的蓝V用户ID。 |
since_id | int64 | false | 上次连接断开时的消息ID。保存断开后五分钟内的新消息,可以通过since_id获取断开五分钟内的新消息。 |
注意事项
- 1、调用接口的登录帐号为该appkey的创建者,需要使用创建者帐号通过Base Auth的方式;
- 2、调用接口的请求IP为该appkey绑定的IP地址;
- 3、指定的ID用户为蓝V;
- 4、指定的ID用户已设置成将自己的新消息推送给该appkey;
- 5、指定的ID用户已开启推送;
- 6、每条完整的新消息数据以json形式返回,默认采用UTF-8编码,且以\r\n分隔;
- 7、蓝V与蓝V之间产生的新消息不推送;
- 8、为缓解服务压力,请求建立后十分钟自动断开,应用需兼容重新调此接口链接。
接口调用失败返回:
{ "request": "/2/messages/receive.json", "error_code": "203XX", "error": "error message." }
连接建立后,当蓝V有新消息时,微博平台通过此连接向应用推送新消息,当前支持的消息类型:
- 1、关注事件消息:follow
{ "id": 1211260020031346, "type": "follow", "recipient_id": 1902538057, "sender_id": 2489518277, "created_at": "Mon Jul 16 18:09:20 +0800 2012", "data": {} }
返回值说明 | ||
---|---|---|
属性 | 值得类型 | 说明描述 |
id | string | 消息ID |
type | string | follow |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 默认文案 |
data | string | 消息内容,关注消息为空 |
- 2、纯文本类型私信消息:text
{ "id": 1211260020031346, "type": "text", "recipient_id": 1902538057, "sender_id": 2489518277, "created_at": "Mon Jul 16 18:09:20 +0800 2012", "text": "关注事件", "data": {} }
返回值说明 | ||
---|---|---|
属性 | 值得类型 | 说明描述 |
id | string | 消息ID |
type | string | follow |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 私信内容 |
data | string | 消息内容,纯文本私信为空 |
- 3、位置类型私信消息:position
{ "id": 1211260020031347, "type": "position", "recipient_id": 1902538057, "sender_id": 2489518277, "created_at": "Mon Jul 16 18:09:20 +0800 2012", "text": "分享了一个位置", "data": { "longitude": "344.3344", "latitude": "232.343434" } }
返回值说明 | ||
---|---|---|
属性 | 值得类型 | 说明描述 |
id | string | 消息ID |
type | string | position |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 默认文案 |
data | string | 消息内容 |
data:longitude | string | 经度 |
data:latitude | string | 纬度 |
乒乓消息回复接口
功能: 乒乓消息响应接口,对接收到的指定新消息进行回复
接口调用地址:https://api.weibo.com/2/messages/reply.json
HTTP请求方式:POST
是否需要登陆:是
接口请求参数 | |||
---|---|---|---|
参数名称 | 值得类型 | 是否必填 | 说明描述 |
source | string | true | 申请应用时分配的AppKey,调用接口时候代表应用的唯一身份。 |
id | int64 | true | 需要响应的推送消息ID。 |
type | string | true | 需要以何种类型的消息进行响应。text:纯文本。 |
data | string | true | 消息数据,具体内容严格遵循type类型对应格式。必须为json做URLEncode后的字符串格式,采用UTF-8编码。字符串长度不超过2512个字节。 |
注意事项
- 1、调用接口的登录帐号必须为该appkey的创建者,需要使用创建者帐号通过Base Auth的方式;
- 2、指定ID的新消息创建时间在72小时内;
- 3、指定ID的新消息只能回复一次,多次回复报错;
- 4、指定ID的新消息对应的原接收者身份发出此消息;
- 5、指定ID的新消息对应的原发送者将收到此消息;
- 6、发送者未被屏蔽或拉黑时消息进私信箱。
接口调用失败返回:
{ "request": "/2/messages/reply.json", "error_code": "203XX", "error": "error message." }
当前支持回复的消息类型中,data参数支持的格式:
- 1、纯文本类型私信消息:text
接口请求参数 | |||
---|---|---|---|
参数名称 | 值得类型 | 是否必填 | 说明描述 |
text | string | true | 要回复的私信文本内容。文本大小必须小于300个汉字。 |
举例:
当data对应json为{"text": "纯文本响应"} 时,则进行URLEncode后对应data参数值为:"%7b%0a++++%22text%22%3a+%22%e7%ba%af%e6%96%87%e6%9c%ac%e5%93%8d%e5%ba%94%22%0a%7d"。
返回值说明 | ||
---|---|---|
属性 | 值得类型 | 说明描述 |
id | string | 消息ID |
type | string | follow |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 默认文案 |
data | string | 消息内容,关注消息为空 |
- 2、纯文本类型私信消息:text
{ "id": 1211260020031346, "type": "text", "recipient_id": 1902538057, "sender_id": 2489518277, "created_at": "Mon Jul 16 18:09:20 +0800 2012", "text": "关注事件", "data": {} }
返回值说明 | ||
---|---|---|
属性 | 值得类型 | 说明描述 |
id | string | 消息ID |
type | string | follow |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 私信内容 |
data | string | 消息内容,纯文本私信为空 |
- 3、位置类型私信消息:position
{ "id": 1211260020031347, "type": "position", "recipient_id": 1902538057, "sender_id": 2489518277, "created_at": "Mon Jul 16 18:09:20 +0800 2012", "text": "分享了一个位置", "data": { "longitude": "344.3344", "latitude": "232.343434" } }
返回值说明 | ||
---|---|---|
属性 | 值得类型 | 说明描述 |
id | string | 消息ID |
type | string | position |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 默认文案 |
data | string | 消息内容 |
data:longitude | string | 经度 |
data:latitude | string | 纬度 |
V1到V2怎么迁移
简述
- V1迁移到V2主要需要完成OAuth1.0到OAuth2.0的过度及完成V1原有接口与V2中新接口的对应替换。
迁移时需要完成的工作
- 1、授权方式的迁移,OAuth1.0升级到OAuth2.0;
- 2、阅读迁移注意事项及常见问题解决建议;
- 3、新旧接口的迁移,接口调用地址、调用方式、参数、返回值、错误信息处理的代码改造。
OAuth1.0升级到OAuth2.0
- 1、OAuth2.0简述
- OAuth2.0是较OAuth1.0更简单更安全的授权方式,同时支持Web,桌面和移动应用。是未来新浪微博开放平台最主要的用户身份验证和授权方式。
- 2、迁移前准备
- 请先阅读OAuth2.0开发指南。
- OAuth2.0授权方式与OAuth1.0相比,引入授权回调页与绑定域名,简化了授权流程,同时也提升了授权的安全性。
- 在实现OAuth2.0授权方式前,针对不同的应用我们需要设置应用的授权回调页或进行域名的绑定,用于获得授权成功后返回的code,再通过code获取access_token。
- 使用开发者帐号登录http://open.weibo.com,进入“我的应用”控制台需要迁移的应用进行设置:
- a)网站接入类
- 点击控制台导航“网站信息”,在网站基本信息中查看网站域名。如果您的网站应用还未验证所有权,会提示您进行所有权验证,点击进入验证页面完成所有权验证。Web应用请参考:Web应用迁移指引 。
- 注意:验证时填写的网站域名即为您的应用的绑定域名。
- b)站内应用
- 站内应用已经是OAuth2.0授权方式,无需做改动。
- b)站内应用
- c)客户端应用 & 其他应用
- 点击控制台导航“应用信息”—> “高级信息”,进行授权回调页或域名的绑定。设置回调页不需要二审,方便您进行测试开发。绑定域名需要进行二审,二审时线上应用不受影响,绑定域名增加应用的安全性,同时该域名下的所有页面都可作为授权回调页。
- c)客户端应用 & 其他应用
- 注意:客户端也需要设置授权回调页或绑定域名,在程序中以webview的方式进行调用授权页面返回code,具体实现可
- 以参考:移动应用迁移指引 。 其他客户端可以参考相应SDK:http://open.weibo.com/wiki/SDK 。
- 注意:客户端也需要设置授权回调页或绑定域名,在程序中以webview的方式进行调用授权页面返回code,具体实现可
- 3、OAuth2.0授权实现
- 主要流程(请先阅读OAuth2.0开发指南):
- a)引导需要授权的用户访问如下地址
- 注意:redirect_uri必须为绑定域名下网页或设置的回调地址。
- b)如果用户同意授权,页面跳转至 YOUR_REGISTERED_REDIRECT_URI/?code=CODE
- 注意:每次返回的code值都是不一样的且在换取access_token后失效。
- c)使用code换取access_token
- 注意:必须使用POST方式提交,其中client_id=YOUR_APP_KEY&client_secret=YOUR_APP_SECRET可以使用
- basic方式加入header中。
- 注意:必须使用POST方式提交,其中client_id=YOUR_APP_KEY&client_secret=YOUR_APP_SECRET可以使用
- e)使用获得的OAuth2.0 Access Token调用API
- 读取接口一般使用GET方式提交,如:
- 接口:statuses/home_timeline
- 调用:https://api.weibo.com/2/statuses/home_timeline.json?access_token=SlAV32hkKG&count=20 ;
- e)使用获得的OAuth2.0 Access Token调用API
- 写入接口必须使用POST方式提交,如:
- 接口:statuses/upload
- 调用:https://upload.api.weibo.com/2/statuses/upload.json
- 注意:参数信息放入header及body中,除access_token外,其他参数必须放入body中请求。
- upload请求消息体举例:
- => Send header, 301 bytes (0x12d)
- POST /2/statuses/upload.json HTTP/1.1
- User-Agent: curl/7.19.4 (i586-pc-mingw32msvc) libcurl/7.19.4 Ope
- nSSL/0.9.8g zlib/1.2.3
- Host: upload.api.weibo.com
- Accept: */*
- Content-Length: 38694
- Expect: 100-continue
- Content-Type: multipart/form-data; boundary=--------------------
- --------8933e7b00565
- <= Recv header, 23 bytes (0x17)
- HTTP/1.1 100 Continue
- => Send data, 370 bytes (0x172)
- ------------------------------8933e7b00565
- Content-Disposition: form-data; name="access_token"
- 2.00RQs9XCmlEQDD4fb4b0bfe3Be7ZQE
- ------------------------------8933e7b00565
- Content-Disposition: form-data; name="status"
- Test02
- ------------------------------8933e7b00565
- Content-Disposition: form-data; name="pic"; filename="psu.jpg"
- Content-Type: image/jpeg
V1接口迁移到V2接口
- 在实现OAuth2.0授权后,接下来需要将应用使用的V1版接口对应迁移到V2版接口。此时需要根据新接口的调用地址、调用方式、参数、返回值、错误信息处理来进行代码的改造。
- 以下是V2版接口与V1版接口的对应列表,部分旧版接口由于用户投诉或性能等原因已不再提供,同时新版接口提供丰富的高级接口开放优质应用申请,您可以直接在应用控制台中提交高级接口申请。
- 此外,SCOPE授权功能、好友分组接口、邀请接口、社交化等接口已经在平台开放计划中,我们将在保证功能、性能及稳定性后适时开放,详细的开放日期请您关注@微博API。
- 如果现有接口未能满足您的需求,欢迎@微博API进行反馈,我们将根据开发者需求强度及微博用户利益权衡适度开放。
新旧接口对应表 | |||
---|---|---|---|
新版V2接口 | 对应老版V1接口 | 接口名称 | 接口名称 |
statuses/public_timeline | statuses/public_timeline | 获取最新的公共微博 | 获取最新的公共微博 |
OAuth2(开发指南) | ||
---|---|---|
oauth2/authorize | 请求用户授权Token | |
oauth2/access_token | 获取授权过的Access Token | |
oauth2/get_oauth2_token | OAuth1.0的Access Token更换至OAuth2.0的Access Token |