小程序模板消息

详细模板消息接入参考指引

alipay.open.app.mini.templatemessage.send

小程序通过openapi给用户触达消息,主要为支付后的触达(通过消费id)和用户提交表单后的触达(通过formId)。

请求地址

环境HTTPS请求地址
正式环境https://openapi.alipay.com/gateway.do

公共请求参数

名称类型必填描述示例值
app_idString支付宝分配给开发者的应用ID2014072300007148
methodString接口名称alipay.open.app.mini.templatemessage.send
formatString仅支持JSONJSON
charsetString请求使用的编码格式,如utf-8,gbk,gb2312等utf-8
sign_typeString商户生成签名字符串所使用的签名算法类型,目前支持RSA2RSA2
signString商户请求参数的签名串,详见签名详见示例
timestampString发送请求的时间,格式"yyyy-MM-dd HH:mm:ss"2014-07-24 03:07:50
versionString调用的接口版本,固定为:1.01.0
app_auth_tokenString详见应用授权概述
biz_contentString请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

名称类型必填描述示例值
to_user_idString触达消息的支付宝user_id2088102122458832
form_idString用户发生的交易行为的交易号,或者用户在小程序产生表单提交的表单号,用于信息发送的校验2017010100000000580012345678
user_template_idString用户申请的模板id号,固定的模板id会发送固定的消息MDI4YzIxMDE2M2I5YTQzYjUxNWE4MjA4NmU1MTIyYmM=
pageString小程序的跳转页面,用于消息中心用户点击之后详细跳转的小程序页面page/component/index
dataString开发者需要发送模板消息中的自定义部分来替换模板的占位符(注意,占位符必须和申请模板时的关键词一一匹配){“keyword1”: {“value” : “12:00”}, “keyword2”: {“value” : “20180808”}, “keyword3”: {“value” : “支付宝”}}

公共响应参数

名称类型必填描述示例值
codeString网关返回码,当消息发送成功时,返回码为1000040004
msgString网关返回码描述Business Failed
sub_codeString网关明细返回码FORM_ID_INVALID
sub_msgString网关明细返回码描述formId不合法
signString签名详见示例

响应参数

代码示例

java版本

  1. AlipayClient alipayClient =newDefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
  2. AlipayOpenAppMiniTemplatemessageSendRequest request =new AlipayOpenAppMiniTemplatemessageSendRequest();
  3. request.setBizContent("{"+
  4. "\"to_user_id\":\"2088102122458832\","+
  5. "\"form_id\":\"2017010100000000580012345678\","+
  6. "\"user_template_id\":\"MDI4YzIxMDE2M2I5YTQzYjUxNWE4MjA4NmU1MTIyYmM=\","+
  7. "\"page\":\"page/component/index\","+
  8. "\"data\":\"{\\\"keyword1\\\":{\\\"value\\\":\\\"12:00\\\"},\\\"keyword2\\\":{\\\"value\\\":\\\"20180808\\\"},\\\"keyword3\\\":{\\\"value\\\":\\\"支付宝\\\"}}\""+
  9. "}");
  10. AlipayOpenAppMiniTemplatemessageSendResponse response = alipayClient.execute(request);
  11. if(response.isSuccess()){
  12. System.out.println("调用成功");
  13. }else{
  14. System.out.println("调用失败");
  15. }

php版本

  1. $aop = new AopClient ();
  2. $aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
  3. $aop->appId = 'your app_id';
  4. $aop->rsaPrivateKey = '请填写开发者私钥去头去尾去回车,一行字符串';
  5. $aop->alipayrsaPublicKey='请填写支付宝公钥,一行字符串';
  6. $aop->apiVersion = '1.0';
  7. $aop->signType = 'RSA2';
  8. $aop->postCharset='GBK';
  9. $aop->format='json';
  10. $request = new AlipayOpenAppMiniTemplatemessageSendRequest ();
  11. $request->setBizContent("{" .
  12. "\"to_user_id\":\"2088102122458832\"," .
  13. "\"form_id\":\"2017010100000000580012345678\"," .
  14. "\"user_template_id\":\"MDI4YzIxMDE2M2I5YTQzYjUxNWE4MjA4NmU1MTIyYmM=\"," .
  15. "\"page\":\"page/component/index\"," .
  16. "\"data\":\"{\\\"keyword1\\\":{\\\"value\\\":\\\"12:00\\\"},\\\"keyword2\\\":{\\\"value\\\":\\\"20180808\\\"},\\\"keyword3\\\":{\\\"value\\\":\\\"支付宝\\\"}}\"" .
  17. "}");
  18. $result = $aop->execute ( $request);
  19. $responseNode = str_replace(".", "_", $request->getApiMethodName()) . "_response";
  20. $resultCode = $result->$responseNode->code;
  21. if(!empty($resultCode)&&$resultCode == 10000){
  22. echo "成功";
  23. } else {
  24. echo "失败";
  25. }

.net版本

  1. IAopClient client = new DefaultAopClient("https://openapi.alipay.com/gateway.do", "app_id", "merchant_private_key", "json", "1.0", "RSA2", "alipay_public_key", "GBK", false);
  2. AlipayOpenAppMiniTemplatemessageSendRequest request= new AlipayOpenAppMiniTemplatemessageSendRequest() ;
  3. request.BizContent="{" +
  4. "\"to_user_id\":\"2088102122458832\"," +
  5. "\"form_id\":\"2017010100000000580012345678\"," +
  6. "\"user_template_id\":\"MDI4YzIxMDE2M2I5YTQzYjUxNWE4MjA4NmU1MTIyYmM=\"," +
  7. "\"page\":\"page/component/index\"," +
  8. "\"data\":\"{\\\"keyword1\\\":{\\\"value\\\":\\\"12:00\\\"},\\\"keyword2\\\":{\\\"value\\\":\\\"20180808\\\"},\\\"keyword3\\\":{\\\"value\\\":\\\"支付宝\\\"}}\"" +
  9. "}";
  10. AlipayOpenAppMiniTemplatemessageSendResponse response=client.execute(request);
  11. Console.WriteLine(response.Body);

响应示例

  1. {
  2. "alipay_open_app_mini_templatemessage_send_response":{
  3. "code":"10000",
  4. "msg":"Success"
  5. }
  6. ,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
  7. }

异常示例

json示例

  1. {
  2. "alipay_open_app_mini_templatemessage_send_response":{
  3. "code":"10000",
  4. "msg":"Success"
  5. }
  6. ,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
  7. }

业务错误码


错误码

错误描述

解决方案

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的格式错误(这里一定要用支付宝的订单号),会返回该错误码

原文: https://docs.alipay.com/mini/api/templatemessage