Server API Address | 小米澎湃OS开发者平台

Server API Address更新时间: 2023-04-26 19:20:08

Server API Address and Parameters

If users expect to develop "ServerSDK" for other platforms, the API addresses and parameters provided below may be helpful.

If sending overseas messages, you must use the specified domain according to the region of the device

region	domain
Russia	https://ru-api.xmpush.global.xiaomi.com
India	https://idmb-api.xmpush.global.xiaomi.com
EEA+UK	https://fr-api.xmpush.global.xiaomi.com
other countries/regions	https://sgp-api.xmpush.global.xiaomi.com

All examples in this document use domain of "other countries/regions"(https://sgp-api.xmpush.global.xiaomi.com).The developer needs to select the correct domain according to the information in the above table according to the region where the device is located.

1. Push a single message

Formal environment

V2 interface:

Pushes a message to a RegID or a list of RegIDs.

https://sgp-api.xmpush.global.xiaomi.com/v2/message/regid

Pushes a message to an aliases or a list of aliases.

https://sgp-api.xmpush.global.xiaomi.com/v2/message/alias

Pushes a message to an account or a list of accounts.

https://sgp-api.xmpush.global.xiaomi.com/v2/message/user_account

Pushes a message to a topic.

https://sgp-api.xmpush.global.xiaomi.com/v2/message/topic

Pushes a message to multiple topics.

https://sgp-api.xmpush.global.xiaomi.com/v2/message/multi_topic

Pushes a message to all devices.

https://sgp-api.xmpush.global.xiaomi.com/v2/message/all

V3 interface (compatible with V2 interface and supports multiple package names):

Pushes a message to a RegID or a list of RegIDs (these RegIDs may belong to different package names)

https://sgp-api.xmpush.global.xiaomi.com/v3/message/regid

Pushes a message to an alias or a list of aliases (these aliases may belong to different package names).

https://sgp-api.xmpush.global.xiaomi.com/v3/message/alias

Pushes a message to a topic (you can specify one or more package names).

https://sgp-api.xmpush.global.xiaomi.com/v3/message/topic

Pushes a message to multiple topics (you can specify one or more package names).

https://sgp-api.xmpush.global.xiaomi.com/v3/message/multi_topic

Pushes a message to all devices (you can specify one or more package names).

https://sgp-api.xmpush.global.xiaomi.com/v3/message/all

HTTP request method: POST

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=<APP_SECRET> ".

APP_SECRET is obtained from the developer site.

Attention: The "key" must be lower case. For example, Authorization: key=YOUR_APP_SECRET.

Table 1-1. Android POST Parameters

Type	Parameter name	Description
String	payload	Message content.(Attention: Need to urlencode payload strings)
String	restricted_package_name	App package name.Note: Mi Push V2 supports 1 package name, while V3 supports multiple package names (separate them with commas).
Integer	pass_through	The value of pass_through could be:· 0, indicates notifications· 1, indicates transparent messages
String	title	The notification title shown on the notification shade can't be left blank. It must be less than 50 characters in length, and each ASCII/Non-ASCII character will be counted as 1 (required for notifications).
String	description	The notification description shown on the notification shade can't be left blank. It must be less than 128 characters in length, and each ASCII/Non-ASCII character will be counted as 1 (required for notifications).
Integer	notify_type	The value of notify_type could be "DEFAULT_ALL" or the "OR" combination of the following cases:· DEFAULT_ALL = -1;· DEFAULT_SOUND = 1; // Use default sound reminder;· DEFAULT_VIBRATE = 2; // Use default vibration reminder;· DEFAULT_LIGHTS = 4; // Use default LED light reminder;
long	time_to_live	Optional.Sets the retention time of messages on the server when the user goes offline. Unit: ms.Messages can be retained on the server for 2 weeks by default.
long	time_to_send	Optional.Sends messages regularly.It is expressed in 00:00:00.0 UTC time since January 1, 1970 (Time in milliseconds).Note: Only timed messages within seven days are supported.
Integer	notify_id	Optional.By default, only one push message is displayed in the notification shade.If you want to display multiple push messages in the notification shade, you need to set different notify_id for different messages (Notification shade messages with the same notify_id will overwrite the previous ones).
String	extra.sound_uri	Optional: Customize the message ringtone in the notification shade.The value of extra.sound_uri is set to the URI of the ringtone.(Please refer to the "Custom ringtones" section in "Server Java SDK Documentation".) Note: The ringtone file is placed under the raw directory of the Android application.
String	extra.ticker	Optional: Display notification messages in the status bar scroll.
String	extra.notify_foreground	Optional: Turn on/off notification pop-ups when the application is in the foreground.When the value of extra.notify_foreground is "1", the application will pop up a notification shade message; when the value of extra.notify_foreground is "0", the application will not pop up a notification shade message.Note: Notification shade messages will pop up by default. (Please refer to the "Control app foreground notification popup" section in "Server Java SDK Documentation".)
String	extra.notify_effect	Optional. Pre-declare the click behavior of notification shade messages.Different predefined click behaviors can be obtained by setting the value of extra.notify_effect.· "1": Click on the notification shade to open the Launcher Activity of the application.· "2": Open any Activity of the application after clicking on the notification shade (The developer also needs to include extra.intent_uri).· "3": Click on the notification shade to open the web page (The developer also needs to include extra.web_uri).(Please refer to "Click Behavior of Predefined Notification Shade Notifications" in "Server Java SDK Documentation".)
String	extra.intent_uri	Optional: Open any component of the current application.
String	extra.web_uri	Optional: Open a certain webpage.
int	extra.flow_control	Optional: Control whether smooth sending is required.Not supported by default.Value represents the speed of smooth push.Note: The server supports a minimum qps of 3000/s.In other words, if the smooth push is set to 1000, the real push speed is 3000/s.
String	extra.jobkey	Optional: Use the push batch (JobKey) function to aggregate messages.The client will be de-duplicated according to the jobkey, that is, only the first message of the same jobkey will be displayed, and other messages will be ignored.A legal jobkey consists of numbers ([0-9]), uppercase and lowercase letters ([a-zA-Z]), underscores (_) and underscores (-), and the length is not more than 20pcs Character, and cannot start with an underscore (_).
String	extra.callback	Optional: Turn on message receipt.After the message is sent, the push system can send a receipt to the developer to inform the developer of the delivery, click, or delivery failure status of these messages. Set the value of extra.callback to the http interface for the third party to receive receipts.For the interface protocol, please refer to the "Message Receipt" section in the "Server Java SDK Documentation".
String	extra.callback.param	Optional: Customize third-party receipt parameters with a maximum length of 64 bytes.
int	extra.callback.type	Optional: Indicate the type of receipt.For detailed usage, please refer to the callback.type field in the "Message Receipt" section in the "Server Java SDK Documentation".
String	extra.locale	Optional: Set the language range of devices that can receive messages, separated by commas.How to obtain the local of the current device:Locale.getDefault().toString()For example, mainland China is represented by zh_CN.
String	extra.locale_not_in	Optional: Set the language range of devices that cannot receive the message, separated by commas.
String	extra.model	Option for three model support usages.1. The model range of devices that can receive messages, separated by commas.How to obtain the model of the current device:Build.MODELFor example, the mobile version of the Mi 4 mobile phone is represented by "MI 4LTE".2. The brand range of devices that can receive messages, separated by commas.For example, Samsung mobile phones are represented by "samsung". (Currently including 42 mainstream brands; please refer to the "Brand List" appendix for the corresponding relationships)3. The price range of devices that can receive messages, separated by commas.For example, a device with a price of 0-999 is represented by "0-999". (Currently covering 4 price ranges; please refer to the "Price List" appendix for the corresponding relationships)
String	extra.model_not_in	Optional: Set the model range of devices that cannot receive the message, separated by commas.
String	extra.app_version	The version number of the application that can receive messages, separated by commas.The Android application version number is derived from the value of "android:versionName" in the manifest file.Note: MiPush_SDK_Client_2_2_12_sdk.jar (and later) versions are currently supported.
String	extra.app_version_not_in	The version numbers of applications that cannot receive messages, separated by commas.
String	extra.connpt	Optional: Specify that messages can only be received under a specific network environment.Currently only supports specifying "Wi-Fi".
String	extra.only_send_once	Optional: Set the value of extra.only_send_once to 1, which means that the messages are only sent once when the device is online, and offline messages are not cached for multiple delivery.
The following parameters apply to all HTTP APIs for push messages.
String	registration_id	Send a message to the specified device based on registration_id.Multiple registration_ids can be provided and sent to a group of devices. Different registration_ids are separated by commas.The parameter only applies to the "/message/regid" HTTP API.(Note: The payload string needs to be urlencoded)
String	alias	Send a message to the specified device based on the alias.Multiple aliases can be provided and sent to a group of devices. Different aliases are separated by commas.The parameter only applies to the "/message/alias" HTTP API.
String	user_account	Send a message to all devices that have set the user_account based on the user_accounts.Multiple user_accounts can be provided, separated by a comma between user_accounts.The parameter only applies to the "/message/user_account" HTTP API.
String	topic	Send a message to all devices subscribed to the topic based on the topic.The parameter only apply to the "/message/topic" HTTP API.
String	topics	Uses ;$; to separate the topic listNote: The topics parameter needs to be used in conjunction with the topic_op parameter, and the number of topics cannot exceed 5.The parameter only applies to the "/message/multi_topic" HTTP API.
String	topic_op	The operational relationship between topics.The following three types are supported:· UNION· INTERSECTION· EXCEPTFor example:If the list elements of topics are [A, B, C, D], the union result is A∪B∪C∪D, the intersection result is A ∩B ∩C ∩D, and the difference result is A-B-C-D.The parameter only applies to the "/message/multi_topic" HTTP API.

Table 1-2. iOS POST Parameters

Type	Parameter name	Description
String	description	The description of the notification displayed in the notification shade.
long	time_to_live	Optional.Sets the retention time of messages on the server when the user goes offline. Unit: ms.Messages can be retained on the server for 2 weeks by default.
long	time_to_send	Optional.Sends messages regularly.It is expressed in 00:00:00.0 UTC time since January 1, 1970 (Time in milliseconds).Note: Only timed messages within seven days are supported.
String	extra.sound_url	Optional: Set custom message ringtones.When the value is empty, it is silent, and default is the system default sound.
int	extra.badge	Optional.Notification badges.
int	extra.category	Optional.iOS8 push message quick reply category.
String	extra.only_send_once	Optional: Set the value of extra.only_send_once to 1, which means that the messages are only sent once when the device is online, and offline messages are not cached for multiple delivery.
The following parameters apply to all HTTP APIs for push messages.
String	registration_id	Send a message to the specified device based on registration_id.Multiple registration_ids can be provided and sent to a group of devices. Different registration_ids are separated by commas.The parameter only applies to the "/message/regid" HTTP API.
String	alias	Send a message to the specified device based on the alias.Multiple aliases can be provided and sent to a group of devices. Different aliases are separated by commas.The parameter only applies to the "/message/alias" HTTP API.
String	topic	Send a message to all devices subscribed to the topic based on the topic.Note: Not the same as providing multiple topics.The parameter only applies to the "/message/topic" HTTP API.
String	topics	Uses ;$; to separate the topic listNote: The topics parameter needs to be used in conjunction with the topic_op parameter.The parameter only applies to the "/message/multi_topic" HTTP API.
String	topic_op	The operational relationship between topics.The following three types are supported:· UNION· INTERSECTION· EXCEPTFor example:If the list elements of topics are [A, B, C, D], the union result is A∪B∪C∪D, the intersection result is A ∩B ∩C∩D, and the difference result is A-B-C-D.The parameter only applies to the "/message/multi_topic" HTTP API.

Additional parameter description:

1. The server can also define some POST parameters starting with "extra.", the POST parameter format is such as: extra.key=value.

Note: You can set up to 10 key-value pairs.

2. Use v2/message/all to send messages to all devices.The parameters are similar to sending a message to a topic, and there is no need to provide additional topic fields.

3. The parameter specification is the same as the description in the Message class and the Sender class.Alias, topic, and registration_id cannot appear at the same time. There can be multiple aliases, which means that messages are sent to the devices specified by these aliases.What is returned is a string in json format, including the following fields.

· "result": string, "ok" indicates success,

· "error" indicates failure.

· "description": string explains the reason for the failure to send the message.

· "data": string is itself a json string (Where the value of the id field is the Id of the message).

· "code": integer, 0 indicates success, non-zero indicates failure.

· "info": string, detailed information.

For example:

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

 {"result":"error","reason":"payload parameter cannot be empty","description":"missing required parameter ","code":10016}

Demo

1. Send messages to the devices designated by the three aliases "alias1", "alias2", and "alias3".

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000&pass_through=0&extra.sound_uri=android.resource://com.xiaomi.mipushdemo/raw/shaking

2. Send a message to the device whose registration_id is 123.

Request URL: https://sgp-api.xmpush.global.xiaomi.com/v2/message/regid Request 

Method: POST 

Form Data: description=notification_description&payload=this+is+xiaomi+push&restricted_package_name=com.xiaomi.mipushdemo&registration_id=123&title=notification_title&notify_type=2&time_to_live=1000&notify_id=0

3. Send messages to all devices subscribed to my_topic.

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000

4. Custom click behavior: Open the Launcher Activity of the application

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000&pass_through=0&extra.notify_effect=1

5. Custom click behavior: Open any component of the application

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000&pass_through=0&extra.notify_effect=2&extra.intent_uri=intent:#Intent;action=com.a.b.shot;end

6. Custom click behavior: Open webpage

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000&pass_through=0&extra.notify_effect=3&extra.web_uri=http://www.xiaomi.com

7. Send a message to devices subscribed to any tag in the [A,B,C,D] set.

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000

2. Push multiple messages

Formal environment

Push different messages for different RegIDs

https://sgp-api.xmpush.global.xiaomi.com/v2/multi_message/regids

Push different messages for different aliases

https://sgp-api.xmpush.global.xiaomi.com/v2/multi_message/aliases

Push different messages for different userAccounts

https://sgp-api.xmpush.global.xiaomi.com/v2/multi_message/user_accounts

HTTP request method: POST

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Attention: The "key" must be lower case. For example, Authorization: key=YOUR_APP_SECRET.

Table 2-1. Android POST Parameters

Type	Parameter name	Description
String	messages	Sent messages.Messages are strings in json format.(Note: urlencode processing is required for the messages string) For extra.sound_uri, extra.notify_foreground, extra.notify_effect, extra.intent_uri, extra.web_uri, and other Post parameters prefixed with extra, they need to be defined as a json string; the format is as follows: "extra":{"sound_uri":"XXX","notify_effect":"XX"....}When using https://sandbox.xmpush.xiaomi.com/v2/multi_messages/regids, the format meets:[{"target":"regid1","message":{"payload":"your content","restricted_package_name":"your packagename","pass_through":XXX,"notify_type":XXX,"description":"XXX","title":"XXX","time_to_live":XXX,"notify_id":XXX，"extra":{"sound_uri":"XXX","notify_effect":"XX"....}}},{"target":"regids2","message":{......}},...,{"target":"regidsN","message":{......}}]When using https://sandbox.xmpush.xiaomi.com/v2/multi_messages/aliases, the format meets:[{"target":"alias1","message":{"payload":"your content","restricted_package_name":"your packagename","pass_through":XXX,"notify_type":XXX,"description":"XXX","title":"XXX","time_to_live":XXX,"notify_id":XXX，"extra":{"sound_uri":"XXX","notify_effect":"XX"....}}},{"target":"alias2","message":{......}},...,{"target":"aliasN","message":{......}}]
long	time_to_send	Optional: Send batch messages regularly.It is expressed in 00:00:00.0 UTC time since January 1, 1970 (Time in milliseconds).Note:· When sending batch messages regularly, there is no need to set time_to_send for each message.· Only timed messages within seven days are supported.

Table 2-2. iOS POST Parameters

Type	Parameter name	Description
String	messages	Sent messages.Messages are strings in json format.(Note: urlencode processing is required for the messages string) For Post parameters prefixed with extra, such as extra.sound_url, extra.badge, extra.category, etc., they need to be defined as a json string with the following format: "extra":{"sound_url":"XXX","badge":"XXX"....,"category":"XXX"}When using https://sandbox.xmpush.xiaomi.com/v2/multi_messages/regids, the format meets:[{"target":"regid1","message":{"description":"XXX","time_to_live":XXX，"extra":{"sound_url":"XXX","badge":"XXX","category":"XXX"....}}},{"target":"regids2","message":{......}},...,{"target":"regidsN","message":{......}}]When using https://sandbox.xmpush.xiaomi.com/v2/multi_messages/aliases, the format meets:[{"target":"alias1","message":{"description":"XXX","time_to_live":XXX,"extra":{"sound_url":"XXX","badge":"XXX","category":"XXX"....}}},{"target":"alias2","message":{......}},...,{"target":"aliasN","message":{......}}]
long	time_to_send	Optional: Send batch messages regularly.It is expressed in 00:00:00.0 UTC time since January 1, 1970 (Time in milliseconds).Note:· When sending batch messages regularly, there is no need to set time_to_send for each message.· Only timed messages within seven days are supported.

What is returned is a string in json format, including the following fields.

· "result": string, "ok" indicates success, "error" indicates failure.

· "description": string explains the reason for the failure to send the message.

· "data": string is itself a json string (Where the value of the id field is the Id of the message).

· "code": integer, 0 indicates success, non-zero indicates failure.

· "info": string, detailed information.

Demo

Note: In order to see the format of json data more clearly, we did not use urlencode processing.However, in actual development, urlencode processing must be performed on json data.

1. Send different messages to different RegIDs

https://sgp-api.xmpush.global.xiaomi.com/v2/multi_message/regids?messages=[{"target":"regid1","message":


{"payload":"send message to regid1","restricted_package_name":"com.xiaomi.mipushdemo","pass_through":1,



"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","pass_through":1,



"notify_type":2,"description":"description2","title":"title2","time_to_live":20000}}]

