如果开发者期望开发其它平台的ServerSDK，下面提供的API地址和参数也许会有帮助。

一、推送单条消息

正式环境

V2版接口：

向某个regid或一组regid列表推送某条消息
https://api.xmpush.xiaomi.com/v2/message/regid

向某个alias或一组alias列表推送某条消息
https://api.xmpush.xiaomi.com/v2/message/alias

向某个account或一组account列表推送某条消息
https://api.xmpush.xiaomi.com/v2/message/user_account

向某个topic推送某条消息
https://api.xmpush.xiaomi.com/v2/message/topic

向多个topic推送单条消息
https://api.xmpush.xiaomi.com/v2/message/multi_topic

向所有设备推送某条消息
https://api.xmpush.xiaomi.com/v2/message/all

V3版接口（兼容V2版接口并支持多包名）：

向某个regid或一组regid列表推送某条消息（这些regId可以属于不同的包名）
https://api.xmpush.xiaomi.com/v3/message/regid

向某个alias或一组alias列表推送某条消息（这些alias可以属于不同的包名）
https://api.xmpush.xiaomi.com/v3/message/alias

向某个topic推送某条消息（可以指定一个或多个包名）
https://api.xmpush.xiaomi.com/v3/message/topic

向多个topic推送单条消息（可以指定一个或多个包名）
https://api.xmpush.xiaomi.com/v3/message/multi_topic

向所有设备推送某条消息（可以指定一个或多个包名）
https://api.xmpush.xiaomi.com/v3/message/all

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

表 1-1. Android POST参数说明

1. 服务器端还可以定义一些以"extra."开头的POST参数，POST参数形式如：extra.key=value。参数附加说明：

注：至多可以设置10个key-value键值对。

2. 利用v2/message/all可以向所有设备发送消息。参数跟向topic发送消息类似，不需要额外提供topic域。

3. 参数规范与Message类和Sender类中的描述相同。alias，topic，registration_id三者不能同时出现，alias可以有多个，表示向这些alias指定的设备发送消息。返回的是json格式的字符串，包括以下几个字段。

• "result": string，"ok" 表示成功, 
• "error" 表示失败。
• "description": string， 对发送消息失败原因的解释。
• "data": string，本身就是一个json字符串（其中id字段的值就是消息的Id）。
• "code": integer，0表示成功，非0表示失败。
• "info": string，详细信息。

例如：

{"result":"ok","description":"成功","data":{"id":"1000999_1375164696370"},"code":0,"info":"Received push messages for 1 regid"}  

或

 {"result":"error","reason":"payload参数不能为空","description":"缺失必选参数","code":10016}

Demo

1. 向”alias1”，“alias2”，“alias3” 三个别名指定的设备发送消息。

Request URL: https://api.xmpush.xiaomi.com/v2/message/alias Request
Method: POST
Form Data: alias=alias1,alias2,alias3&description=notification_description&payload=this+is+xiaomi+push&restricted_package_name=com.xiaomi.mipushdemo&title=notification_title¬ify_type=2&time_to_live=1000&extra.sound_uri=android.resource://com.xiaomi.mipushdemo/raw/shaking

2. 向registration_id为123指定的设备发送消息。

Request URL: https://api.xmpush.xiaomi.com/v2/message/regid Request
Method: POST
Form Data: description=notification_description&payload=this+is+xiaomi+push&restricted_package_name=com.xiaomi.mipushdemo®istration_id=123&title=notification_title¬ify_type=2&time_to_live=1000¬ify_id=0

3. 向订阅了my_topic的所有设备发送消息。

Request URL: https://api.xmpush.xiaomi.com/v2/message/topic Request
Method: POST
Form Data: description=notification_description&payload=this+is+xiaomi+push&restricted_package_name=com.xiaomi.mipushdemo&topic=my_topic&title=notification_title¬ify_type=2&time_to_live=1000

4. 自定义点击行为：打开app的Launcher Activity

Request URL: https://api.xmpush.xiaomi.com/v2/message/alias Request
Method: POST
Form Data: alias=test_alias1&description=notification_description&payload=this+is+xiaomi+push&restricted_package_name=com.xiaomi.mipushdemo&title=notification_title¬ify_type=2&time_to_live=1000&extra.notify_effect=1

