生活号事件订阅

开发者可以根据业务需要选择性订阅支付宝网关推送的事件消息,从而简化业务模型,降低服务器负载。

2014年12月06日凌晨00:00之前入驻的商户的“进入事件”默认订阅,之后入驻的商户的“进入事件”默认不订阅。

按以下步骤可以进行事件订阅设置:

第一步:进入开放平台管理中心,进入生活号应用配置详情页,找到“事件订阅与重试机制”;

第二步:点击“设置”按钮,在弹出的浮层上选择需要订阅的事件消息,去除不需要订阅的事件消息,点击“确定”即可完成订阅;

注意:

1. 订阅与取消订阅完成之后立即生效。

2. 菜单点击事件及接入验证消息为特殊事件,不能取消订阅。

3. 若使用生活号demo进行开发,应用上线时请确保屏蔽或删除demo中原有的事件订阅并发送消息代码,否则应用上线后,若发生对应的订阅事件(如文本消息事件),商户生活号应用可能会调用接口向用户发送一些demo代码中的消息,给用户造成困扰! 

事件接收方

设置事件接收方可以指定接收该生活号订阅事件消息的应用网关,若商户自己开发生活号应用,则此处不需要设置,此时订阅事件消息会推送到商户应用网关,若商户需要将生活号授权给其他isv进行管理,可通过第三方应用授权对isv应用授权,然后将事件接收方设置为该isv的应用,设置之后,支付宝会将此生活号的订阅事件消息推送往该isv的应用网关,isv可通过商户授权时获取到的app_auth_token代替商户调用生活号相关接口,帮助商户运营生活号。

如下图所示:

重试机制

重试机制可以防止因网络抖动等原因造成的事件消息丢失,开启后支付宝将对发送失败的消息重试2次,每次间隔5秒。2014年12月06日凌晨00:00之前入驻的商户的重试机制默认打开,之后入驻的商户的重试机制默认不打开。

按以下步骤可以进行重试机制设置:

第一步:进入开放平台管理中心,进入生活号应用配置详情页,找到“事件订阅与重试机制”;

第二步:如果尚未开启重试机制,点击“开启”按钮会弹出“确定开启重试机制”对话框,点击确定即可开启重试机制;

第三步:如果已经开启重试机制,想要关闭,点击“关闭”按钮会弹出“确定关闭重试机制”对话框,点击确定即可关闭重试机制;

重试机制设置完毕后立即生效。菜单点击事件及接入验证消息不作重试。

返回成功消息

开发者网关接收到支付宝推送的任何订阅事件消息后,必须同步回复一条接收成功消息,否则支付宝会认为该消息推送失败,若重试机制开启,支付宝会重新推送该消息。

回复消息的格式如下:

<XML>
    <ToUserId><![CDATA[2088802608984030]]></ToUserId>
    <AppId><![CDATA[2014042900005397]]></AppId>
    <CreateTime>![CDATA[1406165628612]]</CreateTime>
    <MsgType><![CDATA[ack]]></MsgType>
</XML>

 

事件消息

消息标识:alipay.mobile.public.message.notify

使用场景举例:接收用户操作事件通知,例如关注生活号、菜单点击等,开发者可以使用异步发送消息功能向用户回复消息,实现诸如查询余额,推送最新优惠消息等业务逻辑。

当开发者网关接收消息成功后,必须同步回复一条接收成功消息。

用户在与生活号账号交互的过程中会产生以下4种事件:

 

关注与取消关注事件

支付宝网关向开发者网关发送的POST消息中biz_content的内容示例如下:

<XML>
    <AppId><![CDATA[2014070100171523]]></AppId>
    <FromUserId><![CDATA[20882837462837462837462837461234]]></FromUserId>
    <FromAlipayUserId><![CDATA[2088283746283746]]></FromAlipayUserId>
    <CreateTime><![CDATA[1405943673657]]></CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <EventType><![CDATA[follow]]></EventType>
    <ActionParam><![CDATA[{"scene":{"sceneId": "1234"}}]]></ActionParam>
    <AgreementId><![CDATA[]]></AgreementId>
    <AccountNo><![CDATA[]]></AccountNo>
    <UserInfo><![CDATA[{"logon_id":"135****1009","user_name":"*iuxu527"}]]></UserInfo>
</XML>
参数名 是否必须 参数说明

AppId

服务窗账号ID

FromUserId

用户OpenId。2016年1月1日起,支付宝用于唯一标识用户的OpenId(32位)由于业务原因计划于2016年9月份废弃,FromAlipayUserId将替代FromUserId作为用户唯一性标示

FromAlipayUserId

用户userid,用户唯一标识

CreateTime

消息创建时间

MsgType

消息类型,事件类消息固定为event

EventType

事件类型。

follow:关注事件;

unfollow:取消关注事件

ActionParam

用户从特定场景(比如扫描开发者自定义的二维码,或者点击带参短链接)关注服务窗时,值为开发者自定义参数,详见带参推广二维码以及带参推广短链接