2. Send different messages to different aliases

https://sgp-api.xmpush.global.xiaomi.com/v2/multi_message/aliases?messages=[{"target":"alias1","message":


{"payload":"send message to alias1","restricted_package_name":"com.xiaomi.mipushdemo","pass_through":1,



"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","pass_through":1,



"notify_type":2,"description":"description2","title":"title2","time_to_live":20000}}]

3. Get message statistics {Deprecated}

The https://sgp-api.xmpush.global.xiaomi.com/v1/stats/message/counters interface is used to obtain message statistical data.

This interface is currently obsolete. Please use the trace interface instead. For an introduction to the trace interface, please refer to the "4. Tracking Message Status" section.

4. Track message status

Get statistics for a certain message or a certain period of time

Track message

https://sgp-api.xmpush.global.xiaomi.com/v1/trace/message/status

Track messages within a certain time zone

https://sgp-api.xmpush.global.xiaomi.com/v1/trace/messages/status

HTTP request method: GET

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Attention: The "key" must be lower case. For example, Authorization: key=YOUR_APP_SECRET.

Table 4-1. GET parameter description of tracked message

Type	Parameter name	Description
String	msg_id	Optional: Indicate the message Id.
String	job_key	Optional: Set jobKey of the message group.If jobKey is not empty, query the status of the message group.Otherwise, use msg_id to query the status of a single message.

