2/messages/receive
(→自定义回复实现步骤) |
|||
第52行: | 第52行: | ||
*1、蓝V用户开启自定义回复开发者模式 | *1、蓝V用户开启自定义回复开发者模式 | ||
**蓝V用户在企业微博后台开启开发者模式,设置成将自己的私信、留言等新消息托管给指定应用处理。 | **蓝V用户在企业微博后台开启开发者模式,设置成将自己的私信、留言等新消息托管给指定应用处理。 | ||
− | ** | + | **服务未正式开放,需提供您希望实现的功能或服务场景,我们评估后确定是否提前为您开通。 |
第61行: | 第61行: | ||
*3、回复接收到的新消息 | *3、回复接收到的新消息 | ||
**应用调用messages/reply接口对接收到的新消息进行处理,实现关键词自动回复或交由蓝 V 客服进行72小时人工应答,所有回复以微博私信方式到达用户。 | **应用调用messages/reply接口对接收到的新消息进行处理,实现关键词自动回复或交由蓝 V 客服进行72小时人工应答,所有回复以微博私信方式到达用户。 | ||
− | |||
− | |||
=好友邀请= | =好友邀请= |
2015年8月24日 (一) 10:38的最后版本
目录
消息服务是什么
- 消费服务是微博为应用、蓝V提供的与微博用户、粉丝进行消息交互的服务。通过此服务,应用、蓝V可在自己的产品中实现私信人工客服、私信自动回复、好友邀请等功能。
涵盖的主要功能模块:
自定义回复
- 使用消息服务自定义回复功能,蓝V 可以在自身的服务器或指定应用上接收微博用户与自己相关的行为消息,并可在72小时内按需进行文字、图文等私信的回复。
1、蓝V可接收的用户行为消息类型:
2、蓝V可回复的私信类型:
回复规则:每条接收到的私信72小时内可回复3次,关注事件等非私信消息72小时内可回复1次。
自定义回复 - 示例
1、应用于自动回复场景示例:
2、应用于人工客服场景示例:
自定义回复实现步骤
- 1、蓝V用户开启自定义回复开发者模式
- 蓝V用户在企业微博后台开启开发者模式,设置成将自己的私信、留言等新消息托管给指定应用处理。
- 服务未正式开放,需提供您希望实现的功能或服务场景,我们评估后确定是否提前为您开通。
- 2、应用连接、推送开始
- 应用调用messages/receive接口进行长连接,接收指定蓝V用户的新消息,若蓝V已授权指定应用托管微博私信、留言等消息箱服务,则连接成功,当有微博用户给蓝V发送新消息时,推送服务将此新消息格式化后由此长连接推送给该应用。
- 3、回复接收到的新消息
- 应用调用messages/reply接口对接收到的新消息进行处理,实现关键词自动回复或交由蓝 V 客服进行72小时人工应答,所有回复以微博私信方式到达用户。
好友邀请
- 使用消息服务好友邀请功能,应用、游戏可以在自身的客户端上激励用户邀请自己微博好友加入游戏,邀请将以Card形式私信触达好友。
好友邀请 - 示例
应用于游戏邀请场景示例:
- 好友邀请规则:
- 1,必须由用户主动发起;
- 2,每用户每小时通过每应用可邀请10个互粉好友。
消息推送接口
功能: 消息推送接口,长连接微博推送服务,接收推送给指定蓝V用户的新消息
接口调用地址:https://m.api.weibo.com/2/messages/receive.json
HTTP请求方式:GET
是否需要登陆:是
接口请求参数 | |||
---|---|---|---|
参数名称 | 值的类型 | 是否必填 | 说明描述 |
source | string | true | 申请应用时分配的AppKey,调用接口时候代表应用的唯一身份。 |
uid | int64 | true | 需要接收的蓝V用户ID。 |
since_id | int64 | false | 上次连接断开时的消息ID。保存断开后5分钟内的新消息,可以通过since_id获取断开五分钟内的新消息。 |
注意事项
- 1、为确保应用及V用户信息安全,此接口必须在服务器端调用;
- 2、调用接口的登录帐号为该appkey的所有者,需要使用所有者帐号通过Base Auth的方式;
- 3、如appkey已绑定IP地址,调用接口的请求IP须为绑定的IP;
- 4、指定的uid用户为蓝V;
- 5、指定的uid用户已设置成将自己的微博私信、留言等消息箱服务交给当前应用托管;
- 6、指定的uid用户已开启推送服务(当前托管即自动开启);
- 6、每条完整的新消息数据以json形式返回,默认采用UTF-8编码,且以\r\n分隔;
- 7、新消息来源用户为蓝V且已开启消息服务时,新消息不推送;
- 8、为缓解服务压力,请求建立后约每5分钟自动断开,应用需兼容根据最后一次获取的新消息ID重新调此接口连接;
调用举例:
curl -u "USERNAME:PASSWORD" "https://m.api.weibo.com/2/messages/receive.json?source=YOUR_APPKEY&uid=***"
连接建立后,当蓝V有新消息时,微博消息服务通过此连接向应用推送新消息,当前支持的消息类型:
- 1、事件消息:event
{ "id": 1211260020031346, "type": "event", "recipient_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 |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 默认文案。subtype为follow时为“关注事件消息”,为unfollow时为“取消关注事件消息”。 |
data | string | 消息内容 |
data:subtype | string | follow:关注事件,unfollow取消关注事件。 |
data:key | string | subtype为follow或unfollow时不返回 |
- 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 | text |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 私信内容 |
data | string | 消息内容,纯文本私信或留言为空 |
注意:需要对接收到的消息体type活subtype做兼容,当出现未知时可忽略此消息。
接口调用失败返回:
{ "request": "/2/messages/receive.json", "error_code": "264XX", "error": "error message." }
消息回复接口
功能: 消息回复接口,对接收到的指定新消息进行回复
接口调用地址:https://m.api.weibo.com/2/messages/reply.json
HTTP请求方式:POST
是否需要登陆:是
接口请求参数 | |||
---|---|---|---|
参数名称 | 值的类型 | 是否必填 | 说明描述 |
source | string | true | 申请应用时分配的AppKey,调用接口时候代表应用的唯一身份。 |
id | long | true | 需要响应的推送消息ID。 |
type | string | true | 需要以何种类型的消息进行响应。text:纯文本。 |
data | string | true | 消息数据,具体内容严格遵循type类型对应格式。必须为json做URLEncode后的字符串格式,采用UTF-8编码。 |
注意事项
- 1、为确保应用及V用户信息安全,此接口必须在服务器端调用;
- 2、调用接口的登录帐号必须为该appkey的所有者,需要使用所有者帐号通过Base Auth的方式;
- 3、如appkey已绑定IP地址,调用接口的请求IP须为绑定的IP;
- 4、指定ID的新消息对应的原接收者已设置成将自己的微博私信、留言等消息箱服务交给当前应用托管;
- 5、指定ID的新消息对应的原接收者已开启推送服务(当前托管即自动开启);
- 6、指定ID的新消息创建时间在72小时内;
- 7、指定的ID消息为“私信、留言”时72小时内可回复三次,为关注、取消关注事件等非私信消息72小时内可回复1次;
- 8、指定ID的新消息对应的原接收者身份发出此消息;
- 9、指定ID的新消息对应的原发送者将收到此消息;
- 10、发送者未被屏蔽或拉黑时消息进私信箱;
当前支持回复的消息类型(type)中,data参数支持的参数:
- 1、纯文本类型私信消息: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"。
则对应的调用为:
curl -u "USERNAME:PASSWORD" -d "source=YOUR_APPKEY&id=1307180000*****&type=text&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" "https://m.api.weibo.com/2/messages/reply.json" -k
- 2、图文类型私信消息: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" } ] }
data参数支持的参数 | |||
---|---|---|---|
参数名称 | 值的类型 | 是否必填 | 说明描述 |
articles:display_name | string | true | 图文的显示名称标题 |
articles:summary | string | true | 图文的文字描述 |
articles:image | string | true | 图文的缩略显示图片,需为JPG、PNG格式,单图及多图第一张推荐使用280*155,多图非第一张推荐使用64*64 |
articles:url | string | true | 图文的URL地址,点击后跳转 |
接口调用失败返回:
{ "request": "/2/messages/reply.json", "error_code": "264XX", "error": "error message." }
文档更新时间: 2015-08-24