消息推送服务

跳转到: 导航, 搜索
(微信XML格式兼容)
(微信XML格式兼容)
第535行: 第535行:
 
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 
|-
 
|-
|style="text-align:center; width: 12%"|XML参数
+
|style="text-align:center; width: 20%"|XML参数
|style="text-align:center;width: 12%"|对应JSON中的参数
+
|style="text-align:center;width: 20%"|对应JSON中的参数
 
|style="text-align:center;"|说明描述
 
|style="text-align:center;"|说明描述
 
|-
 
|-
第583行: 第583行:
 
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 
!colspan="3" scope="col" |<span id="返回值说明">返回值说明</span>
 
|-
 
|-
|style="text-align:center; width: 12%"|XML参数
+
|style="text-align:center; width: 20%"|XML参数
|style="text-align:center;width: 12%"|对应JSON中的参数
+
|style="text-align:center;width: 20%"|对应JSON中的参数
 
|style="text-align:center;"|说明描述
 
|style="text-align:center;"|说明描述
 
|-
 
|-
第602行: 第602行:
 
|type
 
|type
 
|image
 
|image
 +
|-
 
|PicUrl
 
|PicUrl
 
|无对应字段
 
|无对应字段

2014年3月30日 (日) 15:07的版本

目录

消息推送服务概述

当一个和认证用户相关的消息或者事件发生时(如某个用户向认证用户发送消息),微博服务器将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做兼容,当出现未知类型时可忽略此消息。)

事件消息: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时才返回


纯文本类型私信和留言消息: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。


被@消息: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包,对该消息进行响应。微博服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次; 关于重试的消息排重,推荐使用消息ID排重。

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

如果发送被动响应消息,则返回JSON格式如下:

{
    "result": true,
    "tpye": "text",
    "data":"{}"
}


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

纯文本类型私信消息:text

{
    "text": "纯文本回复"
}
data参数支持的参数
参数名称 值的类型 是否必填 说明描述
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"。

图文类型私信消息: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格式兼容”,具体来说如下:

接收消息推送

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 暂无对应字段 该字段为空
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe]]></Event>
</xml>
返回值说明
XML参数 对应JSON中的参数 说明描述
MsgType type event
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
Event data:subtype follow:关注事件,unfollow取消关注事件,subscribe订阅事件,unsubscribe订阅事件。scan和scan_follow为二维码扫描事件。