• 下载
  • 社区

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"
}

异常示例

{
    "alipay_open_app_mini_templatemessage_send_response":{
        "code":"40004",
        "msg":"Business Failed",
        "sub_code":"USER_TEMPLATE_ILLEGAL",
        "sub_msg":"模板非法"
    },
    "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

业务错误码

错误码 错误描述 解决方案
FORM_ID_SEND_LIMIT formId已经到达发送限制,请换formId进行发送 每个formId或者tradeNo对于发送是有次数限制的(3次),该异常代表formId已经到达发送上限,无法再进行发送
TEMPLATE_ILLEGAL 模板不合法,该模板已经被禁止或者模板不存在 重新申请新的模板进行发送消息
MESSAGE_TEMPLATE_KEYWORD_ILLEGAL 系统模板关键词不合法 系统模板关键词已被删除,需要申请新的模板进行发送
USER_TEMPLATE_ILLEGAL 模板非法 确认templateId 是否和申请的模板Id匹配;同时需要确认该模板是否已经被删除
USER_TEMPLATE_LACK_KEYWORD 缺少关键词 申请的模板关键词必须和上送的关键词匹配,例如在申请模板中选择了5个关键词,则data数据域必须有keyword1~keyword5的对象和value
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的格式错误(这里一定要用支付宝的订单号),会返回该错误码
BIZ_CONTENT_FORMAT_ERROR 参数错误 请检查入参格式,或使用alipaysdk组装入参
DATA_CONTENT_FORMAT_ERROR 参数错误 data参数不是json格式
DATA_SENSITIVE 发送的数据存在敏感词 请调整发送数据
USER_ID_INVALID 输入的user_id不合法 检查输入的user_id
NO_BIND_PUBLIC_APP 无绑定的生活号 在小程序详情页的生活号管理中绑定生活号
MESSAGE_SEND_AUTH_ERROR 用户未关注公众号或未授权该小程序 请确认推送的该用户已经授权您的小程序,或者该用户已经关注您小程序绑定的生活号
USER_TEMPLATE_STATUS_ILLEGAL 用户模版状态错误 请确认您的用户模版是否已经生效
APP_TYPE_ERROR 应用类型错误 请确认应用id为小程序应用id