2/messages/receive
第1行: | 第1行: | ||
=消息推送接口= | =消息推送接口= | ||
功能: | 功能: | ||
− | + | 消息推送接口,长连接微博推送服务,接收推送给指定认证用户的新消息。当有微博用户给认证用户发送新消息时,推送服务将此新消息格式化后由此长连接推送给该应用。 | |
第32行: | 第32行: | ||
|int64 | |int64 | ||
|true | |true | ||
− | | | + | |需要接收的认证用户ID,该用户已指定当前应用为其开发且已开启“开发模式”,详见:[[粉丝服务开发模式指南|粉丝服务开发模式指南]]。 |
|- | |- | ||
|since_id | |since_id | ||
第41行: | 第41行: | ||
==注意事项== | ==注意事项== | ||
− | * | + | *1、为确保应用及认证用户信息安全,此接口必须在服务器端调用; |
− | * | + | *2、调用接口的登录用户必须为当前应用的所有者,通过Base Auth的方式调用,详见type为text时的举例; |
− | * | + | *3、<font style="color:red">非常重要:</font>此接口非短连接接口,需要以长连接方式调用,链接建立后有新的消息产生时每条完整的新消息数据以json形 |
− | + | **式返回,默认采用UTF-8编码,且以\r\n分隔; | |
− | + | *4、<font style="color:red">非常重要:</font>为缓解服务压力,请求建立后约每5分钟会自动断开(如未自动断开请用程序断开),需要保留最后一次获取的 | |
− | + | **消息ID作为重新请求接口的since_id参数; | |
− | + | *5、<font style="color:red">非常重要:</font>当接收到的消息类型为text,且内容为“dy”或“td”时,分别表示“订阅”和“退订”;当接收到的消息类型为event, | |
− | + | ||
− | * | + | |
− | ** | + | |
− | * | + | |
**且subtype为“subscribe”或“unsubscribe”时,分别表示“订阅”和“退订”。 | **且subtype为“subscribe”或“unsubscribe”时,分别表示“订阅”和“退订”。 | ||
− | + | *6、新消息来源用户也为认证用户且已开启消息服务时,新消息不推送; | |
==调用举例== | ==调用举例== | ||
第59行: | 第55行: | ||
<pre> | <pre> | ||
curl -u "USERNAME:PASSWORD" "https://m.api.weibo.com/2/messages/receive.json?source=YOUR_APPKEY&uid=***" | curl -u "USERNAME:PASSWORD" "https://m.api.weibo.com/2/messages/receive.json?source=YOUR_APPKEY&uid=***" | ||
− | // "USERNAME:PASSWORD" | + | // "USERNAME:PASSWORD"为应用所有者用户名和密码(注意不是uid认证用户的,除非应用所有者和uid为同一用户) |
</pre> | </pre> | ||
− | == | + | ==认证用户可接收的用户行为消息类型== |
− | + | 连接建立后,当认证用户有新消息时,微博消息服务通过此连接向应用推送新消息,当前支持的消息类型: | |
第303行: | 第299行: | ||
|} | |} | ||
<pre> | <pre> | ||
− | + | 查看(下载)认证用户接收到的语音方法一 | |
curl "https://upload.api.weibo.com/2/mss/msget?access_token=RECIPIENT_ACCESS_TOKEN&fid=TOVFID" | curl "https://upload.api.weibo.com/2/mss/msget?access_token=RECIPIENT_ACCESS_TOKEN&fid=TOVFID" | ||
第309行: | 第305行: | ||
2,"TOVFID":返回结果data字段中的tovfid。 | 2,"TOVFID":返回结果data字段中的tovfid。 | ||
− | + | 查看(下载)认证用户接收到的语音方法二 | |
curl -u "USERNAME:PASSWORD" "https://upload.api.weibo.com/2/mss/msget?source=APPKEY&fid=TOVFID" | curl -u "USERNAME:PASSWORD" "https://upload.api.weibo.com/2/mss/msget?source=APPKEY&fid=TOVFID" | ||
− | 1,"USERNAME:PASSWORD"为"recipient_id" | + | 1,"USERNAME:PASSWORD"为"recipient_id"(认证用户)的微博登录用户名和密码,此时方法二中的APPKEY应用所有者为"recipient_id"; |
2,"TOVFID":返回结果data字段中的tovfid。 | 2,"TOVFID":返回结果data字段中的tovfid。 | ||
</pre> | </pre> | ||
第388行: | 第384行: | ||
<h3>6、被@消息:mention</h3> | <h3>6、被@消息:mention</h3> | ||
− | + | 说明:指定的认证用户需被授予接收“被@消息”权限,此接口才返回“被@消息”,申请可邮件 [mailto:open_api@sina.com open_api@sina.com] 。 | |
<pre> | <pre> | ||
{ | { | ||
第403行: | 第399行: | ||
} | } | ||
− | // 默认仅返回可信用户的@,如需返回所有用户@ | + | // 默认仅返回可信用户的@,如需返回所有用户@,认证用户可访问此链接设置:http://account.weibo.com/set/message |
</pre> | </pre> | ||
<div class="wiki_kit"> | <div class="wiki_kit"> |
2014年1月2日 (四) 10:55的版本
消息推送接口
功能: 消息推送接口,长连接微博推送服务,接收推送给指定认证用户的新消息。当有微博用户给认证用户发送新消息时,推送服务将此新消息格式化后由此长连接推送给该应用。
接口调用地址:https://m.api.weibo.com/2/messages/receive.json
HTTP请求方式:GET
是否需要登陆:是
接口请求参数 | |||
---|---|---|---|
参数名称 | 值的类型 | 是否必填 | 说明描述 |
source | string | true | 申请应用时分配的AppKey,调用接口时候代表应用的唯一身份。 |
uid | int64 | true | 需要接收的认证用户ID,该用户已指定当前应用为其开发且已开启“开发模式”,详见:粉丝服务开发模式指南。 |
since_id | int64 | false | 上次连接断开时的消息ID。保存断开后5分钟内的新消息,可以通过since_id获取断开五分钟内的新消息。 |
注意事项
- 1、为确保应用及认证用户信息安全,此接口必须在服务器端调用;
- 2、调用接口的登录用户必须为当前应用的所有者,通过Base Auth的方式调用,详见type为text时的举例;
- 3、非常重要:此接口非短连接接口,需要以长连接方式调用,链接建立后有新的消息产生时每条完整的新消息数据以json形
- 式返回,默认采用UTF-8编码,且以\r\n分隔;
- 4、非常重要:为缓解服务压力,请求建立后约每5分钟会自动断开(如未自动断开请用程序断开),需要保留最后一次获取的
- 消息ID作为重新请求接口的since_id参数;
- 5、非常重要:当接收到的消息类型为text,且内容为“dy”或“td”时,分别表示“订阅”和“退订”;当接收到的消息类型为event,
- 且subtype为“subscribe”或“unsubscribe”时,分别表示“订阅”和“退订”。
- 6、新消息来源用户也为认证用户且已开启消息服务时,新消息不推送;
调用举例
curl -u "USERNAME:PASSWORD" "https://m.api.weibo.com/2/messages/receive.json?source=YOUR_APPKEY&uid=***" // "USERNAME:PASSWORD"为应用所有者用户名和密码(注意不是uid认证用户的,除非应用所有者和uid为同一用户)
认证用户可接收的用户行为消息类型
连接建立后,当认证用户有新消息时,微博消息服务通过此连接向应用推送新消息,当前支持的消息类型:
1、事件消息:event
{ "id": 1211260020031346, "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" } }
返回值说明 | ||
---|---|---|
属性 | 值的类型 | 说明描述 |
id | string | 消息ID |
type | string | event |
receiver_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 默认文案。subtype为follow或unfollow时分别为“关注事件消息”、“取消关注事件消息”;为subscribe或unsubscribe时为触发订阅的私信关键词(如“dy”),非私信触发时(点击订阅按钮)为“订阅事件消息”、“取消订阅事件消息”。 |
data | string | 消息内容 |
data:subtype | string | follow:关注事件,unfollow取消关注事件,subscribe订阅事件,unsubscribe订阅事件。 |
data:key | string | subtype为follow、unfollow、subscribe或unsubscribe时不返回 |
2、纯文本类型私信和留言消息:text
{ "id": 1211260020031346, "type": "text", "receiver_id": 1902538057, "sender_id": 2489518277, "created_at": "Mon Jul 16 18:09:20 +0800 2012", "text": "私信或留言内容", "data": {} }
返回值说明 | ||
---|---|---|
属性 | 值的类型 | 说明描述 |
id | string | 消息ID |
type | string | text |
receiver_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 私信内容 |
data | string | 消息内容,纯文本私信或留言为空 |
3、位置类型私信消息:position
{ "id": 1211260020031347, "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" } }
返回值说明 | ||
---|---|---|
属性 | 值的类型 | 说明描述 |
id | string | 消息ID |
type | string | mention |
receiver_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 原位置私信文本,没有时用默认文案“发送了一个位置” |
data | string | 消息内容 |
data:longitude | string | 经度 |
data:latitude | string | 纬度 |
4、语音类型私信和留言消息: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查看语音 } }
返回值说明 | ||
---|---|---|
属性 | 值的类型 | 说明描述 |
id | string | 消息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。
5、图片类型私信和留言消息:image
{ "id": 1211260020031347, "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查看图片 } }
返回值说明 | ||
---|---|---|
属性 | 值的类型 | 说明描述 |
id | string | 消息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。
6、被@消息:mention
说明:指定的认证用户需被授予接收“被@消息”权限,此接口才返回“被@消息”,申请可邮件 open_api@sina.com 。
{ "id": 1211260020031346, "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
返回值说明 | ||
---|---|---|
属性 | 值的类型 | 说明描述 |
id | string | 消息ID |
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 |
注意:需要对接收到的消息体type或subtype做兼容,当出现未知类型时可忽略此消息。
接口调用失败返回
{ "request": "/2/messages/receive.json", "error_code": 264XX, "error": "error message." }