消息推送服务

跳转到: 导航, 搜索
(发送被动响应)
 
(未显示2个用户的22个中间版本)
第21行: 第21行:
 
建立首次连接后,后续每次微博事件推送时也都会带上signature、timestamp、nonce三个参数,开发者依然可以通过对signature的校验判断此条消息的真实性。校验方式与首次建立连接一致。
 
建立首次连接后,后续每次微博事件推送时也都会带上signature、timestamp、nonce三个参数,开发者依然可以通过对signature的校验判断此条消息的真实性。校验方式与首次建立连接一致。
  
==接受消息推送==
+
==接收普通消息==
  
建立首次连接后,当认证用户有新消息时,微博消息推送服务会POST消息数据包到开发者填写的URL上,当前支持的消息类型:
+
建立首次连接后,当认证用户有新消息时,微博消息推送服务会POST消息数据包到开发者填写的URL上,当前支持的普通消息类型包括:
  
 
(<font style="color:red">注意:</font>需要对接收到的消息体type或subtype做兼容,当出现未知类型时可忽略此消息。)
 
(<font style="color:red">注意:</font>需要对接收到的消息体type或subtype做兼容,当出现未知类型时可忽略此消息。)
 
<h3>事件消息:event</h3>
 
<pre>
 
{
 
    "type": "event",
 
    "receiver_id": 1902538057,
 
    "sender_id": 2489518277,
 
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
 
    "text": "事件消息",
 
    "data": {
 
        "subtype": "EVENT",
 
        "key": "EVENT_KEY",
 
        "ticket": "TICKET",
 
    }
 
}
 
</pre>
 
<div class="wiki_kit">
 
 
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 
|-
 
|style="text-align:center; width: 12%"|属性
 
|style="text-align:center;width: 12%"|值的类型
 
|style="text-align:center;"|说明描述
 
|-
 
|type
 
|string
 
|event
 
|-
 
|receiver_id
 
|int64
 
|消息的接收者
 
|-
 
|sender_id
 
|int64
 
|消息的发送者
 
|-
 
|created_at
 
|string
 
|消息创建时间
 
|-
 
|text
 
|string
 
|默认文案。subtype为follow或unfollow时分别为“关注事件消息”、“取消关注事件消息”;为subscribe或unsubscribe时为触发订阅的私信关键词(如“dy”),非私信触发时(点击订阅按钮)为“订阅事件消息”、“取消订阅事件消息”;subtype为scan或scan_follow时为“扫描二维码”;
 
|-
 
|data
 
|string
 
|消息内容
 
|-
 
|data:subtype
 
|string
 
|follow:关注事件,unfollow取消关注事件,subscribe订阅事件,unsubscribe订阅事件。scan和scan_follow为二维码扫描事件。
 
|-
 
|data:key
 
|string
 
|subtype为follow、unfollow、subscribe或unsubscribe时不返回
 
|-
 
|data:ticket
 
|string
 
|subtype为scan和scan_follow时才返回
 
|}
 
 
  
 
<h3>纯文本类型私信和留言消息:text</h3>
 
<h3>纯文本类型私信和留言消息:text</h3>
第327行: 第264行:
 
</pre>
 
</pre>
  
 +
==接收事件推送==
  
 +
建立首次连接后,当认证用户有新消息时,微博消息推送服务会POST消息数据包到开发者填写的URL上,当前支持的事件类型:
 +
 +
<h3>事件消息:event</h3>
 +
<pre>
 +
{
 +
    "type": "event",
 +
    "receiver_id": 1902538057,
 +
    "sender_id": 2489518277,
 +
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
 +
    "text": "事件消息",
 +
    "data": {
 +
        "subtype": "EVENT",
 +
        "key": "EVENT_KEY",
 +
        "ticket": "TICKET",
 +
    }
 +
}
 +
</pre>
 +
<div class="wiki_kit">
 +
 +
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 +
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 +
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 +
|-
 +
|style="text-align:center; width: 12%"|属性
 +
|style="text-align:center;width: 12%"|值的类型
 +
|style="text-align:center;"|说明描述
 +
|-
 +
|type
 +
|string
 +
|event
 +
|-
 +
|receiver_id
 +
|int64
 +
|消息的接收者
 +
|-
 +
|sender_id
 +
|int64
 +
|消息的发送者
 +
|-
 +
|created_at
 +
|string
 +
|消息创建时间
 +
|-
 +
|text
 +
|string
 +
|默认文案。subtype为follow或unfollow时分别为“关注事件消息”、“取消关注事件消息”;为subscribe或unsubscribe时为触发订阅的私信关键词(如“dy”),非私信触发时(点击订阅按钮)为“订阅事件消息”、“取消订阅事件消息”;subtype为scan或scan_follow时为“扫描二维码”;
 +