5. 自定义点击行为：打开app的任一组件

Request URL: https://api.xmpush.xiaomi.com/v2/message/alias Request
Method: POST
Form Data: alias=test_alias1&description=notification_description&payload=this+is+xiaomi+push&restricted_package_name=com.xiaomi.mipushdemo&title=notification_title¬ify_type=2&time_to_live=1000&extra.notify_effect=2&extra.intent_uri=intent:#Intent;action=com.a.b.shot;end

6. 自定义点击行为：打开网页

Request URL: https://api.xmpush.xiaomi.com/v2/message/alias Request
Method: POST
Form Data: alias=test_alias1&description=notification_description&restricted_package_name=com.xiaomi.mipushdemo&title=notification_title¬ify_type=2&time_to_live=1000&extra.notify_effect=3&extra.web_uri=http://www.xiaomi.com

7. 向订阅了[A,B,C,D]集合中任一标签的设备发送消息。

Request URL: https://api.xmpush.xiaomi.com/v2/message/multi_topic Request
Method: POST
Form Data: description=notification_description&payload=this+is+xiaomi+push&restricted_package_name=com.xiaomi.mipushdemo&topics=A;$;B;$;C;$;D&topic_op=UNION&title=notification_title¬ify_type=2&time_to_live=1000

二、推送多条消息

正式环境

针对不同的regid推送不同的消息
https://api.xmpush.xiaomi.com/v2/multi_messages/regids

针对不同的alias推送不同的消息
https://api.xmpush.xiaomi.com/v2/multi_messages/aliases

针对不同的userAccount推送不同的消息
https://api.xmpush.xiaomi.com/v2/multi_messages/user_accounts

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

表 2-1. Android POST参数说明

返回的是json格式的字符串，包括以下几个字段。

• "result": string，"ok" 表示成功, "error" 表示失败。
• "description": string， 对发送消息失败原因的解释。
• "data": string，本身就是一个json字符串（其中id字段的值就是消息的Id）。
• "code": integer，0表示成功，非0表示失败。
• "info": string，详细信息。

Demo

注意：为了将json数据的格式看得比较清晰，我们没有做urlencode处理。但是，实际开发中必须对json数据做urlencode处理。

1. 向不同的regid发送不同的消息

https://api.xmpush.xiaomi.com/v2/multi_messages/regids ?messages=[{"target":"regid1","message": {"payload":"send message to regid1","restricted_package_name":"com.xiaomi.mipushdemo", "notify_type":1,"description":"description1","title":"title1","time_to_live":100000， "extra":{"sound_uri":"android.resource://com.xiaomi.mipushdemo/raw/shaking"}}}, {"target":"regid2","message": {"payload":"send message to regid2","restricted_package_name":"com.xiaomi.mipushdemo", "notify_type":2,"description":"description2","title":"title2","time_to_live":20000}}]

2. 向不同的alias发送不同的消息

https://api.xmpush.xiaomi.com/v2/multi_messages/aliases ?messages=[{"target":"alias1","message": {"payload":"send message to alias1","restricted_package_name":"com.xiaomi.mipushdemo", "notify_type":1,"description":"description1","title":"title1","time_to_live":100000}}, {"target":"alias2","message": {"payload":"send message to alias2","restricted_package_name":"com.xiaomi.mipushdemo", "notify_type":2,"description":"description2","title":"title2","time_to_live":20000}}]

三、获取消息的统计数据

请使用trace接口获取消息的统计数据，具体参见“6 追踪消息状态”一节。（https://api.xmpush.xiaomi.com/v1/stats/message/counters 该接口目前已废弃。）

四、追踪消息状态

获取某条消息或某个时间段的消息统计数据

追踪消息https://api.xmpush.xiaomi.com/v1/trace/message/status

追踪某个时间区域内的消息https://api.xmpush.xiaomi.com/v1/trace/messages/status

HTTP请求方法：GET

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

表 4-1. 追踪消息的GET参数说明

Demo：

{"result":"ok", 
"description":"成功",
 "data":{ 
        "data":" {\"id\":\"s1005246409317636237jB\",\"delivery_rate\":\"100%\",\"delivered\":1,\"resolved\":1, \"msg_type\":\"BatchRegId\",\"create_time\":\"2014-08-29 21:07:16\",\"time_to_live\":\"1209600s\", \"click\":0,\"click_rate\":\"0%\"}"}, 
"code":0}