AgreementId

空值

AccountNo

空值

MsgId

消息Id,用于消息去重,开启了重试机制才会有这个字段

UserInfo

支付宝的用户信息,JSON格式,包含加星的用户账号及加星的用户名

UserInfo的一个示例:
{
  "logon_id": "135**1009",
  "user_name": "*iuxu527"
}

 

进入事件

2014年12月06日凌晨00:00及之后入驻的商家进入事件默认不订阅,开发者可以通过事件订阅功能订阅该事件。

支付宝网关向开发者网关发送的POST消息中biz_content的内容示例如下:

<XML>
    <AppId><![CDATA[2014070100171523]]></AppId>
    <FromUserId><![CDATA[20882837462837462837462837461234]]></FromUserId>
    <FromAlipayUserId><![CDATA[2088283746283746]]></FromAlipayUserId>
    <CreateTime><![CDATA[1405943673657]]></CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <EventType><![CDATA[enter]]></EventType>
    <ActionParam><![CDATA[{"scene":{"sceneId": "1234"}}]]></ActionParam>
    <AgreementId><![CDATA[]]></AgreementId>
    <AccountNo><![CDATA[]]></AccountNo>
    <UserInfo><![CDATA[{"logon_id":"135****1009","user_name":"*iuxu527"}]]></UserInfo>
</XML> 
参数名 是否必须 参数说明

AppId

生活号账号ID

FromUserId

用户OpenId。2016年1月1日起,支付宝用于唯一标识用户的OpenId(32位)由于业务原因计划于2016年9月份废弃,FromAlipayUserId将替代FromUserId作为用户唯一性标示

FromAlipayUserId

用户userid,用户唯一标识

CreateTime

消息创建时间

MsgType

消息类型,事件类消息固定为event

EventType

事件类型,固定为enter

ActionParam

用户从特定场景(比如扫描开发者自定义的二维码,或者点击带参短链接)进入生活号时,值为开发者自定义参数,详见带参推广二维码以及带参推广短链接

AgreementId

空值

AccountNo

空值

MsgId

消息Id,用于消息去重,开启了重试机制才会有这个字段

UserInfo

支付宝的用户信息,JSON格式,包含加星的用户账号及加星的用户名

 

菜单点击事件

菜单分为事件型菜单和链接型菜单,用户点击事件型菜单时,支付宝网关向开发者网关发送的POST消息中biz_content的内容示例如下:

<XML>
    <AppId><![CDATA[2014070100171523]]></AppId>
    <FromUserId><![CDATA[20882837462837462837462837461234]]></FromUserId>
    <FromAlipayUserId><![CDATA[2088283746283746]]></FromAlipayUserId>
    <CreateTime><![CDATA[1405943673657]]></CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <EventType><![CDATA[click]]></EventType>
    <ActionParam><![CDATA[test_menu_key]]></ActionParam>
    <AgreementId><![CDATA[]]></AgreementId>
    <AccountNo><![CDATA[]]></AccountNo>
    <UserInfo><![CDATA[{"logon_id":"135****1009","user_name":"*iuxu527"}]]></UserInfo>
</XML>

 

参数名 是否必须 参数说明

AppId

生活号账号ID

FromUserId

用户OpenId。2016年1月1日起,支付宝用于唯一标识用户的OpenId(32位)由于业务原因计划于2016年9月份废弃,FromAlipayUserId将替代FromUserId作为用户唯一性标示

FromAlipayUserId

用户userid,用户唯一标识

CreateTime

消息创建时间

MsgType

消息类型,事件类消息固定为event

EventType

事件类型,固定为click

ActionParam

行为参数,菜单中设置的actionParam值,详见创建菜单

AgreementId

空值

AccountNo

空值

MsgId

消息Id,用于消息去重,开启了重试机制才会有这个字段

UserInfo

支付宝的用户信息,JSON格式,包含加星的用户账号及加星的用户名

 

文本消息

消息标识:alipay.mobile.public.message.notify

使用场景举例:接收用户主动发送的文字消息,开发者可以使用异步单发消息功能向用户回复消息,实现诸如查询余额、推送最新优惠消息、客服等业务逻辑。

当开发者网关接收消息成功之后,必须同步回复一条接收成功消息。

支付宝网关发送的POST消息中biz_content的内容示例如下:

<XML>
   <Text>
     <Content><![CDATA[Hello]]></Content>
   </Text>
    <AppId><![CDATA[2014070100171523]]></AppId>
    <MsgType><![CDATA[text]]></MsgType>
    <CreateTime><![CDATA[1406104130464]]></CreateTime>
    <FromUserId><![CDATA[20882837462837462837462837461234]]></FromUserId>
    <FromAlipayUserId><![CDATA[2088283746283746]]></FromAlipayUserId>
    <MsgId><![CDATA[140723160000000004]]></MsgId>
    <UserInfo><![CDATA[{"logon_id":"135****1009","user_name":"*iuxu527"}]]>
    </UserInfo>
</XML>

 