|-
 +
|data
 +
|string
 +
|消息内容
 +
|-
 +
|data:subtype
 +
|string
 +
|follow:关注事件,unfollow取消关注事件,subscribe订阅事件,unsubscribe订阅事件。scan和scan_follow为二维码扫描事件。
 +
|-
 +
|data:key
 +
|string
 +
|subtype为follow、unfollow、subscribe或unsubscribe时不返回
 +
|-
 +
|data:ticket
 +
|string
 +
|subtype为scan和scan_follow时才返回
 +
|}
  
 
<h3>被@消息:mention</h3>
 
<h3>被@消息:mention</h3>
第387行: 第388行:
 
|当subtype为status时为微博ID,为comment时为评论ID
 
|当subtype为status时为微博ID,为comment时为评论ID
 
|}
 
|}
 
 
  
 
==发送被动响应==
 
==发送被动响应==
  
对于每一个POST请求,开发者在响应包(Get)中返回特定JSON包,对该消息进行响应。微博服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次; 关于重试的消息排重,推荐使用消息ID排重。
+
对于每一个POST请求,开发者在响应包(Get)中返回特定JSON包,对该消息进行响应。微博服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次;  
 +
 
 +
关于重试的消息排重,推荐使用FromUserName + CreateTime 排重;
  
 
假如开发者无法保证在五秒内处理并回复,可以直接回复空串,微博服务器不会对此作任何处理,并且不会发起重试。
 
假如开发者无法保证在五秒内处理并回复,可以直接回复空串,微博服务器不会对此作任何处理,并且不会发起重试。
  
 
如果发送被动响应消息,则返回JSON格式如下:
 
如果发送被动响应消息,则返回JSON格式如下:
 +
注意:JSON格式中的data字段内容必须进行UTF8格式的URLEncode
 
<pre class="brush:js">
 
<pre class="brush:js">
 
{
 
{
 
     "result": true,
 
     "result": true,
     "tpye": "text",
+
     "receiver_id":123456,
 +
    "sender_id":123123,
 +
    "type": "text",
 
     "data":"{}"
 
     "data":"{}"
 
}
 
}
 
</pre>
 
</pre>
 +
  
  
第414行: 第419行:
 
}
 
}
 
</pre>
 
</pre>
 +
 
<div class="wiki_kit">
 
<div class="wiki_kit">
  
第431行: 第437行:
 
|}
 
|}
 
举例:
 
举例:
当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"。
+
当data对应json为{"text": "纯文本响应"} 时,则进行URLEncode后对应data参数值为:"%7B%22text%22%3A%20%22%E7%BA%AF%E6%96%87%E6%9C%AC%E5%93%8D%E5%BA%94%22%7D%20"。
  
 
<h3>图文类型私信消息:articles</h3>
 
<h3>图文类型私信消息:articles</h3>
第511行: 第517行:
 
|}
 
|}
  
 +
==微信XML格式兼容==
 +
除了上述的JSON格式,微博消息推送服务还支持“微信XML格式兼容”;
 +
第三方可以通过http://open.weibo.com/wiki/Eps/push/set_format 接口来选择自己需要的格式是XML还是JSON;
  
 +
XML格式详细描述如下:
  
==XML格式兼容模式==
+
<h3>接收消息推送</h3>
主要是BD合作引入,步骤为:
+
1. text消息的XML格式
 +
<pre>
 +
<xml>
 +
<ToUserName><![CDATA[toUser]]></ToUserName>
 +
<FromUserName><![CDATA[fromUser]]></FromUserName>
 +
<CreateTime>1348831860</CreateTime>
 +
<MsgType><![CDATA[text]]></MsgType>
 +
<Content><![CDATA[this is a test]]></Content>
 +
<MsgId>1234567890123456</MsgId>
 +
</xml>
 +
</pre>
 +
 
 +
<div class="wiki_kit">
 +
 
 +
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 +
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 +
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 +
|-
 +
|style="text-align:center; width: 25%"|XML参数
 +
|style="text-align:center;width: 25%"|在JSON格式中对应的参数
 +
|style="text-align:center;"|说明描述
 +
|-
 +
|ToUserName
 +
|receiver_id
 +
|消息的接收者
 +
|-
 +
|FromUserName
 +
|sender_id
 +
|消息的发送者
 +
|-
 +
|CreateTime
 +
|created_at
 +
|消息创建时间
 +
|-
 +
|MsgType
 +
|type
 +
|text
 +
|-
 +
|Content
 +
|text
 +
|私信内容
 +
|-
 +
|MsgId
 +
