2/messages/receive

跳转到: 导航, 搜索

消息推送接口

功能: 消息推送接口,长连接微博推送服务,接收推送给指定认证用户的新消息。当有微博用户给认证用户发送新消息时,推送服务将此新消息格式化后由此长连接推送给该应用。


接口调用地址: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为同一用户)

认证用户可接收的用户行为消息类型

连接建立后,当认证用户有新消息时,微博消息服务通过此连接向应用推送新消息,当前支持的消息类型:

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


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


值得你期待的更多消息类型:菜单点击、微博被转发、被评论、被赞、话题、支付...



接口调用失败返回

{
    "request": "/2/messages/receive.json",
    "error_code": 264XX,
    "error": "error message."
}