参数名 是否必须 参数说明

Text

文本消息内容

AppId

生活号账号ID

MsgType

消息类型,固定为text

CreateTime

消息创建时间

FromUserId

用户OpenId。2016年1月1日起,支付宝用于唯一标识用户的OpenId(32位)由于业务原因计划于2016年9月份废弃,FromAlipayUserId将替代FromUserId作为用户唯一性标示

FromAlipayUserId

用户userid,用户唯一标识

MsgId

消息ID

UserInfo

支付宝的用户信息,JSON格式,包含加星的用户账号及加星的用户名

 

图片消息

消息标识:alipay.mobile.public.message.notify

使用场景举例:接收用户主动发送的图片消息,开发者可以使用异步单发消息功能向用户回复消息,实现诸如查询余额、推送最新优惠消息、客服等业务逻辑。

当开发者网关接收消息成功之后,必须同步回复一条接收成功消息。

支付宝网关发送的POST消息中biz_content的内容示例如下:

<XML>
  <Image>
    <MediaId><![CDATA[L21pZnMvVDF4ZlFBWGpGWFhYYUNucHJYP3Q9YW13ZiZ4c2lnPTFiNTNkODhjZmQ5MDkxNWRjOWJlMmZlMjc1NTBjYzk1452]]></MediaId>
    <Format><![CDATA[jpg]]></Format>
  </Image>
  <AppId><![CDATA[2014070100171523]]></AppId>
  <MsgType><![CDATA[image]]></MsgType>
  <CreateTime><![CDATA[1406104130464]]></CreateTime>
  <FromUserId><![CDATA[20882837462837462837462837461234]]></FromUserId>
  <FromAlipayUserId><![CDATA[2088283746283746]]></FromAlipayUserId>
  <MsgId><![CDATA[140723160000000004]]></MsgId>
  <UserInfo><![CDATA[{"logon_id":"135****1009","user_name":"*iuxu527"}]]></UserInfo>
</XML>

 

参数名 是否必须 参数说明

Image

图片消息内容

MediaId

图片媒体ID,开发者可使用该参数值下载图片

Format

图片文件格式,如jpg

AppId

生活号账号ID

MsgType

消息类型,固定为image

CreateTime

消息创建时间

FromUserId

用户OpenId。2016年1月1日起,支付宝用于唯一标识用户的OpenId(32位)由于业务原因计划于2016年9月份废弃,FromAlipayUserId将替代FromUserId作为用户唯一性标示

FromAlipayUserId

用户userid,用户唯一标识

MsgId

消息ID

UserInfo

支付宝的用户信息,JSON格式,包含加星的用户账号及加星的用户名

 

使用mediaId下载图片

接口网关地址:https://openfile.alipay.com/chat/multimedia.do

接口名称:alipay.mobile.public.multimedia.download

使用场景举例:开发者可通过本接口下载用户聊天发送的图片。

注意:本接口与消息交互体系中的网关地址不同,消息体及调用方式相同。

业务消息内容:

{
    "mediaId": "L21pZnMvVDFucFVGWGZKYlhYYUNucHJYP3Q9YW13ZiZ4c2lnPTEzYWYwZjE1MmU2OTVhZTRlYjRkNGVhYjhlZGU2MzIw052"
}
参数名 参数说明

mediaId

用户聊天发送的图片文件ID

 

代码调用示例(JAVA):

//创建AlipayClient对象,参数分别为请求网关、开发者生活号appid、开发者私钥、参数格式、字符编码(默认GBK)
  AlipayClient alipayClient = new AlipayMobilePublicMultiMediaClient(
    "https://openfile.alipay.com/chat/multimedia.do", AlipayServiceEnvConstants.APP_ID,
    AlipayServiceEnvConstants.PRIVATE_KEY, "json", AlipayServiceEnvConstants.CHARSET);
 
  //构建请求对象
  AlipayMobilePublicMultiMediaDownloadRequest request = new AlipayMobilePublicMultiMediaDownloadRequest();
  //图片输出流
  OutputStream output = null;
  //下载图片mediaid
  String mediaId = "";
  //根目录
  String basePath = "";
  //图片保存地址
  String savePath = basePath + File.separator + mediaId + "." + "jpg";
  File tmpImageFile = new File(savePath);
  try {
   output = new FileOutputStream(tmpImageFile);
   request.setOutputStream(output);
  } catch (Exception e) {
   e.printStackTrace();
  }
 
  //构建业务参数
  JSONObject bizContent = new JSONObject();
  bizContent.put("mediaId", mediaId);
  request.setBizContent(bizContent.toString());
  //构建返回对象
  AlipayMobilePublicMultiMediaDownloadResponse response = null;
  try {
   //调用接口
   response = alipayClient.execute(request);
  } catch (AlipayApiException e) {
   e.printStackTrace();
  } catch (Exception e) {
   e.printStackTrace();
  }

 

同步响应结果

如果调用成功,将返回一个Content-Type为图片格式的HTTP请求,包含了图片的数据流。

onlineServer