|暂无对应字段
 +
|该字段内容为空
 +
|}
 +
 
 +
2. image消息的XML格式
 +
<pre>
 +
<xml>
 +
<ToUserName><![CDATA[toUser]]></ToUserName>
 +
<FromUserName><![CDATA[fromUser]]></FromUserName>
 +
<CreateTime>1348831860</CreateTime>
 +
<MsgType><![CDATA[image]]></MsgType>
 +
<PicUrl><![CDATA[this is a url]]></PicUrl>
 +
<MediaId><![CDATA[media_id]]></MediaId>
 +
<MsgId>1234567890123456</MsgId>
 +
</xml>
 +
</pre>
 +
 
 +
<div class="wiki_kit">
 +
 
 +
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 +
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 +
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 +
|-
 +
|style="text-align:center; width: 25%"|XML参数
 +
|style="text-align:center;width: 25%"|在JSON格式中对应的参数
 +
|style="text-align:center;"|说明描述
 +
|-
 +
|ToUserName
 +
|receiver_id
 +
|消息的接收者
 +
|-
 +
|FromUserName
 +
|sender_id
 +
|消息的发送者
 +
|-
 +
|CreateTime
 +
|created_at
 +
|消息创建时间
 +
|-
 +
|MsgType
 +
|type
 +
|image
 +
|-
 +
|PicUrl
 +
|无对应字段
 +
|该字段内容为空
 +
|-
 +
|MediaID
 +
|data:tovfid
 +
|私信内容
 +
|-
 +
|MsgId
 +
|暂无对应字段
 +
|该字段为空
 +
|}
 +
 
 +
3. voice消息的XML格式
 +
<pre>
 +
<xml>
 +
<ToUserName><![CDATA[toUser]]></ToUserName>
 +
<FromUserName><![CDATA[fromUser]]></FromUserName>
 +
<CreateTime>1357290913</CreateTime>
 +
<MsgType><![CDATA[voice]]></MsgType>
 +
<MediaId><![CDATA[media_id]]></MediaId>
 +
<Format><![CDATA[Format]]></Format>
 +
<MsgId>1234567890123456</MsgId>
 +
</xml>
 +
</pre>
 +
 
 +
<div class="wiki_kit">
 +
 
 +
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 +
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 +
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 +
|-
 +
|style="text-align:center; width: 25%"|XML参数
 +
|style="text-align:center;width: 25%"|在JSON格式中对应的参数
 +
|style="text-align:center;"|说明描述
 +
|-
 +
|ToUserName
 +
|receiver_id
 +
|消息的接收者
 +
|-
 +
|FromUserName
 +
|sender_id
 +
|消息的发送者
 +
|-
 +
|CreateTime
 +
|created_at
 +
|消息创建时间
 +
|-
 +
|MsgType
 +
|type
 +
|voice
 +
|-
 +
|PicUrl
 +
|无对应字段
 +
|该字段内容为空
 +
|-
 +
|MediaID
 +
|data:tovfid
 +
|私信内容
 +
|-
 +
|Format
 +
|暂无对应字段
 +
|该字段为空
 +
|-
 +
|MsgId
 +
|暂无对应字段
 +
|该字段为空
 +
|}
 +
 
 +
4. position消息的XML格式
 +
<pre>
 +
<xml>
 +
<ToUserName><![CDATA[toUser]]></ToUserName>
 +
<FromUserName><![CDATA[fromUser]]></FromUserName>
 +
<CreateTime>1351776360</CreateTime>
 +
<MsgType><![CDATA[location]]></MsgType>
 +
<Location_X>23.134521</Location_X>
 +
<Location_Y>113.358803</Location_Y>
 +
<Scale>20</Scale>
 +
<Label><![CDATA[位置信息]]></Label>
 +
<MsgId>1234567890123456</MsgId>
 +
</xml>
 +
</pre>
 +
 
 +
<div class="wiki_kit">
 +
 
 +
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 +
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 +
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 +
|-
 +
|style="text-align:center; width: 25%"|XML参数
 +
|style="text-align:center;width: 25%"|在JSON格式中对应的参数
 +
|style="text-align:center;"|说明描述
 +
|-
 +
|ToUserName
 +
|receiver_id
 +
|消息的接收者
 +
|-
 +
|FromUserName
 +
|sender_id
 +
|消息的发送者
 +
|-
 +
|CreateTime
 +
|created_at
 +
|消息创建时间
 +
|-
 +
|MsgType
 +
|type
 +
|position
 +
|-
 +
|Location_X
 +
|data:latitude
 +
|纬度
 +
|-
 +
|Location_Y
 +
|data:longitude
 +
|经度
 +
|-
 +
|Scale
 +