Demo:

{"result":"ok",

"description":"Success",

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

Table 4-2. GET parameter description for tracked messages within a certain time zone

Type	Parameter name	Description
long	begin_time	Indicates the starting timestamp, in ms.
long	end_time	Indicates the end timestamp, in ms.

Demo:

{"result":"ok",

"description":"Success",

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

Among which,

· id represents the id of a single message.

· resolved indicates the planned delivery number of the message.

· raw_counter indicates the target number of https original requests.

· invalid_target indicates the number of invalid targets (alias is invalid, user_account is invalid, etc.).

· app_not_register indicates the number of push services that the application has not registered.

· device_condition_unmatch indicates that the environment where the device is located does not meet the conditions set by the message (For example: network environment does not match, region does not match, application version does not match, model does not match, etc.).

· msg_send indicates the actual number of messages sent.

· delivered indicates the number of messages delivered.

· delivery_rate represents the delivery rate (Number delivered/effective number of devices).

· bar_closed indicates the number of blocked messages in the notification shade.

· msg_display indicates the number of messages displayed (Number of deliveries - Number of blocked notification shade messages).

· click indicates the number of clicks on the message.

· click_rate indicates the click rate (Number of clicks/delivery) of the message.

· create_time indicates the time the message was sent.

· time_to_live indicates the validity period of the message.

· msg_type indicates the way the message is sent (msg_type is divided into Common, BatchRegID, Alias, BatchAlias, Topic).

Bulk message statistics

The bulk message statistics data interface supports batch queries of corresponding message statistics based on multiple message IDs or jobkeys (Not more than 100).

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

HTTP request method: POST

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Attention: The "key" must be lower case. For example, Authorization: key=YOUR_APP_SECRET.

Table 4-3. Request parameter description

Type	Parameter name	Description
String[]	job_keys	jobkey list. Example: op335013,op335012
String[]	msg_ids	Message ID list Example: msgid1,msgid2

Example response:

{

    "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": "Success"

}

5. Subscribe/unsubscribe tags

Formal environment

Subscribe to RegID tags

https://sgp-api.xmpush.global.xiaomi.com/v2/topic/subscribe

Unsubscribe from RegID tags

https://sgp-api.xmpush.global.xiaomi.com/v2/topic/unsubscribe

Subscribe to alias tags

https://sgp-api.xmpush.global.xiaomi.com/v2/topic/subscribe/alias

Unsubscribe from alias tags

https://sgp-api.xmpush.global.xiaomi.com/v2/topic/unsubscribe/alias

Cancel all subscriptions for a label

https://sgp-api.xmpush.global.xiaomi.com/v2/topic/unsubscribe/all

HTTP request method: POST

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Attention: The "key" must be lower case. For example, Authorization: key=YOUR_APP_SECRET.

Description of parameters for /v2/topic/subscribe and /v2/topic/unsubscribe:

Table 5-1. Parameter description of subscribe/unsubscribe RegID labels

Type	Parameter name	Description
String	registration_id	Device regid list, separated by commas, required.Limit: Up to 1000 RegIDs.
String	topic	Label, required.
String	restricted_package_name	Package name.Note: If multiple package names are set in the application, they are required.
String	category	Optional.

Demo:

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

Description of parameters for /v2/topic/subscribe/alias and /v2/topic/unsubscribe/alias:

Table 5-2. Parameter description of subscribe/unsubscribe alias labels

Type	Parameter name	Description
String	aliases	Each alias is separated by a comma and is required.Limit: Up to 1000 aliases.
String	topic	Label, required.
String	restricted_package_name	Package name.Note: If multiple package names are set in the application, they are required.
String	category	Optional.

Demo:

https://sgp-api.xmpush.global.xiaomi.com/v2/topic/subscribe/alias?alias=abc&topic=tt

Parameter description for /v2/topic/unsubscribe/all:

Table 5-3. Parameter description for canceling all subscriptions of a certain label

Type	Parameter name	Description
String	topic	Label, required.
String	restricted_package_name	Package name.Note: If multiple package names are set in the application, they are required.
String	category	Optional.

Demo:

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

HTTP request method: POST

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Attention: The "key" must be lower case. For example, Authorization: key=YOUR_APP_SECRET.

6. Get a list of invalid regIds

The feedback interface is offline. Please use the message return receipt callback instead. Set extra.callback.type=16 to get a list of invalid target devices.

Type	Parameter name	Description
String	extra.callback	Optional: Turn on message receipt.After the message is sent, the push system can send a receipt to the developer to inform the developer of the delivery, click, or delivery failure status of these messages.Set the value of extra.callback to the http interface for the third party to receive receipts.For the interface protocol, please refer to the "Message Receipt" section in the "Server Java SDK Documentation".
String	extra.callback.param	Optional: Customize third-party receipt parameters with a maximum length of 64 bytes.
int	extra.callback.type	Optional: Indicate the type of receipt.For detailed usage, please refer to the callback.type field in the "Message Receipt" section in the "Server Java SDK Documentation".

7. Get all the aliases currently set by a user of an application

Formal environment

API address:

https://sgp-api.xmpush.global.xiaomi.com/v1/alias/all

HTTP request method: GET

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Note: The character key must be lowercase.Example: Authorization: key=YOUR_APP_SECRET

Table 7-1. Obtain all Alias GET

Type	Parameter name	Description
String	restricted_package_name	Optional.Application package names, because one AppId may correspond to multiple package names, use this parameter to specify a specific package name.
String	registration_id	Query the regId of the device.

What is returned is a string in json format.

If successful, the format of the returned string is as follows.

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

If it fails, the format of the returned string is as follows.

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

8. Obtain all topics to which a user of an application is currently subscribed

Formal environment

API address:

https://sgp-api.xmpush.global.xiaomi.com/v1/topic/all

HTTP request method: GET

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Note: The character key must be lowercase.Example: Authorization: key=YOUR_APP_SECRET

Table 8-1. GET parameter description for obtaining all topics

Type	Parameter name	Description
String	restricted_package_name	Optional.Application package names, because one AppId may correspond to multiple package names, use this parameter to specify a specific package name.
String	registration_id	Query the regId of the device.

What is returned is a string in json format.

If successful, the format of the returned string is as follows.

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

If it fails, the format of the returned string is as follows.

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

9. Get all valid regIds corresponding to a userAccount

Formal environment

API address:

https://sgp-api.xmpush.global.xiaomi.com/v1/useraccount/get_regids_by_useraccount

HTTP request method: GET

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Note: The character key must be lowercase.Example: Authorization: key=YOUR_APP_SECRET

Table 9-1. GET parameter description

Type	Parameter name	Description
String	packageName	Optional.Application package names, because one AppId may correspond to multiple package names, use this parameter to specify a specific package name.
String	userAccount	The userAccount to be queried.
Long	appId	AppId of the application.

What is returned is a string in json format.

If successful, the format of the returned string is as follows.

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

If it fails, the format of the returned string is as follows.

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

10. Detect/delete scheduled tasks

Formal environment

Detect whether the timing task exists

https://sgp-api.xmpush.global.xiaomi.com/v2/schedule_job/exist

Delete scheduled tasks

https://sgp-api.xmpush.global.xiaomi.com/v2/schedule_job/delete

HTTP request method: POST

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Note: The character key must be lowercase.Example: Authorization: key=YOUR_APP_SECRET

Table 10-1. List of parameters

Type	Parameter name	Description
String	job_id	Indicates the message Id.

What is returned is a string in json format.

· A code of 0 indicates success; otherwise indicates failure.

· reason indicates the reason for the failure.

11. Push rich-text messages

11.1 Large image, large text

Please refer to "4.4.1 Large image/Large text/Large icon" in "Server Java SDK Documentation" for an introduction to large image and large text message styles.

Related fields

Type	Parameter name	Description
String	extra.notification_style_type	Used to distinguish between ordinary copies, large-image copies, and multi-character version copies.0 indicates an ordinary copy; 1 indicates a multi-character version; 2 indicates a large-image version.
String	extra.notification_bigPic_uri	Large image URL; used for large picture version copies.Image requirements: the mainland China version requires an image size of 876324 px; the global version requires an image size of 984450 px.The format must be png or jpg.
String	extra.notification_large_icon_uri	Large icon URL.Large icons can appear in large-image and multi-character messages, and are displayed on the right.The mainland China version is only supported by MIUI12 and above, and the following versions are not supported; the global version is supported.Image requirements: size 120*120 px, png or jpg format.

Left button settings:

Type	Parameter name	Description
String	extra.notification_style_button_left_notify_effect	Actions after clicking the button on the left support the following values:· 1: Open the application· 2: Open the specified page in the app· 3: Open webpageIf it is not configured or it is configured to other values, the button will not be displayed.
String	extra.notification_style_button_left_name	The name of the button on the left. This parameter must be configured. If it is not configured, the button will not be displayed.
String	extra.notification_style_button_left_intent_uri	Open the application.
String	extra.notification_style_button_left_web_uri	Click the button on the left to open the designated web page.
String	extra.notification_style_button_left_intent_class	Click the button on the left to open the specified page in the application.

Right button settings:

Type	Parameter name	Description
String	extra.notification_style_button_right_notify_effect	Actions after clicking the button on the right support the following values:· 1: Open the application· 2: Open the specified page in the application· 3: Open webpageIf it is not configured or it is configured to other values, the button will not be displayed.
String	extra.notification_style_button_right_name	The name of the button on the right. This parameter must be configured. If it is not configured, the button will not be displayed.
String	extra.notification_style_button_right_intent_uri	Open the application.
String	extra.notification_style_button_right_web_uri	Click the button on the right to open the designated web page.
String	extra.notification_style_button_right_intent_class	Click the button on the right to open the specified page in the application.

Middle button settings:

Type	Parameter name	Description
String	extra.notification_style_button_mid_notify_effect	Actions after clicking the middle button support the following values:· 1: Open the application· 2: Open the specified page in the application· 3: Open webpageIf it is not configured or it is configured to other values, the button will not be displayed.
String	extra.notification_style_button_mid_name	The name of the middle button. This parameter must be configured. If it is not configured, the button will not be displayed.
String	extra.notification_style_button_mid_intent_uri	Open the application.
String	extra.notification_style_button_mid_web_uri	Click the middle button to open the designated web page.
String	extra.notification_style_button_mid_intent_class	Click the middle button to open the specified page in the application.

Upload large-image API

Request URL:

https://sgp-api.xmpush.global.xiaomi.com/media/upload/image

Request Method:POST

Params:

file = xxx // MultipartFile, Image requirements: Large image size 876*324 px; the global version requires image size 984*450 px.The large icon must be png or jpg format.



is_global = <true|false> // bool, whether it is used in the global version



is_icon = <true|false> // bool, whether it is an icon.If it is false, it indicates a large image is uploaded; a large image URL and a cropped and zoomed icon URL will be returned

Our file upload interface reads the file code stream and parameters read from the standard http multipart message, which is parsed into a MultipartFile object on the server side. For other languages, it is sufficient to send the http message according to the multipart standard. The message example is as follows:

POST /media/upload/image HTTP/1.1

Content-Type: multipart/form-data; boundary=--------------------------459030140943653165028478

Authorization: key=XXXXXXXXXXXXX

User-Agent: XXXXXXX

Accept: */*

Host: ip:port

accept-encoding: gzip, deflate

content-length: 905

Connection: keep-alive

----------------------------459030140943653165028478

Content-Disposition: form-data; name="file"; filename="1553156439(1).png"

Content-Type: image/png



Here is the binary content of the file

----------------------------459030140943653165028478

Content-Disposition: form-data; name="is_global"

false

----------------------------459030140943653165028478

Content-Disposition: form-data; name="is_icon"

false

----------------------------459030140943653165028478--

Response:

{

    "result": "ok",

    "trace_id": "Xcm53055545898060552Hb",

    "code": 0,

    "data": {

        "icon_url": "http://t1.market.mi-img.com/thumcrop/webp/h120/MiPass/07ae3e4c2b0d647803fdb42931fd58e7980750b6d/icon.webp?crop=l276r600",

        "sha1": "83dc9643017db9dfa0f3885520947102fed05340",

        "pic_url": "http://f7.market.xiaomi.com/download/MiPass/07ae3e4c2b0d647803fdb42931fd58e7980750b6d/83dc9643017db9dfa0f3885520947102fed05340.png"

    },

    "description": "Success"

}

Using large images and large text messages with API

Large image and large text messages have nothing to do with the push method, so whether it is topic, broadcast, or alias, push methods support pushing large image and multi-character versions.

Take an alias message as an example:

· Original sending method:

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000 &pass_through=0&extra.layout_name=custom_notify

· If you add large image information, upgrade to a large image message, and add the button on the left, so the sending demo becomes:

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000&pass_through=0&extra.notification_style_type=2&extra.notification_bigPic_uri=http://www.xiaomi.com.jpg&extra.notification_style_button_left_notify_effect=3&extra.notification_style_button_left_web_uri=http://admin.xmpush.xiaomi.com

· If you are sending a large text message:

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000&pass_through=0&extra.notification_style_type=1&extra.notification_large_icon_uri=https://dev.mi.com/console/doc/detail?pId=1163.png

11.2 Small icon

For an introduction to the small icon style, please refer to "4.4.2. Small icon" in "Server Java SDK Documentation".

Note: The small icon image must be a transparent and white image.Do not upload graphics of other colors, color them with setColor instead.

Related fields

Type	Parameter name	Description
String	extra.notification_small_icon_uri	Small icon image URL.For devices of different sizes, there is no need to upload small icons of different sizes. It is recommended to uniformly use 60 x 60 px.
String	extra.notification_small_icon_color	small icon The color the image will be changed into.The format is hexadecimal.

Use small icons with API

· Original push method:

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000&pass_through=0&extra.sound_uri=android.resource://com.xiaomi.mipushdemo/raw/shaking

· Push with small icons:

Request URL: https://sgp-api.xmpush.global.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&notify_type=2&time_to_live=1000&pass_through=0&extra.sound_uri=android.resource://com.xiaomi.mipushdemo/raw/shaking&extra.notification_small_icon_color=#ABCDEF&extra.notification_small_icon_uri=http://f7.market.xiaomi.com/download/MiPass/0dae348c2e00697874fdbf293a0d53eb9db43618e/943bad192939eb69b05d85ff0171a04240a6cbef.png

12. Notification class (Channel)

Notification category (Channel) introduction

Notification class (Channel) is a new feature introduced by Android O to solve the following problems:

· There are more and more notifications in the app, causing obvious interruptions to users.

· However, users can only block all notifications of this application globally, not some of them while leaving the ones that are useful to them.

To solve this problem, Android supports developers to divide their notifications into several categories, and then allows users to block notifications in a certain category individually.

Description: The current version does not currently support setting Channel Group.

Method

Note:

Users can create up to 8 channels.

The Channel_id of each Channel can't be repeated, and the Channel_name is also not allowed to be repeated.

Once a Channel is created and sent with a message, the Channel will be generated on the device, and it can't be deleted or modified, so be careful when creating a Channel.

· Add new Channel

API address:

https://sgp-api.xmpush.global.xiaomi.com/v1/channel/add

POST parameter description:

Type	Parameter name	Description
String	channel_id	Required: The notification category ID. The length should not exceed 200 characters.
String	channel_name	Required: The name of the notification category. The length should not exceed 40 characters.
Integer	notify_type	Required: The type of effect when the user receives the notification. The following values are supported:· 1: Use default sound reminder· 2: Use the default vibration prompt· 4: Use the default led light prompt· -1 (System default value): All of the above three effects· 0: None of the above three effects, that is to say, silent push.
String	channel_description	Optional: Describe the notification category, briefly introducing which type of notification is stored in the category, with a length not exceeding 300 characters.
String	sound_url	Optional: Customize notification ringtone uri; please refer to "Server Java SDK Document"> Custom Ringtone for an introduction to the format.

Description:

Data sync set through the API and operating platform, and the Channel set through the API can be viewed and set directly on the operating platform.It takes a few minutes to sync after the channel is set up.

· Obtain all valid Channels:

API address:

https://sgp-api.xmpush.global.xiaomi.com/v1/channel/list

· Abandon a Channel:

API address:

https://sgp-api.xmpush.global.xiaomi.com/v1/channel/discard

POST parameter description:

Type	Parameter name	Description
String	channel_id	Required: The ID of the notification category.

· Send a message with Channel:

Parameter Description:

Type	Parameter name	Description
String	extra.channel_id	Required: The notification category ID.
String	extra.channel_name	Optional: Select the name of the notification category.
String	extra.channel_description	Optional: Describe the notification category.

Example of adding a Channel:

https://sgp-api.xmpush.global.xiaomi.com/v1/channel/add

13. Batch query RegID registration area

If the target users include users inside and outside mainland China, you can use this interface to query the target user's home region, and then use the interfaces inside and outside mainland China to push messages respectively.

API address:

https://sgp-api.xmpush.global.xiaomi.com/v1/feedback/get_region_by_regid

HTTP request method: POST

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Attention: The "key" must be lower case. For example, Authorization: key=YOUR_APP_SECRET.

POST parameter description:

Type	Parameter name	Description
String	regIds	A list of regIds, separated by English commas. For example: F8NdgKEFL+hbRvvqNrHAFqFddWp46warurFYdCYluX0=, kL0Fqg/wnDAfnGxpGTUrC1DGHi8XtzfJs4H+NA/XAtw=

Example response:

{

    "result": "ok",

    "trace_id": "Xdm01712568685156246Gj",

    "code": 0,

    "data": {

        "F8NdgKEFL+hbRvvqNrHAFqFddWp46warurFYdCYluX0=": "CN",

        "kL0Fqg/wnDAfnGxpGTUrC1DGHi8XtzfJs4H+NA/XAtw=": "CN"

    },

    "description": "Success"

}

14. Message termination

In some cases, operating personnel may send messages by mistake. In this case, the "message termination" function can be used to immediately stop message delivery to intercept the message sending in time and prevent the influence from expanding.

Stop the message based on message ID

API address:

https://sgp-api.xmpush.global.xiaomi.com/v1/message/switch/stop_by_id

HTTP request method: POST

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Attention: The "key" must be lower case. For example, Authorization: key=YOUR_APP_SECRET.

POST parameter description:

Type	Parameter name	Description
String	restricted_package_name	App package name.
String[]	msg_ids	List of message IDs that need to be terminated.

Example response:

{

    "result": "ok",

    "trace_id": "Xdm01712568685156246Gj",

    "code": 0,

    "description": "Success"

}

Stop the message according to the message jobkey

API address:

https://sgp-api.xmpush.global.xiaomi.com/v1/message/switch/stop_by_jobkey

HTTP request method: POST

Add "Authorization" to the "HEADER field" for identity verification.The format is "key=".

APP_SECRET is obtained from the developer site.

Attention: The "key" must be lower case. For example, Authorization: key=YOUR_APP_SECRET.

POST parameter description:

Type	Parameter name	Description
String	restricted_package_name	App package name.
String[]	job_keys	The jobkey list of messages that need to be stopped.

Example response:

{

    "result": "ok",

    "trace_id": "Xdm01712568685156246Gj",

    "code": 0,

    "description": "Success"

}

Other parameters

1. APNs

aps_proper_fields.title Title

aps_proper_fields.subtitle Sub-title

aps_proper_fields.body Content

aps_proper_fields.mutable-content mutable-content

文档内容是否有帮助？

有帮助

无帮助

本页导读

1. Push a single message

2. Push multiple messages

3. Get message statistics {Deprecated}

4. Track message status

5. Subscribe/unsubscribe tags

6. Get a list of invalid regIds

7. Get all the aliases currently set by a user of an application

8. Obtain all topics to which a user of an application is currently subscribed

9. Get all valid regIds corresponding to a userAccount

10. Detect/delete scheduled tasks

11. Push rich-text messages

12. Notification class (Channel)

13. Batch query RegID registration area

14. Message termination