Weibo Platform Logo

微博开放平台

weibo

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 消息内容，纯文本私信为空



迁移中常见问题

  • 1、Xweibo组件及应用如何过度到V2版？
    • Xweibo已审核上线应用在10月左右暂时不受影响，需要积极配合Xweibo官方提示进行相应的升级。请关注Xweibo官网：http://x.weibo.com 。


  • 2、V1中的私信及获取用户信息接口为什么不开放？
    • 私信及涉及隐私的用户信息接口被大量应用滥用，导致大量用户投诉，给平台的开放造成了非常恶劣影响，出于对用户隐私的保护，平台决定不再开放此类导致用户信息泄漏的接口。


  • 3、OAuth2.0授权需要申请吗？
    • OAuth2.0授权无需申请，任何应用都可以使用。
    • 需要额外申请的是授权有效期或客户端验证授权。授权有效期可在应用控制台，接口管理标签下的授权机制选项中进行在线申请，客户端验证授权申请方式参见第二个问题。


  • 4、怎么申请客户端的验证授权（Resource Owner Password Credentials）方式？
    • 因为OAuth2.0的客户端验证授权会获得用户明文密码，所以实行有限开放。


    • 申请条件：
    • a）应用分类属于桌面客户端、手机客户端。
    • b）应用本身已经通过开放平台文案、广场审核，并在广场上展示超过15天。
    • c）应用使用人数在30000以上。
    • d）应用本身功能与新浪微博关联紧密。


    • 满足条件后在应用控制台的“接口管理”-->“授权机制”中申请。


  • 5、手机客户端、PC客户端应用是否需要设置回调页？
    • 需要，使用Web应用的验证授权(Authorization Code)方式的客户端也需要设置授权回调页或绑定域名，在程序中以webview的方式进行调用授权页面返回code，具体实现参考相应的客户端SDK：http://open.weibo.com/wiki/SDK。


  • 6、如何查询应用的access_token有效期是多少？
    • a）桌面客户端、手机客户端类应用，测试：1天、尽审核：7天、审核后并上广场展示后：90天。
    • b）非客户端类应用，测试1天、普通7天、中级15天、高级30天、合作90天。


  • 7、如何申请延长应用的access_token有效期？
    • a）桌面客户端、手机客户端类应用，未审核应用在应用控制台申请审核通过后7天，如需要达到90天有效期，审核通过后
      • 在申请广场审核。
    • b）非客户端类应用，未审核应用在应用控制台申请审核通过后为普通级别7天， 如需申请更高级别，在应用控制台“接口管
      • 理”-->“调用频次”中进行申请。


  • 8、如何计算某个用户的access_token过期时间？
    • a）用户授权时，oauth2/access_token接口返回的expires_in（单位：秒）值就是access_token的生命周期。
    • b）从上述对应表中，找到应用所对应的授权有效期，过期时间 = 用户授权时间 + 授权有效期。



  • 9、access_token过期后怎么处理？
    • access_token过期调用接口时，平台会返回错误码为21332的错误，此时需要引导用户重新进行授权。建议在每次获得用户授权时保存过期时间，在每次调用接口前判断用户access_token是否过期。


    • 引导已授权用户再次授权时，如果此用户为已登录新浪微博状态，则授权页面为“一闪而过”无需用户再点击“授权”按钮，如果想让用户重新登录授权，则在调用authorize接口是传入参数：forcelogin=true，默认不填（授权页一闪而过）此参数相当于forcelogin=false。


  • 10、已上线应用如何进行本地测试？
    • a）应用不含高级权限或高级接口，建议申请一个普通的Appkey进行本地测试；
    • b）应用含高级接口或高级权限，可以考虑绑定hosts指向本地测试代码进行测试。


  • 11、如何将已授权用户从OAuth1.0过度到OAuth2.0授权？
    • 应用授权方式从OAuth1.0迁移到OAuth2.0时，应用的授权用户总数不变，以下是进行用户过度的两个建议：
    • a）直接上线OAuth2.0授权版本，OAuth2.0获取access_token时返回用户的uid，根据此uid判断该用户为老用户或新用
      • 户，新增或更新数据库中用户access_token等信息；
    • b）使用get_oauth2_token接口换取OAuth2.0的access_token，此方法可以免去用户对OAuth2.0第一次授权，适当延长过
      • 度OAuth2.0的时间以完成a）的实现（对于授权有效期较长或客户端类应用可以考虑此方法）。
      • 注意：做批量换取是需谨慎，同一个OAuth1.0的Access Token只能换取一次(多次调用将返回同一个token)，过期时间
          • 从第一次换取的时候计算。


  • 12、迁移时是否需要添加测试帐号？
    • a）测试帐号仅对未审核应用限制，如果您的应用在V1时已经审核通过，则无需添加测试用户。
    • b）如果您使用了未审核的Appkey进行测试，需要您在应用或网站控制台“应用信息”或“网站信息”-->“测试帐号”中添加测试帐
      • 号，未审核应用只有应用创建者与测试帐号才能调用接口。


  • 13、V2版接口返回值为什么仅支持JSON格式不支持XML格式返回？
    • a）接口返回值中可能会含有html等字段，采用XML格式返回时需要对html进行特殊处理，直接影响到平台包装返回值及开
      • 发者解析返回值的效率；
    • b）对于JS等语言在解析复杂的XML难度较高，效率较低；
    • c）XML格式较JSON采用Key-Value的形式有很大冗余，不符合手机客户端等对性能要求较高的应用需求。


  • 14、有哪些高级接口，怎么申请新版高级接口？
    • 在V2接口文档中接口名称后标注着： 图标则表示此接口为高级接口。高级接口申请要求应用需要通过文案审核，并无作恶情况发生。其他要求及申请流程见：高级接口申请指南。


  • 15、阅读完迁移指南后仍有问题怎么办？



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授权方式，无需做改动。


    • c）客户端应用 & 其他应用
      • 点击控制台导航“应用信息”—> “高级信息”，进行授权回调页或域名的绑定。设置回调页不需要二审，方便您进行测试开发。绑定域名需要进行二审，二审时线上应用不受影响，绑定域名增加应用的安全性，同时该域名下的所有页面都可作为授权回调页。



    • 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中。


    • d）返回值
      • {"access_token":"SlAV32hkKG","remind_in":"3600","expires_in":3600,"uid":"1902538057"}
      • 注意：OAuth2.0的access_token较OAuth1.0具有一定的有效期，当access_token过期时需要引导用户重新授权。应用



      • 注意：参数信息放入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
来自“http://open.weibo.com/wiki/index.php?title=Messages&oldid=11054”

关于微博开放平台| 联系我们| 服务条款| 无线游戏| 开放平台官微

京网文 [2011] 0398-130号 京ICP证100780号 Copyright © 1996-2024 SINA