|暂无对应字段
 +
|该字段为空
 +
|-
 +
|Label
 +
|暂无对应字段
 +
|该字段为空
 +
|-
 +
|MsgId
 +
|暂无对应字段
 +
|该字段为空
 +
|}
 +
 
 +
5. 关注/取消关注,订阅/取消订阅消息的XML格式
 +
<pre>
 +
<xml>
 +
<ToUserName><![CDATA[toUser]]></ToUserName>
 +
<FromUserName><![CDATA[FromUser]]></FromUserName>
 +
<CreateTime>123456789</CreateTime>
 +
<MsgType><![CDATA[event]]></MsgType>
 +
<Event><![CDATA[subscribe]]></Event>
 +
</xml>
 +
</pre>
 +
 
 +
<div class="wiki_kit">
 +
 
 +
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 +
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 +
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 +
|-
 +
|style="text-align:center; width: 25%"|XML参数
 +
|style="text-align:center;width: 25%"|在JSON格式中对应的参数
 +
|style="text-align:center;"|说明描述
 +
|-
 +
|ToUserName
 +
|receiver_id
 +
|消息的接收者
 +
|-
 +
|FromUserName
 +
|sender_id
 +
|消息的发送者
 +
|-
 +
|CreateTime
 +
|created_at
 +
|消息创建时间
 +
|-
 +
|MsgType
 +
|type
 +
|event
 +
|-
 +
|Event
 +
|data:subtype
 +
|follow:关注事件,unfollow取消关注事件,subscribe订阅事件,unsubscribe订阅事件。
 +
|}
 +
 
 +
6. 扫描带参数二维码事件的XML格式
 +
用户扫描带场景值二维码时,可能推送以下两种事件:
 +
如果用户还未关注二维码生成方的官方账号,则扫描后进入关注列表;如果用户点击关注,则微博会给第三方推送scan_follow事件;
 +
<pre>
 +
<xml>
 +
<ToUserName><![CDATA[toUser]]></ToUserName>
 +
<FromUserName><![CDATA[FromUser]]></FromUserName>
 +
<CreateTime>123456789</CreateTime>
 +
<MsgType><![CDATA[event]]></MsgType>
 +
<Event><![CDATA[subscribe]]></Event>
 +
<EventKey><![CDATA[qrscene_123123]]></EventKey>
 +
<Ticket><![CDATA[TICKET]]></Ticket>
 +
</xml>
 +
</pre>
 +
 
 +
<div class="wiki_kit">
 +
 
 +
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 +
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 +
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 +
|-
 +
|style="text-align:center; width: 25%"|XML参数
 +
|style="text-align:center;width: 25%"|在JSON格式中对应的参数
 +
|style="text-align:center;"|说明描述
 +
|-
 +
|ToUserName
 +
|receiver_id
 +
|消息的接收者
 +
|-
 +
|FromUserName
 +
|sender_id
 +
|消息的发送者
 +
|-
 +
|CreateTime
 +
|created_at
 +
|消息创建时间
 +
|-
 +
|MsgType
 +
|type
 +
|event
 +
|-
 +
|Event
 +
|data:subtype
 +
|scan_follow
 +
|-
 +
|EventKey
 +
|data:key
 +
|事件Key值,action_name为前缀,后面为二维码的scene_id值
 +
|-
 +
|Ticket
 +
|data:ticket
 +
|二维码的ticket,可用来换取二维码图片
 +
|}
 +
 
 +
如果用户已经关注二维码生成方的官方账号,则扫描后进入和该官方账号的私信对话界面中,并且微博会给第三方推送scan事件;
 +
<pre>
 +
<xml>
 +
<ToUserName><![CDATA[toUser]]></ToUserName>
 +
<FromUserName><![CDATA[FromUser]]></FromUserName>
 +
<CreateTime>123456789</CreateTime>
 +
<MsgType><![CDATA[event]]></MsgType>
 +
<Event><![CDATA[SCAN]]></Event>
 +
<EventKey><![CDATA[SCENE_VALUE]]></EventKey>
 +
<Ticket><![CDATA[TICKET]]></Ticket>
 +
</xml>
 +
</pre>
 +
 
 +
<div class="wiki_kit">
 +
 
 +
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 +
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 +
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 +
|-
 +
|style="text-align:center; width: 25%"|XML参数
 +
|style="text-align:center;width: 25%"|在JSON格式中对应的参数
 +
|style="text-align:center;"|说明描述
 +
|-
 +
|ToUserName
 +
|receiver_id
 +
|消息的接收者
 +
|-
 +
|FromUserName
 +
|sender_id
 +
|消息的发送者
 +
|-
 +
|CreateTime
 +
