为了改善小米终端用户的通知体验，营造良好可持续的推送生态，小米推送对现有消息下发能力进行了升级，新增模板下发能力。

一、模板功能简介

小米推送规定所有私信消息需接入模板，接入模板的消息具备如下特点：

• 所有私信channel需携带channel_id和模板id下发；
• 下发时仅传送消息变量{$keywords$}至MiPush侧进行消息拼装。

二、模板接入指南

1. 启用小米推送服务，请参考《推送服务启用指南》

2. MiPush私信消息模板申请及接入方法

2.1 官方模板
使用开发者账号登录小米推送运营平台，选择您的应用，进入“应用信息”管理界面。在左侧导航栏中找到“消息分类管理”，点击展开后选择“模板管理-官方模板”，无需申请，即可使用相应模板id进行下发。
注：官方模板由MiPush实时更新维护。

2.2 自定义模板申请流程

若上述官方模板无法满足您的需求，可以申请自定义模板：
在左侧导航栏中找到“消息分类管理”，点击展开后选择“模板管理-自定义模板”。在模板管理页面右上角，点击“新建模板”按钮开始创建自定义模板。

在“新建模板”页面，完成信息填写并提交审核。

• 基础配置：
  
• 所属消息分类：请选择模板所属消息分类，如订单及物流；
• 模板名称：请根据通知场景简要命名，避免数字、特殊符号等难以理解的名称；
• 模板描述：对模板用途、适用场景或内容特点的补充说明字段。若模板名称已清晰表达含义，可选择不填写；如需填写，建议简洁准确，突出核心特征和适用场景。

• 模板内容配置：
  
• 标题结构配置：用于定义消息标题的展示格式，支持固定文本与变量组合，需确保结构清晰、语意完整。
• 内容结构配置（副标题）：用于定义消息正文的展示格式，支持固定文本与变量组合，需注意逻辑完整性和可读性。
• 变量内容示例：展示模板中各变量的具体填充效果，需为每个变量提供真实合理的示例内容，体现模板实际应用场景。
• 注意：
• 主标题&副标题的变量需要按照 {$变量名$}的格式，需通过点击「插入变量」功能生成规范变量符号；
• 主标题首位不可以变量开头；
• 变量名不能重复；
• 每个模板最多支持9个变量。

提交申请后，您可以在“模板管理”页面查看已提交的模板信息，包括模板id、模板名称、消息分类、适用通知类别、标题结构、内容结构、状态等信息。

3.服务端接入

1、服务端API

基于现有MiPush服务端API进行消息推送（服务器API地址以及参数 | 小米澎湃OS开发者平台），依托扩展extra参数的方式完成消息模板接入适配。

• 扩展extra参数说明

• 发送方式：支持使用Michannel推送单条消息或推送多条消息
  
• 推送单条消息

• 推送多条消息

示例：

curl --location 'https://api.xmpush.xiaomi.com/v3/message/regid' \
--header 'Authorization: key=xxxxxxxxxxxxxxx' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'restricted_package_name=com.xiaomi.mipushdemo' \
--data-urlencode 'title={$app_name$}订单支付成功' \
--data-urlencode 'description=尊敬的用户，您的订单{$order_no$}已支付成功，金额：{$order_amount$}元，预计{$delivery_time$}送达。' \
--data-urlencode 'registration_id=hZ6jiFfetuOt6vjK8ZTS1dEauxbDek2A76GqsZJapEUlsFpIDln+5WYP2v929Ltj' \
--data-urlencode 'extra.intent_uri=intent:#Intent;component=com.xiaomi.mipushdemo/com.xiaomi.mipushdemo.TestActivity;end' \
--data-urlencode 'extra.callback=http://10.192.33.174:8080/callback/test' \
--data-urlencode 'extra.callback.type=129' \
--data-urlencode 'extra.channel_id=130' \
--data-urlencode 'extra.template_id=1001' \
--data-urlencode 'extra.template_param={"app_name":"小米商城","order_no":"XM202601130001","order_amount":"11.00","delivery_time":"2026-01-15 18:00"}'

2、服务端SDK

基于现有MiPUSH服务端SDK进行消息推送（服务端Java SDK文档 | 小米澎湃OS开发者平台），依托扩展extra(String key, String value) 的方式完成消息模板接入适配。

• 扩展extra参数key说明

• 发送方式支持范围：

示例：

public void testTemplateMessage() throws Exception {
    Map<String, String> extra = new HashMap<>();
    extra.put("channel_id", "113635");
    extra.put("template_id", "1001");
    extra.put("template_param", "{\"keywords1\":\"1111\",\"keywords2\":\"参数2\"}");

    Message message = new Message.Builder()
            .title("你有一条新消息")
            .description("尊敬的用户，您的订单{$keywords1$}已支付成功，金额：{$keywords2$}元")
            .restrictedPackageName("APP_PACKAGE_NAME")
            .extra(extra)
            .build();
        Constants.useOfficial();
        Sender sender = new Sender(APP_SECRECT);
        Result result = sender.send(message, REGID, 3); //根据regID，发送消息到指定设备上
        System.out.println("Server response: "+"MessageId: " + result.getMessageId()
                + " ErrorCode: " + result.getErrorCode().getValue()
                + " Reason: " + result.getReason());

}

3、服务端错误码参考

以下为消息模板接入错误码说明，其余请参考服务端错误码参考 | 小米澎湃OS开发者平台

示例-错误响应报文：

{
    "result": "error",
    "reason": "Template parameter value must be String type",
    "trace_id": "Xxo00803769689306678rp",
    "code": 10041,
    "data": {
        "day_acked": "180",
        "day_quota": "10000"
    },
    "description": "title或者description不合规范"
}