Messages
第1行: | 第1行: | ||
− | .... | + | <div style="text-align:center;"><h1>乒乓消息接口使用手册</h1></div> |
+ | |||
+ | |||
+ | =乒乓消息接口简介= | ||
+ | *微博开放平台乒乓消息接口为应用、企业、媒体提供与微博用户进行消息交互的能力。 | ||
+ | |||
+ | |||
+ | =乒乓消息接口使用步骤= | ||
+ | |||
+ | *1、蓝V用户开启新消息推送 | ||
+ | **蓝V用户授权指定应用接收其新消息,并开启新消息推送(内测期间请使用蓝V官方账号微博私信@XXX 申请)。 | ||
+ | |||
+ | |||
+ | *2、应用连接、推送开始 | ||
+ | **应用调用messages/receive接口进行长连接,接收指定蓝V用户的新消息,若蓝V已指定该应用且开启服务,则连接成功,当有微博用户给蓝V发送新消息时,推送服务将此新消息格式化后由此长连接推送给该应用。 | ||
+ | |||
+ | |||
+ | *3、回复接收到的新消息 | ||
+ | **应用调用messages/reply接口对接收到的新消息进行回复,可根据语义识别后自动回复或由人工回复。每条新消息需在72小时内回复,且只能回复一次。 | ||
+ | |||
+ | |||
+ | =乒乓消息推送接口= | ||
+ | 功能: | ||
+ | 乒乓消息推送接口,长连接微博推送服务,接收推送给指定蓝V用户的新消息 | ||
+ | |||
+ | |||
+ | 接口调用地址:https://api.weibo.com/2/messages/receive.json | ||
+ | |||
+ | |||
+ | HTTP请求方式:GET | ||
+ | |||
+ | |||
+ | 是否需要登陆:是 | ||
+ | |||
+ | |||
+ | <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="4" scope="col" |<span id="接口请求参数">接口请求参数</span> | ||
+ | |- | ||
+ | |style="text-align:center; width: 12%"|参数名称 | ||
+ | |style="text-align:center;width: 12%"|值得类型 | ||
+ | |style="text-align:center;width: 11%"|是否必填 | ||
+ | |style="text-align:center;"|说明描述 | ||
+ | |- | ||
+ | |source | ||
+ | |string | ||
+ | |true | ||
+ | |申请应用时分配的AppKey,调用接口时候代表应用的唯一身份。 | ||
+ | |- | ||
+ | |uid | ||
+ | |int64 | ||
+ | |true | ||
+ | |需要接收的蓝V用户ID。 | ||
+ | |- | ||
+ | |since_id | ||
+ | |int64 | ||
+ | |false | ||
+ | |上次连接断开时的消息ID。保存断开后五分钟内的新消息,可以通过since_id获取断开五分钟内的新消息。 | ||
+ | |} | ||
+ | |||
+ | 注意事项 | ||
+ | *1、调用接口的登录帐号为该appkey的创建者,需要使用创建者帐号通过Base Auth的方式; | ||
+ | *2、调用接口的请求IP为该appkey绑定的IP地址; | ||
+ | *3、指定的ID用户为蓝V; | ||
+ | *4、指定的ID用户已设置成将自己的新消息推送给该appkey; | ||
+ | *5、指定的ID用户已开启推送; | ||
+ | *6、每条完整的新消息数据以json形式返回,默认采用UTF-8编码,且以\r\n分隔; | ||
+ | *7、蓝V与蓝V之间产生的新消息不推送; | ||
+ | *8、为缓解服务压力,请求建立后十分钟自动断开,应用需兼容重新调此接口链接。 | ||
+ | |||
+ | |||
+ | 连接建立后,当蓝V有新消息时,微博平台通过此连接向应用推送新消息,当前支持的消息类型: | ||
+ | |||
+ | |||
+ | *1、关注事件消息:follow | ||
+ | <pre> | ||
+ | { | ||
+ | "id": 1211260020031346, | ||
+ | "type": "follow", | ||
+ | "recipient_id": 1902538057, | ||
+ | "sender_id": 2489518277, | ||
+ | "created_at": "Mon Jul 16 18:09:20 +0800 2012", | ||
+ | "data": {} | ||
+ | } | ||
+ | </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;"|说明描述 | ||
+ | |- | ||
+ | |id | ||
+ | |string | ||
+ | |消息ID | ||
+ | |- | ||
+ | |type | ||
+ | |string | ||
+ | |follow | ||
+ | |- | ||
+ | |recipient_id | ||
+ | |int64 | ||
+ | |消息的接收者 | ||
+ | |- | ||
+ | |sender_id | ||
+ | |int64 | ||
+ | |消息的发送者 | ||
+ | |- | ||
+ | |created_at | ||
+ | |string | ||
+ | |消息创建时间 | ||
+ | |- | ||
+ | |text | ||
+ | |string | ||
+ | |默认文案 | ||
+ | |- | ||
+ | |data | ||
+ | |string | ||
+ | |消息内容,关注消息为空 | ||
+ | |} | ||
+ | |||
+ | *2、纯文本类型私信消息:text | ||
+ | <pre> | ||
+ | { | ||
+ | "id": 1211260020031346, | ||
+ | "type": "text", | ||
+ | "recipient_id": 1902538057, | ||
+ | "sender_id": 2489518277, | ||
+ | "created_at": "Mon Jul 16 18:09:20 +0800 2012", | ||
+ | "text": "关注事件", | ||
+ | "data": {} | ||
+ | } | ||
+ | </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;"|说明描述 | ||
+ | |- | ||
+ | |id | ||
+ | |string | ||
+ | |消息ID | ||
+ | |- | ||
+ | |type | ||
+ | |string | ||
+ | |follow | ||
+ | |- | ||
+ | |recipient_id | ||
+ | |int64 | ||
+ | |消息的接收者 | ||
+ | |- | ||
+ | |sender_id | ||
+ | |int64 | ||
+ | |消息的发送者 | ||
+ | |- | ||
+ | |created_at | ||
+ | |string | ||
+ | |消息创建时间 | ||
+ | |- | ||
+ | |text | ||
+ | |string | ||
+ | |私信内容 | ||
+ | |- | ||
+ | |data | ||
+ | |string | ||
+ | |消息内容,纯文本私信为空 | ||
+ | |} | ||
+ | |||
+ | |||
+ | *3、位置类型私信消息:position | ||
+ | <pre> | ||
+ | { | ||
+ | "id": 1211260020031347, | ||
+ | "type": "position", | ||
+ | "recipient_id": 1902538057, | ||
+ | "sender_id": 2489518277, | ||
+ | "created_at": "Mon Jul 16 18:09:20 +0800 2012", | ||
+ | "text": "分享了一个位置", | ||
+ | "data": { | ||
+ | "longitude": "344.3344", | ||
+ | "latitude": "232.343434" | ||
+ | } | ||
+ | } | ||
+ | </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;"|说明描述 | ||
+ | |- | ||
+ | |id | ||
+ | |string | ||
+ | |消息ID | ||
+ | |- | ||
+ | |type | ||
+ | |string | ||
+ | |position | ||
+ | |- | ||
+ | |recipient_id | ||
+ | |int64 | ||
+ | |消息的接收者 | ||
+ | |- | ||
+ | |sender_id | ||
+ | |int64 | ||
+ | |消息的发送者 | ||
+ | |- | ||
+ | |created_at | ||
+ | |string | ||
+ | |消息创建时间 | ||
+ | |- | ||
+ | |text | ||
+ | |string | ||
+ | |默认文案 | ||
+ | |- | ||
+ | |data | ||
+ | |string | ||
+ | |消息内容 | ||
+ | |- | ||
+ | |data:longitude | ||
+ | |string | ||
+ | |经度 | ||
+ | |- | ||
+ | |data:latitude | ||
+ | |string | ||
+ | |纬度 | ||
+ | |} | ||
+ | |||
+ | 注意:需要对接收到的消息体type做兼容,当出现未知type时可忽略此消息。 | ||
+ | |||
+ | |||
+ | 接口调用失败返回: | ||
+ | <pre> | ||
+ | { | ||
+ | "request": "/2/messages/receive.json", | ||
+ | "error_code": "203XX", | ||
+ | "error": "error message." | ||
+ | } | ||
+ | </pre> | ||
+ | |||
+ | |||
+ | =乒乓消息回复接口= | ||
+ | 功能: | ||
+ | 乒乓消息响应接口,对接收到的指定新消息进行回复 | ||
+ | |||
+ | |||
+ | 接口调用地址:https://api.weibo.com/2/messages/reply.json | ||
+ | |||
+ | |||
+ | HTTP请求方式:POST | ||
+ | |||
+ | |||
+ | 是否需要登陆:是 | ||
+ | |||
+ | |||
+ | <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="4" scope="col" |<span id="接口请求参数">接口请求参数</span> | ||
+ | |- | ||
+ | |style="text-align:center; width: 12%"|参数名称 | ||
+ | |style="text-align:center;width: 12%"|值得类型 | ||
+ | |style="text-align:center;width: 11%"|是否必填 | ||
+ | |style="text-align:center;"|说明描述 | ||
+ | |- | ||
+ | |source | ||
+ | |string | ||
+ | |true | ||
+ | |申请应用时分配的AppKey,调用接口时候代表应用的唯一身份。 | ||
+ | |- | ||
+ | |id | ||
+ | |int64 | ||
+ | |true | ||
+ | |需要响应的推送消息ID。 | ||
+ | |- | ||
+ | |type | ||
+ | |string | ||
+ | |true | ||
+ | |需要以何种类型的消息进行响应。text:纯文本。 | ||
+ | |- | ||
+ | |data | ||
+ | |string | ||
+ | |true | ||
+ | |消息数据,具体内容严格遵循type类型对应格式。必须为json做URLEncode后的字符串格式,采用UTF-8编码。字符串长度不超过2512个字节。 | ||
+ | |} | ||
+ | |||
+ | 注意事项 | ||
+ | *1、调用接口的登录帐号必须为该appkey的创建者,需要使用创建者帐号通过Base Auth的方式; | ||
+ | *2、指定ID的新消息创建时间在72小时内; | ||
+ | *3、指定ID的新消息只能回复一次,多次回复报错; | ||
+ | *4、指定ID的新消息对应的原接收者身份发出此消息; | ||
+ | *5、指定ID的新消息对应的原发送者将收到此消息; | ||
+ | *6、发送者未被屏蔽或拉黑时消息进私信箱。 | ||
+ | |||
+ | |||
+ | 当前支持回复的消息类型中,data参数支持的格式: | ||
+ | *1、纯文本类型私信消息:text | ||
+ | <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="4" scope="col" |<span id="接口请求参数">接口请求参数</span> | ||
+ | |- | ||
+ | |style="text-align:center; width: 12%"|参数名称 | ||
+ | |style="text-align:center;width: 12%"|值得类型 | ||
+ | |style="text-align:center;width: 11%"|是否必填 | ||
+ | |style="text-align:center;"|说明描述 | ||
+ | |- | ||
+ | |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"。 | ||
+ | |||
+ | |||
+ | 接口调用失败返回: | ||
+ | <pre> | ||
+ | { | ||
+ | "request": "/2/messages/reply.json", | ||
+ | "error_code": "203XX", | ||
+ | "error": "error message." | ||
+ | } | ||
+ | </pre> | ||
+ | |||
+ | __NOTOC__ |
2013年6月25日 (二) 19:06的版本
乒乓消息接口使用手册
乒乓消息接口简介
- 微博开放平台乒乓消息接口为应用、企业、媒体提供与微博用户进行消息交互的能力。
乒乓消息接口使用步骤
- 1、蓝V用户开启新消息推送
- 蓝V用户授权指定应用接收其新消息,并开启新消息推送(内测期间请使用蓝V官方账号微博私信@XXX 申请)。
- 2、应用连接、推送开始
- 应用调用messages/receive接口进行长连接,接收指定蓝V用户的新消息,若蓝V已指定该应用且开启服务,则连接成功,当有微博用户给蓝V发送新消息时,推送服务将此新消息格式化后由此长连接推送给该应用。
- 3、回复接收到的新消息
- 应用调用messages/reply接口对接收到的新消息进行回复,可根据语义识别后自动回复或由人工回复。每条新消息需在72小时内回复,且只能回复一次。
乒乓消息推送接口
功能: 乒乓消息推送接口,长连接微博推送服务,接收推送给指定蓝V用户的新消息
接口调用地址:https://api.weibo.com/2/messages/receive.json
HTTP请求方式:GET
是否需要登陆:是
接口请求参数 | |||
---|---|---|---|
参数名称 | 值得类型 | 是否必填 | 说明描述 |
source | string | true | 申请应用时分配的AppKey,调用接口时候代表应用的唯一身份。 |
uid | int64 | true | 需要接收的蓝V用户ID。 |
since_id | int64 | false | 上次连接断开时的消息ID。保存断开后五分钟内的新消息,可以通过since_id获取断开五分钟内的新消息。 |
注意事项
- 1、调用接口的登录帐号为该appkey的创建者,需要使用创建者帐号通过Base Auth的方式;
- 2、调用接口的请求IP为该appkey绑定的IP地址;
- 3、指定的ID用户为蓝V;
- 4、指定的ID用户已设置成将自己的新消息推送给该appkey;
- 5、指定的ID用户已开启推送;
- 6、每条完整的新消息数据以json形式返回,默认采用UTF-8编码,且以\r\n分隔;
- 7、蓝V与蓝V之间产生的新消息不推送;
- 8、为缓解服务压力,请求建立后十分钟自动断开,应用需兼容重新调此接口链接。
连接建立后,当蓝V有新消息时,微博平台通过此连接向应用推送新消息,当前支持的消息类型:
- 1、关注事件消息:follow
{ "id": 1211260020031346, "type": "follow", "recipient_id": 1902538057, "sender_id": 2489518277, "created_at": "Mon Jul 16 18:09:20 +0800 2012", "data": {} }
返回值说明 | ||
---|---|---|
属性 | 值得类型 | 说明描述 |
id | string | 消息ID |
type | string | follow |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 默认文案 |
data | string | 消息内容,关注消息为空 |
- 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 | follow |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 私信内容 |
data | string | 消息内容,纯文本私信为空 |
- 3、位置类型私信消息:position
{ "id": 1211260020031347, "type": "position", "recipient_id": 1902538057, "sender_id": 2489518277, "created_at": "Mon Jul 16 18:09:20 +0800 2012", "text": "分享了一个位置", "data": { "longitude": "344.3344", "latitude": "232.343434" } }
返回值说明 | ||
---|---|---|
属性 | 值得类型 | 说明描述 |
id | string | 消息ID |
type | string | position |
recipient_id | int64 | 消息的接收者 |
sender_id | int64 | 消息的发送者 |
created_at | string | 消息创建时间 |
text | string | 默认文案 |
data | string | 消息内容 |
data:longitude | string | 经度 |
data:latitude | string | 纬度 |
注意:需要对接收到的消息体type做兼容,当出现未知type时可忽略此消息。
接口调用失败返回:
{ "request": "/2/messages/receive.json", "error_code": "203XX", "error": "error message." }
乒乓消息回复接口
功能: 乒乓消息响应接口,对接收到的指定新消息进行回复
接口调用地址:https://api.weibo.com/2/messages/reply.json
HTTP请求方式:POST
是否需要登陆:是
接口请求参数 | |||
---|---|---|---|
参数名称 | 值得类型 | 是否必填 | 说明描述 |
source | string | true | 申请应用时分配的AppKey,调用接口时候代表应用的唯一身份。 |
id | int64 | true | 需要响应的推送消息ID。 |
type | string | true | 需要以何种类型的消息进行响应。text:纯文本。 |
data | string | true | 消息数据,具体内容严格遵循type类型对应格式。必须为json做URLEncode后的字符串格式,采用UTF-8编码。字符串长度不超过2512个字节。 |
注意事项
- 1、调用接口的登录帐号必须为该appkey的创建者,需要使用创建者帐号通过Base Auth的方式;
- 2、指定ID的新消息创建时间在72小时内;
- 3、指定ID的新消息只能回复一次,多次回复报错;
- 4、指定ID的新消息对应的原接收者身份发出此消息;
- 5、指定ID的新消息对应的原发送者将收到此消息;
- 6、发送者未被屏蔽或拉黑时消息进私信箱。
当前支持回复的消息类型中,data参数支持的格式:
- 1、纯文本类型私信消息:text
接口请求参数 | |||
---|---|---|---|
参数名称 | 值得类型 | 是否必填 | 说明描述 |
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"。
接口调用失败返回:
{ "request": "/2/messages/reply.json", "error_code": "203XX", "error": "error message." }