|created_at
 +
|消息创建时间
 +
|-
 +
|MsgType
 +
|type
 +
|event
 +
|-
 +
|Event
 +
|data:subtype
 +
|scan
 +
|-
 +
|EventKey
 +
|data:key
 +
|事件Key值,action_name为前缀,后面为二维码的scene_id值
 +
|-
 +
|Ticket
 +
|data:ticket
 +
|二维码的ticket,可用来换取二维码图片
 +
|}
 +
 
 +
<h3>发送被动响应</h3>
 +
1. 回复text消息的XML格式
 +
<pre>
 +
<xml>
 +
<ToUserName><![CDATA[toUser]]></ToUserName>
 +
<FromUserName><![CDATA[fromUser]]></FromUserName>
 +
<CreateTime>1348831860</CreateTime>
 +
<MsgType><![CDATA[text]]></MsgType>
 +
<Content><![CDATA[this is a test]]></Content>
 +
</xml>
 +
</pre>
 +
 
 +
<div class="wiki_kit">
 +
 
 +
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 +
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 +
!colspan="3" scope="col" |<span id="参数说明">参数说明</span>
 +
|-
 +
|style="text-align:center; width: 25%"|XML参数
 +
|style="text-align:center;width: 25%"|在JSON格式中对应的参数
 +
|style="text-align:center;"|说明描述
 +
|-
 +
|ToUserName
 +
|receiver_id
 +
|消息的接收者
 +
|-
 +
|FromUserName
 +
|sender_id
 +
|消息的发送者
 +
|-
 +
|CreateTime
 +
|created_at
 +
|消息创建时间
 +
|-
 +
|MsgType
 +
|type
 +
|text
 +
|-
 +
|Content
 +
|data:text
 +
|私信内容;微博对于要回复的私信文本内容,要求文本大小必须小于300个汉字;如果超过300个汉字,则微博会自动截断超过部分
 +
|}
 +
 
 +
2. 回复图文消息的XML格式
 +
<pre>
 +
<ToUserName><![CDATA[toUser]]></ToUserName>
 +
<FromUserName><![CDATA[fromUser]]></FromUserName>
 +
<CreateTime>12345678</CreateTime>
 +
<MsgType><![CDATA[news]]></MsgType>
 +
<ArticleCount>2</ArticleCount>
 +
<Articles>
 +
<item>
 +
<Title><![CDATA[title1]]></Title>
 +
<Description><![CDATA[description1]]></Description>
 +
<PicUrl><![CDATA[picurl]]></PicUrl>
 +
<Url><![CDATA[url]]></Url>
 +
</item>
 +
<item>
 +
<Title><![CDATA[title]]></Title>
 +
<Description><![CDATA[description]]></Description>
 +
<PicUrl><![CDATA[picurl]]></PicUrl>
 +
<Url><![CDATA[url]]></Url>
 +
</item>
 +
</Articles>
 +
</pre>
 +
 
 +
<div class="wiki_kit">
 +
 
 +
{|width="100%" border="0" cellspacing="0" cellpadding="0" class="wiki_table"
 +
<html><colgroup><col class="tbF1"/><col class="tbF2" /><col /></colgroup></html>
 +
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 +
|-
 +
|style="text-align:center; width: 25%"|XML参数
 +
|style="text-align:center;width: 25%"|在JSON格式中对应的参数
 +
|style="text-align:center;"|说明描述
 +
|-
 +
|ToUserName
 +
|receiver_id
 +
|消息的接收者
 +
|-
 +
|FromUserName
 +
|sender_id
 +
|消息的发送者
 +
|-
 +
|CreateTime
 +
|created_at
 +
|消息创建时间
 +
|-
 +
|MsgType
 +
|type
 +
|articles
 +
|-
 +
|ArticleCount
 +
|无对应字段
 +
|该字段内容会自动忽略掉;另外微博最多支持8个图文,如果超过8个图文,则微博会自动截断超过部分;
 +
|-
 +
|Title
 +
|articles:display_name
 +
|图文的显示名称标题,文本大小必须小于60个汉字。
 +
|-
 +
|Description
 +
|articles:summary
 +
|图文的文字描述,文本大小必须小于300个汉字,支持空格与换行,三个或三个以上的空格、换行缩减为两个。
 +
|-
 +
|PicUrl
 +
|articles:image
 +
|图文的图片链接,仅支持PNG、JPG类型。
 +
|-
 +
|Url
 +
|articles:url
 +
|图文的URL地址,点击后跳转。
 +
|}

2014年6月9日 (一) 18:06的最后版本

目录

消息推送服务概述

当一个和认证用户相关的消息或者事件发生时(如某个用户向认证用户发送消息),微博服务器将POST消息数据包到开发者填写的URL上;