表 4-2. 追踪某个时间区域内消息的GET参数说明

Demo：

{"result":"ok", 
"description":"成功", 
"data":{ 
      "data":"[ {\"id\":\"a1000270409820283940fp\",\"delivery_rate\":\"100%\",\"delivered\":2,\"resolved\":2, \"msg_type\":\"BatchAlias\",\"create_time\":\"2014-09-04 16:44:43\",\"time_to_live\":\"109s\", \"create_timestamp\":1409820283941,\"click\":0,\"click_rate\":\"0%\"}, 
               {\"id\":\"s1000270409820247716NA\",\"delivery_rate\":\"100%\",\"delivered\":2,\"resolved\":2, \"msg_type\":\"BatchRegId\",\"create_time\":\"2014-09-04 16:44:07\",\"time_to_live\":\"109s\", \"create_timestamp\":1409820247717,\"click\":0,\"click_rate\":\"0%\"}, 
               {\"id\":\"a1000270409820207789dJ\",\"delivery_rate\":\"0%\",\"delivered\":0,\"resolved\":1, \"msg_type\":\"Alias\",\"create_time\":\"2014-09-04 16:43:27\",\"time_to_live\":\"1209600s\", \"create_timestamp\":1409820207789,\"click\":0,\"click_rate\":\"0%\"}, 
               {\"id\":\"t1000270409820155849Ek\",\"delivery_rate\":\"100%\",\"delivered\":2,\"resolved\":2, \"msg_type\":\"Topic\",\"create_time\":\"2014-09-04 16:42:35\",\"time_to_live\":\"109s\", \"create_timestamp\":1409820155849,\"click\":0,\"click_rate\":\"0%\"}, 
               {\"id\":\"s10002704098201310026i\",\"delivery_rate\":\"0%\",\"delivered\":0,\"resolved\":1, \"msg_type\":\"Common\",\"create_time\":\"2014-09-04 16:42:11\",\"time_to_live\":\"1209600s\", \"create_timestamp\":1409820131002,\"click\":0,\"click_rate\":\"0%\"}]"}, 
"code":0}

其中，

• id表示单条消息的id。
• resolved表示消息的计划送达数。
• raw_counter表示https原始请求目标数。
• invalid_target表示无效目标数（alias无效,、user_account无效等)。
• app_not_register表示app未注册push服务数量。
• device_condition_unmatch表示设备所处的环境不符合消息设置的条件（例如：网络环境不匹配, 地域不匹配, app版本不匹配, 机型不匹配等）。
• msg_send表示消息的实际下发数。
• delivered表示消息的送达数。
• delivery_rate表示送达率（送达数/有效设备数）。
• bar_closed表示屏蔽通知栏数。
• msg_display表示消息的展示数（送达数-屏蔽通知栏数）。
• click表示消息的点击数。
• click_rate表示消息的点击率（点击数/送达数）。
• create_time表示消息的发送时间。
• time_to_live表示消息的有效期。
• msg_type表示该消息发送的方式（msg_type分为Common、BatchRegId、Alias、BatchAlias、Topic）。

获取批量消息统计数据

批量消息统计数据接口支持根据多个消息ID或jobkey（不超过100）批量查询对应的消息统计。

https://api.xmpush.xiaomi.com/v1/trace/multi_message/status

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

表 4-3. 请求参数说明

响应示例：

{ 
    "result": "ok", 
    "trace_id": "Xdm04456572507794174Qy", 
    "code": 0, 
    "data": { 
        "data": { 
            "op335013": { 
                "create_time": "2019-10-18 17:51:04", 
                "invalid_target": 0, 
                "msg_send": 2, 
                "raw_counter": 2, 
                "click_rate": "50%", 
                "delivered": 2, 
                "click": 1, 
                "bar_closed": 0, 
                "device_condition_unmatch": 0, 
                "create_timestamp": 1571392264044, 
                "time_to_live": "1145336s", 
                "msg_type": "Alias", 
                "delivery_rate": "100%", 
                "id": "acm5550657139226404450", 
                "resolved": 2, 
                "app_not_register": 0, 
                "msg_display": 2 
            }, 
            "op335012": { 
                "create_time": "2019-10-18 17:51:03", 
                "invalid_target": 1, 
                "msg_send": 0, 
                "raw_counter": 1, 
                "click_rate": "0%", 
                "delivered": 0, 
                "click": 0, 
                "bar_closed": 0, 
                "device_condition_unmatch": 0, 
                "create_timestamp": 1571392263756, 
                "time_to_live": "1145337s", 
                "msg_type": "Alias", 
                "delivery_rate": "0%", 
                "id": "acm53814571392263756Lv", 
                "resolved": 0, 
                "app_not_register": 0, 
                "msg_display": 0 
            } 
        } 
    }, 
    "description": "成功" 
}

五、订阅/取消订阅标签

正式环境

订阅RegId的标签https://api.xmpush.xiaomi.com/v2/topic/subscribe

取消订阅RegId的标签https://api.xmpush.xiaomi.com/v2/topic/unsubscribe

订阅alias的标签https://api.xmpush.xiaomi.com/v2/topic/subscribe/alias

取消订阅alias的标签https://api.xmpush.xiaomi.com/v2/topic/unsubscribe/alias

取消某个标签的所有订阅https://api.xmpush.xiaomi.com/v2/topic/unsubscribe/all

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

针对/v2/topic/subscribe和/v2/topic/unsubscribe的参数说明：

表 5-1. 订阅/取消订阅RegId的标签的参数说明

Demo：

https://api.xmpush.xiaomi.com/v2/topic/subscribe ?registration_id=abc &topic=tt

针对/v2/topic/subscribe/alias和/v2/topic/unsubscribe/alias的参数说明：

表 5-2. 订阅/取消订阅alias的标签的参数说明

Demo：

https://api.xmpush.xiaomi.com/v2/topic/subscribe/alias ?aliases=a1 &topic=tt

针对/v2/topic/unsubscribe/all的参数说明：

表 5-3. 取消某个标签的所有订阅的参数说明

Demo：

https://api.xmpush.xiaomi.com/v2/topic/unsubscribe/all ?topic=tt

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

六、获取失效的regId列表

feedback接口已下线，请使用消息回执callback代替，设置extra.callback.type=16可获取无效的目标设备列表。

七、获取一个应用的某个用户目前设置的所有Alias

正式环境

API地址：https://api.xmpush.xiaomi.com/v1/alias/all

HTTP请求方法：GET

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注：字符key必须小写。例如：Authorization: key=YOUR_APP_SECRET

表 7-1. 获取所有Alias的GET

返回的是json格式的字符串。

如果成功，则返回的字符串格式如下。

​{"result":"ok","code":0,"data":{"list":["XXXXXX","XXXXXX",...,"XXXXXX"]},"description":"成功"} 

如果失败，则返回的字符串格式如下。

{"result":"error","reason":"XXXXXXXXX","description":"XXXX","code":XXXX}

八、获取一个应用的某个用户目前订阅的所有Topic

正式环境

API地址：https://api.xmpush.xiaomi.com/v1/topic/all

HTTP请求方法：GET

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注：字符key必须小写。例如：Authorization: key=YOUR_APP_SECRET

表 8-1. 获取所有Topic的GET参数说明

返回的是json格式的字符串。

如果成功，则返回的字符串格式如下。

​{"result":"ok","code":0,"data":{"list":["XXXXXX","XXXXXX",...,"XXXXXX"]},"description":"成功"}

如果失败，则返回的字符串格式如下。

{"result":"error","reason":"XXXXXXXXX","description":"XXXX","code":XXXX}

九、获取一个userAccount对应的所有有效regId

正式环境

API地址：https://api.xmpush.xiaomi.com/v1/useraccount/get_regids_by_useraccount

HTTP请求方法：GET

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注：字符key必须小写。例如：Authorization: key=YOUR_APP_SECRET

表 9-1.  GET参数说明

返回的是json格式的字符串。

如果成功，则返回的字符串格式如下。

​{"result":"ok","code":0,"data":{"list":["XXXXXX","XXXXXX",...,"XXXXXX"]},"description":"成功"}

如果失败，则返回的字符串格式如下。

{"result":"error","reason":"XXXXXXXXX","description":"XXXX","code":XXXX}

十、检测/删除定时任务

正式环境

检测定时任务是否存在https://api.xmpush.xiaomi.com/v2/schedule_job/exist

删除定时任务https://api.xmpush.xiaomi.com/v2/schedule_job/delete

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注：字符key必须小写。例如：Authorization: key=YOUR_APP_SECRET

表 10-1. 参数列表

返回的是json格式的字符串。

• code是0表示成功；否则表示失败。
• reason表示失败的原因。

十一、通知类别（Channel）

通知类别（Channel）介绍

通知类别（Channel）是 Android O 引入的新功能，旨在解决以下问题：

• 应用的通知越来越多，给用户造成明显打扰。
• 但用户只能全局屏蔽这个应用的全部通知，不能屏蔽部分，然后留下对自己有用的。

为了解决这个问题，Android 支持开发者给自己的通知分成若干类，然后允许用户单独屏蔽这个类别的通知。关于通知类别（Channel）的详细介绍请参见《MIUI 10 通知类别 (Channel) 适配》。

说明：当前版本暂不支持设置Channel Group。

使用方法

注意：用户最多可创建8组Channel。各Channel的Channel_id不可重复，Channel_name也不允许同名。Channel一旦创建并发送了带有Channel的消息，设备上即会生成这个Channel，不能删除也不能修改，所以请谨慎创建Channel。

• 添加新Channel

参考《小米推送消息分类新规》2.channel申请与接入方法。

• 发送带有Channel的消息：

参数说明：

十二、消息终止

一些时候运营人员可能会出现误发消息的情况，这时可以通过“消息终止”功能立即停止消息下发，以便及时截断消息发送、防止影响面扩大。

根据消息ID停止消息

API地址：https://api.xmpush.xiaomi.com/v1/message/switch/stop_by_id

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

POST参数说明：

响应示例：

{
    "result": "ok",
    "trace_id": "Xdm01712568685156246Gj",
    "code": 0,
    "description": "成功"
}

根据消息jobkey停止消息

API地址：https://api.xmpush.xiaomi.com/v1/message/switch/stop_by_jobkey

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

POST参数说明：

响应示例：

{
    "result": "ok",
    "trace_id": "Xdm01712568685156246Gj",
    "code": 0,
    "description": "成功"
}

十三、消息撤回

根据设备alias撤回消息

API地址：https://api.xmpush.xiaomi.com/v1/message/alias/revoke

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

POST参数说明：

响应示例：

{
    "result": "ok",
    "trace_id": "Xdm01712568685156246Gj",
    "code": 0,
    "description": "成功"
}

根据设备regId撤回消息

API地址：https://api.xmpush.xiaomi.com/v1/message/regid/revoke

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

POST参数说明：

响应示例：

{
    "result": "ok",
    "trace_id": "Xdm01712568685156246Gj",
    "code": 0,
    "description": "成功"
}

根据设备userAccount撤回消息

API地址：https://api.xmpush.xiaomi.com/v1/message/user_account/revoke

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

POST参数说明：

响应示例：

{
    "result": "ok",
    "trace_id": "Xdm01712568685156246Gj",
    "code": 0,
    "description": "成功"
}

根据消息id和jobkey撤回消息

API地址：https://api.xmpush.xiaomi.com/v2/message/revoke

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

POST参数说明：

响应示例：

{
    "result": "ok",
    "code": 0,
    "description": "成功"
}

撤回topic消息

API地址：https://api.xmpush.xiaomi.com/v1/message/topic/revoke

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

POST参数说明：

响应示例：

{
    "result": "ok",
    "trace_id": "Xdm01712568685156246Gj",
    "code": 0,
    "description": "成功"
}

撤回多topic消息

API地址：https://api.xmpush.xiaomi.com/v1/message/multi_topic/revoke

HTTP请求方法：POST

添加HEADER字段Authorization，用于身份验证。格式是 key=<APP_SECRET>。

APP_SECRET是从开发者网站申请得到。

注意：字符key必须小写，例如：Authorization: key=YOUR_APP_SECRET

POST参数说明：

响应示例：

{
    "result": "ok",
    "trace_id": "Xdm01712568685156246Gj",
    "code": 0,
    "description": "成功"
}