小程序模板消息
详细模板消息接入参考指引
alipay.open.app.mini.templatemessage.send
小程序通过openapi给用户触达消息,主要为支付后的触达(通过消费id)和用户提交表单后的触达(通过formId)。
请求地址
环境 | HTTPS请求地址 |
---|---|
正式环境 | https://openapi.alipay.com/gateway.do |
公共请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
app_id | String | 是 | 支付宝分配给开发者的应用ID | 2014072300007148 |
method | String | 是 | 接口名称 | alipay.open.app.mini.templatemessage.send |
format | String | 是 | 仅支持JSON | JSON |
charset | String | 是 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | utf-8 |
sign_type | String | 是 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2 | RSA2 |
sign | String | 是 | 商户请求参数的签名串,详见签名 | 详见示例 |
timestamp | String | 是 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | 2014-07-24 03:07:50 |
version | String | 是 | 调用的接口版本,固定为:1.0 | 1.0 |
app_auth_token | String | 否 | 详见应用授权概述 | |
biz_content | String | 是 | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 |
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
to_user_id | String | 是 | 触达消息的支付宝user_id | 2088102122458832 |
form_id | String | 是 | 用户发生的交易行为的交易号,或者用户在小程序产生表单提交的表单号,用于信息发送的校验 | 2017010100000000580012345678 |
user_template_id | String | 是 | 用户申请的模板id号,固定的模板id会发送固定的消息 | MDI4YzIxMDE2M2I5YTQzYjUxNWE4MjA4NmU1MTIyYmM= |
page | String | 是 | 小程序的跳转页面,用于消息中心用户点击之后详细跳转的小程序页面 | page/component/index |
data | String | 是 | 开发者需要发送模板消息中的自定义部分来替换模板的占位符(注意,占位符必须和申请模板时的关键词一一匹配) | {“keyword1”: {“value” : “12:00”}, “keyword2”: {“value” : “20180808”}, “keyword3”: {“value” : “支付宝”}} |
公共响应参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
code | String | 是 | 网关返回码,当消息发送成功时,返回码为10000 | 40004 |
msg | String | 是 | 网关返回码描述 | Business Failed |
sub_code | String | 否 | 网关明细返回码 | FORM_ID_INVALID |
sub_msg | String | 否 | 网关明细返回码描述 | formId不合法 |
sign | String | 是 | 签名 | 详见示例 |
响应参数
无
代码示例
java版本
AlipayClient alipayClient =newDefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayOpenAppMiniTemplatemessageSendRequest request =new AlipayOpenAppMiniTemplatemessageSendRequest();
request.setBizContent("{"+
"\"to_user_id\":\"2088102122458832\","+
"\"form_id\":\"2017010100000000580012345678\","+
"\"user_template_id\":\"MDI4YzIxMDE2M2I5YTQzYjUxNWE4MjA4NmU1MTIyYmM=\","+
"\"page\":\"page/component/index\","+
"\"data\":\"{\\\"keyword1\\\":{\\\"value\\\":\\\"12:00\\\"},\\\"keyword2\\\":{\\\"value\\\":\\\"20180808\\\"},\\\"keyword3\\\":{\\\"value\\\":\\\"支付宝\\\"}}\""+
"}");
AlipayOpenAppMiniTemplatemessageSendResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
}else{
System.out.println("调用失败");
}
php版本
$aop = new AopClient ();
$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
$aop->appId = 'your app_id';
$aop->rsaPrivateKey = '请填写开发者私钥去头去尾去回车,一行字符串';
$aop->alipayrsaPublicKey='请填写支付宝公钥,一行字符串';
$aop->apiVersion = '1.0';
$aop->signType = 'RSA2';
$aop->postCharset='GBK';
$aop->format='json';
$request = new AlipayOpenAppMiniTemplatemessageSendRequest ();
$request->setBizContent("{" .
"\"to_user_id\":\"2088102122458832\"," .
"\"form_id\":\"2017010100000000580012345678\"," .
"\"user_template_id\":\"MDI4YzIxMDE2M2I5YTQzYjUxNWE4MjA4NmU1MTIyYmM=\"," .
"\"page\":\"page/component/index\"," .
"\"data\":\"{\\\"keyword1\\\":{\\\"value\\\":\\\"12:00\\\"},\\\"keyword2\\\":{\\\"value\\\":\\\"20180808\\\"},\\\"keyword3\\\":{\\\"value\\\":\\\"支付宝\\\"}}\"" .
"}");
$result = $aop->execute ( $request);
$responseNode = str_replace(".", "_", $request->getApiMethodName()) . "_response";
$resultCode = $result->$responseNode->code;
if(!empty($resultCode)&&$resultCode == 10000){
echo "成功";
} else {
echo "失败";
}
.net版本
IAopClient client = new DefaultAopClient("https://openapi.alipay.com/gateway.do", "app_id", "merchant_private_key", "json", "1.0", "RSA2", "alipay_public_key", "GBK", false);
AlipayOpenAppMiniTemplatemessageSendRequest request= new AlipayOpenAppMiniTemplatemessageSendRequest() ;
request.BizContent="{" +
"\"to_user_id\":\"2088102122458832\"," +
"\"form_id\":\"2017010100000000580012345678\"," +
"\"user_template_id\":\"MDI4YzIxMDE2M2I5YTQzYjUxNWE4MjA4NmU1MTIyYmM=\"," +
"\"page\":\"page/component/index\"," +
"\"data\":\"{\\\"keyword1\\\":{\\\"value\\\":\\\"12:00\\\"},\\\"keyword2\\\":{\\\"value\\\":\\\"20180808\\\"},\\\"keyword3\\\":{\\\"value\\\":\\\"支付宝\\\"}}\"" +
"}";
AlipayOpenAppMiniTemplatemessageSendResponse response=client.execute(request);
Console.WriteLine(response.Body);
响应示例
{
"alipay_open_app_mini_templatemessage_send_response":{
"code":"10000",
"msg":"Success"
}
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
异常示例
json示例
{
"alipay_open_app_mini_templatemessage_send_response":{
"code":"10000",
"msg":"Success"
}
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
业务错误码
错误码 | 错误描述 | 解决方案 |
FORM_ID_SEND_LIMIT | formId已经到达发送限制,请换formId进行发送 | 每个formId或者tradeNo的最大发送消息的次数是3次 |
TEMPLATE_ILLEGAL | 模板库不合法,该模板库已经被禁止或者模板不存在 | 重新申请新的模板进行发送消息 |
MESSAGE_TEMPLATE_KEYWORD_ILLEGAL | 模板关键词不合法 | 模板关键词已被删除,需要申请新的模板进行发送 |
USER_TEMPLATE_ILLEGAL | 用户模板非法 | 确认应用是否存在,如果用户模板存在(未被删除),则稍后重试 |
FORM_ID_INVALID | formId不合法 | 1、请确认formId的合法性,如果确认是formId是真实合法的(formId的来源可以有两个,一个是通过小程序form表单页获得,另一种是用户发生付款的交易号),请稍后再次发起请求。(注意,支付类的模板消息只允许只用tradeNo进行发送,表单类的模板消息只允许使用表单组件生成的formId进行发送) 2、formId需要和被触达的用户匹配,如果formId是通过小程序表单生成的,则只允许发送给触发表单的用户,如果formId是交易号,则只允许发送给付款人员。 |
FORM_ID_NOT_MATCH_APPID | formId和appId不匹配 | formId如果是点击表单产生的,则只允许提供当前表单的小程序允许使用该formId发送,如果是tradeNo,则允许第一次使用这个tradeNo的小程序使用 |
FORM_ID_OVER_TIME | formId超时 | 一个formId的发送有效期为七天,如果是用户提交表单的formId,则以用户提交表单的时间开始计算;如果是tradeNo则以发生付款的时间开始计算。 |
USER_KEYWORD_LENGTH_ERROR | 关键词超长 | 每个关键词的value值长度不得大于60个字符,请修改keyword.value的入参 |
PAGE_OVER_LIMIT | page参数超长 | openapi里面的page参数最多为128字节 |
TRADE_NO_NOT_MATCH_USERID | tradeNo只能发送给实际付款人 | tradeNo只能发送给实际付款人 |
QUERY_CONSUMER_REQEUST_ERROR | 查询消费记录入参错误 | 当模板类型是交易类时,如果userId的格式错误,或者tradeNo的格式错误(这里一定要用支付宝的订单号),会返回该错误码 |