在开发者首次使用事件推送服务时,需要先通过一次校验来和微博服务器建立首次连接;微博服务器发送GET请求到开发者填写的URL上,校验参数如下表所示:

校验参数字段 字段类型 字段说明
signature string 微博加密签名,signature结合了开发者appsecret参数和请求中的timestamp参数,nonce参数
timestamp string 时间戳
nonce string 随机数
echostr string 随机字符串


signature参数的加密规则为:将appsecret参数,timestamp参数,nonce参数进行字典排序后,将三个参数字符串拼接成一个字符串进行sha1加密;开发者收到请求后,首先通过加密后的signature参数来校验GET请求的真实性,如果确认此次GET请求来自微博服务器,原样返回echostr参数内容就可以成功建立首次连接,否则连接失败。


建立首次连接后,后续每次微博事件推送时也都会带上signature、timestamp、nonce三个参数,开发者依然可以通过对signature的校验判断此条消息的真实性。校验方式与首次建立连接一致。

接收普通消息

建立首次连接后,当认证用户有新消息时,微博消息推送服务会POST消息数据包到开发者填写的URL上,当前支持的普通消息类型包括:

注意:需要对接收到的消息体type或subtype做兼容,当出现未知类型时可忽略此消息。)

纯文本类型私信和留言消息:text

{
    "type": "text",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "私信或留言内容",
    "data": {}
}
返回值说明
属性 值的类型 说明描述
type string text
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 私信内容
data string 消息内容,纯文本私信或留言为空


位置类型私信消息:position

{
    "type": "position",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "我在这里: http://t.cn/zQgLLYO",
    "data": {
        "longitude": "116.308586",
        "latitude": "39.982525"
      }
}
返回值说明
属性 值的类型 说明描述
type string mention
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 原位置私信文本,没有时用默认文案“发送了一个位置”
data string 消息内容
data:longitude string 经度
data:latitude string 纬度


语音类型私信和留言消息:voice

{
    "id": 1211260020031347,
    "type": "voice",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "发了一个语音消息",
    "data": {
        "vfid": 821804459,    // 发送者用此ID查看语音
        "tovfid": 821804469  // 接收者用此ID查看语音
    }
}
返回值说明
属性 值的类型 说明描述
type string voice
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 私信内容
data string 消息内容,纯文本私信或留言为空
data:vfid string 语音文件ID,发送者通过此ID读取语音
data:tovfid string 语音文件ID,接收者通过此ID读取语音
查看(下载)认证用户接收到的语音方法一
curl "https://upload.api.weibo.com/2/mss/msget?access_token=RECIPIENT_ACCESS_TOKEN&fid=TOVFID"

1,"RECIPIENT_ACCESS_TOKEN":返回结果中接收者(recipient_id)通过OAuth2授权返回的access_token;
2,"TOVFID":返回结果data字段中的tovfid。

查看(下载)认证用户接收到的语音方法二
curl -u "USERNAME:PASSWORD" "https://upload.api.weibo.com/2/mss/msget?source=APPKEY&fid=TOVFID"

1,"USERNAME:PASSWORD"为"recipient_id"(认证用户)的微博登录用户名和密码,此时方法二中的APPKEY应用所有者为"recipient_id";
2,"TOVFID":返回结果data字段中的tovfid。


图片类型私信和留言消息:image

{
    "type": "image",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "发了一张图片",
    "data": {
        "vfid": 821804459,     // 发送者用此ID查看图片
        "tovfid": 821804469    // 接收者用此ID查看图片
    }
}
返回值说明
属性 值的类型 说明描述
type string image
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 私信内容
data string 消息内容,纯文本私信或留言为空
data:vfid string 图片ID,发送者通过此ID读取图片
data:tovfid string 图片ID,接收者通过此ID读取图片
查看(下载)图片
curl "https://upload.api.weibo.com/2/mss/msget?access_token=RECIPIENT_ACCESS_TOKEN&fid=TOVFID"

1,"RECIPIENT_ACCESS_TOKEN":返回结果中接收者(receiver_id)通过OAuth2授权返回的access_token;
2,"TOVFID":返回结果data字段中的tovfid。

接收事件推送

建立首次连接后,当认证用户有新消息时,微博消息推送服务会POST消息数据包到开发者填写的URL上,当前支持的事件类型:

事件消息:event

{
    "type": "event",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "事件消息",
    "data": {
        "subtype": "EVENT",
        "key": "EVENT_KEY",
        "ticket": "TICKET",
    }
}
返回值说明
属性 值的类型 说明描述
type string event
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 默认文案。subtype为follow或unfollow时分别为“关注事件消息”、“取消关注事件消息”;为subscribe或unsubscribe时为触发订阅的私信关键词(如“dy”),非私信触发时(点击订阅按钮)为“订阅事件消息”、“取消订阅事件消息”;subtype为scan或scan_follow时为“扫描二维码”;
data string 消息内容
data:subtype string follow:关注事件,unfollow取消关注事件,subscribe订阅事件,unsubscribe订阅事件。scan和scan_follow为二维码扫描事件。
data:key string subtype为follow、unfollow、subscribe或unsubscribe时不返回
data:ticket string subtype为scan和scan_follow时才返回

被@消息:mention

说明:指定的认证用户需被授予接收“被@消息”权限,此接口才返回“被@消息”,申请可邮件 open_api@sina.com

{
    "type": "mention",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "被@的微博或评论文本信息",
    "data": {
        "subtype": "MENTION_TYPE,
        "key": "MENTION_KEY"
    }
}

// 默认仅返回可信用户的@,如需返回所有用户@,认证用户可访问此链接设置:http://account.weibo.com/set/message
返回值说明
属性 值的类型 说明描述
type string mention
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 被@的微博或评论文本信息
data string 消息内容
data:subtype string status:@的微博,comment:@的评论
data:key string 当subtype为status时为微博ID,为comment时为评论ID

发送被动响应

对于每一个POST请求,开发者在响应包(Get)中返回特定JSON包,对该消息进行响应。微博服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次;

关于重试的消息排重,推荐使用FromUserName + CreateTime 排重;

假如开发者无法保证在五秒内处理并回复,可以直接回复空串,微博服务器不会对此作任何处理,并且不会发起重试。

如果发送被动响应消息,则返回JSON格式如下: 注意:JSON格式中的data字段内容必须进行UTF8格式的URLEncode

{
    "result": true,
    "receiver_id":123456,
    "sender_id":123123,
    "type": "text",
    "data":"{}"
}


当前支持回复的私信类型(type)中,data参数支持的参数:

纯文本类型私信消息:text

{
    "text": "纯文本回复"
}
data参数支持的参数
参数名称 值的类型 是否必填 说明描述
text string true 要回复的私信文本内容。文本大小必须小于300个汉字。

举例: 当data对应json为{"text": "纯文本响应"} 时,则进行URLEncode后对应data参数值为:"%7B%22text%22%3A%20%22%E7%BA%AF%E6%96%87%E6%9C%AC%E5%93%8D%E5%BA%94%22%7D%20"。

图文类型私信消息:articles

{
    "articles": [
        {
            "display_name": "两个故事",
            "summary": "今天讲两个故事,分享给你。谁是公司?谁又是中国人?​",
            "image": "http://storage.mcp.weibo.cn/0JlIv.jpg",
            "url": "http://e.weibo.com/mediaprofile/article/detail?uid=1722052204&aid=983319"
        },
        ... //最多支持8个图文,建议为1或3个
    ]
}


data参数支持的参数
参数名称 值的类型 是否必填 说明描述
articles:display_name string true 图文的显示名称标题
articles:summary string true 图文的文字描述,大于等于2个图文时,仅显示第一个图文的描述
articles:image string true 图文的缩略显示图片,需为JPG、PNG格式,单图及多图第一张推荐使用280*155,多图非第一张推荐使用64*64
articles:url string true 图文的URL地址,点击后跳转


位置类型私信消息:position

{
    "longitude": "116.308586",
    "latitude": "39.982525"
}


data参数支持的参数
参数名称 值的类型 是否必填 说明描述
longitude string true 经度
latitude string true 纬度

微信XML格式兼容

除了上述的JSON格式,微博消息推送服务还支持“微信XML格式兼容”; 第三方可以通过http://open.weibo.com/wiki/Eps/push/set_format 接口来选择自己需要的格式是XML还是JSON;

XML格式详细描述如下:

接收消息推送

1. text消息的XML格式

<xml>
 <ToUserName><![CDATA[toUser]]></ToUserName>
 <FromUserName><![CDATA[fromUser]]></FromUserName> 
 <CreateTime>1348831860</CreateTime>
 <MsgType><![CDATA[text]]></MsgType>
 <Content><![CDATA[this is a test]]></Content>
 <MsgId>1234567890123456</MsgId>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type text
Content text 私信内容
MsgId 暂无对应字段 该字段内容为空

2. image消息的XML格式

<xml>
 <ToUserName><![CDATA[toUser]]></ToUserName>
 <FromUserName><![CDATA[fromUser]]></FromUserName>
 <CreateTime>1348831860</CreateTime>
 <MsgType><![CDATA[image]]></MsgType>
 <PicUrl><![CDATA[this is a url]]></PicUrl>
 <MediaId><![CDATA[media_id]]></MediaId>
 <MsgId>1234567890123456</MsgId>
 </xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type image
PicUrl 无对应字段 该字段内容为空
MediaID data:tovfid 私信内容
MsgId 暂无对应字段 该字段为空

3. voice消息的XML格式

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[fromUser]]></FromUserName>
<CreateTime>1357290913</CreateTime>
<MsgType><![CDATA[voice]]></MsgType>
<MediaId><![CDATA[media_id]]></MediaId>
<Format><![CDATA[Format]]></Format>
<MsgId>1234567890123456</MsgId>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type voice
PicUrl 无对应字段 该字段内容为空
MediaID data:tovfid 私信内容
Format 暂无对应字段 该字段为空
MsgId 暂无对应字段 该字段为空

4. position消息的XML格式

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[fromUser]]></FromUserName>
<CreateTime>1351776360</CreateTime>
<MsgType><![CDATA[location]]></MsgType>
<Location_X>23.134521</Location_X>
<Location_Y>113.358803</Location_Y>
<Scale>20</Scale>
<Label><![CDATA[位置信息]]></Label>
<MsgId>1234567890123456</MsgId>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type position
Location_X data:latitude 纬度
Location_Y data:longitude 经度
Scale 暂无对应字段 该字段为空
Label 暂无对应字段 该字段为空
MsgId 暂无对应字段 该字段为空

5. 关注/取消关注,订阅/取消订阅消息的XML格式

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe]]></Event>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type event
Event data:subtype follow:关注事件,unfollow取消关注事件,subscribe订阅事件,unsubscribe订阅事件。

6. 扫描带参数二维码事件的XML格式 用户扫描带场景值二维码时,可能推送以下两种事件: 如果用户还未关注二维码生成方的官方账号,则扫描后进入关注列表;如果用户点击关注,则微博会给第三方推送scan_follow事件;

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe]]></Event>
<EventKey><![CDATA[qrscene_123123]]></EventKey>
<Ticket><![CDATA[TICKET]]></Ticket>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type event
Event data:subtype scan_follow
EventKey data:key 事件Key值,action_name为前缀,后面为二维码的scene_id值
Ticket data:ticket 二维码的ticket,可用来换取二维码图片

如果用户已经关注二维码生成方的官方账号,则扫描后进入和该官方账号的私信对话界面中,并且微博会给第三方推送scan事件;

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[SCAN]]></Event>
<EventKey><![CDATA[SCENE_VALUE]]></EventKey>
<Ticket><![CDATA[TICKET]]></Ticket>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type event
Event data:subtype scan
EventKey data:key 事件Key值,action_name为前缀,后面为二维码的scene_id值
Ticket data:ticket 二维码的ticket,可用来换取二维码图片

发送被动响应

1. 回复text消息的XML格式

<xml>
 <ToUserName><![CDATA[toUser]]></ToUserName>
 <FromUserName><![CDATA[fromUser]]></FromUserName> 
 <CreateTime>1348831860</CreateTime>
 <MsgType><![CDATA[text]]></MsgType>
 <Content><![CDATA[this is a test]]></Content>
</xml>
参数说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type text
Content data:text 私信内容;微博对于要回复的私信文本内容,要求文本大小必须小于300个汉字;如果超过300个汉字,则微博会自动截断超过部分

2. 回复图文消息的XML格式

<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[fromUser]]></FromUserName>
<CreateTime>12345678</CreateTime>
<MsgType><![CDATA[news]]></MsgType>
<ArticleCount>2</ArticleCount>
<Articles>
<item>
<Title><![CDATA[title1]]></Title> 
<Description><![CDATA[description1]]></Description>
<PicUrl><![CDATA[picurl]]></PicUrl>
<Url><![CDATA[url]]></Url>
</item>
<item>
<Title><![CDATA[title]]></Title>
<Description><![CDATA[description]]></Description>
<PicUrl><![CDATA[picurl]]></PicUrl>
<Url><![CDATA[url]]></Url>
</item>
</Articles>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type articles
ArticleCount 无对应字段 该字段内容会自动忽略掉;另外微博最多支持8个图文,如果超过8个图文,则微博会自动截断超过部分;
Title articles:display_name 图文的显示名称标题,文本大小必须小于60个汉字。
Description articles:summary 图文的文字描述,文本大小必须小于300个汉字,支持空格与换行,三个或三个以上的空格、换行缩减为两个。
PicUrl articles:image 图文的图片链接,仅支持PNG、JPG类型。
Url articles:url 图文的URL地址,点击后跳转。
文档更新时间: 2014-06-09