Create Push API
Push a notification or message to a single device or a device list.The pushed content can only be a push json object.
info This is the latest version of the Push API. The v4 version is improved as follows:
- Use HTTP Basic Authentication for access authorization. In this way, the entire API request can be completed using common HTTP tools, such as curl, browser plug-ins, etc.
- Push request Content-Type completely uses JSON format.
Request Authorization
For more information, see REST API overview authentication method description.
Push Url
POST https://push.api.engagelab.cc/v4/push
Request example
Request header
> POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==
Request body
{
"from": "push",
"to": "all",
"body": {
"platform": "all",
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"builder_id": 1,
"extras": {
"newsid": 321
}
},
"ios": {
"alert": "Hi, MTPush!",
"sound": "default",
"badge": "+1",
"extras": {
"newsid": 321
}
}
},
"message": {
"msg_content": "Hi,MTPush",
"content_type": "text",
"title": "msg",
"extras": {
"key": "value"
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
},
"request_id": "12345678",
"custom_args": "business info"
}
Request Parameters
The parameter structure of the push, as detailed in the following table.
key word | type | option | description |
---|---|---|---|
from | String | optional | the user who send the request |
to | String or JSON Object | required | target that user will send to |
body | JSON Object | required | request body |
platform | String or JSON Array | required | platform type: android, ios |
notification | JSON Object | optional | |
message | JSON Object | optional | |
options | JSON Object | optional | push parameters |
request_id | String | optional | Optional field customized by the customer, which is used by the customer to identify which request it is, and is returned when responding |
custom_args | JSON Object | optional | Optional field customized by the customer, which is returned to the customer during callback |
from
the user who send the request, String type, optional field.
Request Example
{
"from":"push"
}
to
The push device object indicates which device lists a push can be pushed to. To confirm the push device object, MTPush provides two methods: broadcast and registration ID
Push target
key word | data format | target type | description | notes |
---|---|---|---|---|
all | String | broadcast | Push to all the devices | Push target is active devices within 30 days |
registration_id | JSON Array | registration ID | Registration Id Array List. The OR relationship between multiple registration IDs is union. | DeviceId, Up to 1000 at a time |
Request example
- push to all targets(broadcast):
{
"to": "all",
}
- push to multiples registration_ids:
{
"to": {
"registration_id": [
"4312kjklfds2",
"8914afd2",
"45fdsa31"
]
}
}
body
request body, the fields like below:
key word | format | option | description |
---|---|---|---|
platform | String or JSON Array | required | platform type: android, ios |
notification | JSON Object | optional | |
message | JSON Object | optional | |
options | JSON Object | optional | push parameters |
platform
MTPush support Android, iOS platform, the key words:"android" and "ios"
info If the target platform is iOS, you need to use apns_production field in options to specify the push environment. True means to push the production environment, and false means to push the development environment; If not specified, it is the push production environment.
push to all the platform:
{ "platform" : "all" }
specify the platform:
{
"platform": [
"android",
"ios"
]
}
notification
The "notification" object is one of the pushed entity content objects (the other is "message"), which will be pushed to the device as a "notification"
key word | format | option | type | description |
---|---|---|---|---|
alert | String or JSON Object | required | content | The message/notification content. If no alert is specified under android and ios, it will take effect |
android | JSON Object | optional | android platform | android platform parameters,see android |
ios | JSON Object | optional | ios platform | ios platform parameters,see ios |
alert
The "alert" attribute of this location (directly under the notification object) is a quick definition. If the alert information of each platform is the same, the alert under the platform does not need be defined. If each platform has a definition, the definition here will be overwritten
{
"notification" : {
"alert" : "Hello, Push!"
}
}
The notification object defined above will be pushed to multiple platforms specified by "platform", and its notification alert information is the same
android
Notifications on the Android platform are displayed by the MTPush SDK in a certain notification bar style. The supported fields are as follows:
key word | format | option | type | description |
---|---|---|---|---|
alert | String or JSON Object | required | notification content | |
title | String | optional | notification title | |
builder_id | Int | optional | notification style id | The Android SDK can set the style of the notification bar. Here, you can specify which style to use according to the style ID |
channel_id | String | optional | Android notification channel ID | No more than 1000 bytes, and the NotificationChannel can be configured from Android 8.0. Here, the notification bar display effect is specified according to the channel ID |
priority | Int | optional | Notification bar display priority | default 0,range -2~2。 |
category | String | optional | Notice bar filter and sort | It completely depends on the processing strategy of the rom manufacturer for the category. |
style | Int | optional | Notification bar style type | Used to specify the notification bar style typedefault: 0 |
big_text | String | optional | big document notification bar style | |
inbox | JSONObject | optional | document list notification bar style | |
big_pic_path | String | optional | Text entry notification bar style | |
extras | JSON Object | optional | additional fields | Here, you can customize the key/value information in JSON format for business use |
intent | JSON Object | optional | specify the click jump page url | Use the intent url to specify the target page to jump to after clicking the notification bar.It is recommended to fill in the intent field, otherwise click the notice and there may be no jump action, there are two jump methods like below: intent:#Intent;action=action path;component= packageName/ActivityFullPath;end(OPPO and FCM must be config "action path", other manufacturer must config "ActivityFullPath", otherwise click the notice and there may be no jump action) |
large_icon | String | optional | notification big icon | |
small_icon | String | optional | notification small icon | |
sound | String | optional | sound | |
badge_add_num | Int | optional | set the badge number accumulation value, and accumulate based on the original badge value | |
badge_class | String | optional | The application entry activity class corresponding to the desktop icon, such as "com. test. badge. MainActivity" |
{
"notification": {
"android": {
"alert": "hello, MTPush!",
"title": "Push test",
"builder_id": 3,
"style": 1,
"big_text": "big text content",
"inbox":JSONObject,
"big_pic_path": "picture url",
"priority": 0,
"category": "category str",
"large_icon": "http://push.api.engagelab.cc/largeIcon.jpg",
"small_icon": "http://www.small.com/small_icon.jpg",
"intent": {
"url": "intent:#Intent;component=push.api.engagelab.cc/com.example.mtpushdemo.SettingActivity;end"
},
"extras": {
"news_id": 134,
"my_key": "a value"
}
}
}
}
ios
apns notification in iOS platform
The content of this notification will be sent to the Apple APNs server by the MTPush agent and displayed on the iOS device in the system notification mode
The notification content meets the specification of APNs, and the supported fields are as follows:
key word | format | option | type | description |
---|---|---|---|---|
alert | String or JSON Object | required | content | |
sound | String or JSON Object | optional | sound | |
badge | Int or String | optional | application badge | |
content-available | Boolean | optional | push wake up | When pushing, carry "content available": true indicates background remote notification. If this field is not carried, it is a normal remote notification. Reference for details:Background Remote Notification |
mutable-content | Boolean | optional | Notification Extension | The Notification Service Extension function added in iOS 10 is used to report the delivery status of each APN information. To use this function, the client needs to implement the Service Extension interface and use the mutable content field on the server to complete the settings |
category | String | optional | support until iOS 8 。set the category field in APNs payload | |
extras | JSON Object | optional | Extended Fields | custom key/value fields |
thread-id | String | optional | Notification grouping | IOS remote notifications are grouped by this attribute. Notifications of the same thread id are grouped together |
interruption-level | String | optional | Interruption levels for notification priority and delivery time | The notification level of iOS 15 can only be one of active, critical, passive and timeSensitive,reference for details:UNNotificationInterruptionLevel |
info IOS notifies MTPush to forward to APNs server The length of Notification+Message in MTPush is limited to 4000 bytes MTPush uses utf-8 encoding when pushing, so a Chinese character takes up 3 bytes.
server send example:
{
"notification": {
"ios": {
"alert": "hello, Push!",
"sound": "sound.caf",
"badge": 1,
"extras": {
"news_id": 134,
"my_key": "a value"
}
}
}
}
client received message example:
{
"_j_msgid" = 813843507;
aps = {
alert = "hello,Push!";
badge = 1;
sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}
message
message in the application or called custom message, transparent message
- This part of the content will not be displayed on the notice bar. The MTPush SDK will transmit the message content to the App after receiving it. App needs to handle by itself.
- IOS obtains this part of content in the push app message channel (non APNS), and the app must be in the foreground.
The supported fields are as follows:
key word | format | option | description |
---|---|---|---|
msg_content | String or JSON Object | required | message content |
title | String | optional | message title |
content_type | String | optional | message content type |
extras | JSON Object | optional | JSON format optional parameters |
示例:
{
"message": {
"msg_content": "Hi,Push",
"content_type": "text",
"title": "msg",
"extras": {
"key": "value"
}
}
}
options
Push options. Currently, the following options are included:
key word | format | option | type | description |
---|---|---|---|---|
time_to_live | Int or String | optional | offline message retention time (seconds) | |
override_msg_id | Long | optional | message ID will be overwrite | If the current push wants to overwrite the previous push, fill in the msg of the previous push here_ ID will produce coverage effect: |
apns_production | Boolean | optional | APNs production environment | This field is only valid for iOS Notification. If it is not specified, it will be pushed to the production environment. Notice:The MTPush official API LIBRARY (SDK) is set to push the "development environment" by default. |
apns_collapse_id | String | optional | Update the identifier of iOS notification | |
big_push_duration | Int | optional | Constant speed push duration (min) | |
third_party_channel | JSON Object | optional | Android Manufacturer channel configuration information | Only valid parameters for users configured with manufacturer channels,reference for details third_party_channel |
third_party_channel
this field is used to fill in the personalized information of Android manufacturer channels. The key only supports seven Android manufacturer channels: xiaomi, huawei, meizu, oppo, vivo, honor and fcm. One or more of them can exist at the same time,key of each manufacturer type can currently include the following options:
key word | format | option | type | description |
---|---|---|---|---|
distribution_new | String | required | When Engagelab and manufacturer channel coexist, set the priority of distribution | The value cannot be an empty string.For fcm + domestic vendor combination type users: |
channel_id | String | optional | Notification bar message classification | support OPPO private message、Xiaomi's notification message、Huawei Message Classification ,The category ChannelID value needs to be applied by the developer to the manufacturer |
classification | Int | optional | Notification bar message classification | vivo Mobile phone manufacturer notification bar message classification, default: 0。 |
pushMode | Int | optional | vivo push mode | default: 0。Reference for details vivo pushMode,To use test push, you need to manually configure the ID of the test device in the vivo background |
importance | String | optional | Huawei/honor notification bar message intelligent classification | In order to adapt to the intelligent classification of Huawei mobile phone manufacturers' notification bar messages, the corresponding import field of Huawei is not filled, and the default is "NORMAL",reference:Huawei notification message intelligent classification, |
urgency | String | optional | Huawei Manufacturer Customized Message Priority | Adapt the priority of customized messages from Huawei mobile phone manufacturers |
category | String | optional | Huawei Manufacturer Customized Message Scenario ID | In order to adapt Huawei mobile phone manufacturers' customized messages, identify special scenarios of high priority transparent messages, or identify message types to speed up the sending of specific types of messages,reference for details:category value description。 |
small_icon_uri | String | optional | Small icon style of manufacturer message | |
small_icon_color | String | optional | xiaomi manufacturer's small icon style and color | |
only_use_vendor_style | Boolean | optional | Whether to use its own channel to set the style | Whether to use only the style set in its own channel, not the style set in Android default is false, |
request example:
"third_party_channel": {
"xiaomi": {
"distribution_new": "mtpush",
"channel_id": "*******",
"small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png",
"small_icon_color": "#ABCDEF",
},
"huawei": {
"distribution_new": "mtpush_pns",
"importance": "NORMAL",
"small_icon_uri": "https://xx.com/xx.jpg",
"only_use_vendor_style": true
},
"meizu": {
"distribution_new": "mtpush"
},
"fcm": {
"distribution_new": "mtpush"
},
"oppo": {
"distribution_new": "mtpush",
"channel_id": "*******",
"large_icon": "3653918_5f92b5739ae676f5745bcbf4",
},
"vivo": {
"distribution_new": "mtpush",
"classification": 0,
"pushMode": 0
}
}
request_id
developer can custom this optional field, used for identify the message request and return response
request example
{
"request_id":"12345678"
}
response example
{
"msg_id": "1225764",
"request_id": "12345678"
}
custom_args
Customer defined, optional field, not returned in response, returned in callback
request example
{
"custom_args":"business info"
}
Response parameters
Success response
field | type | option | description |
---|---|---|---|
request_id | String | Optional | The custom ID submitted on request, returned as is on response. |
message_id | String | Required | The message ID to uniquely identify a message. |
< HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id": "18", "msg_id": "1828256757"}
Failure response
The http status code is 4xx or 5xx and the response body contains the following fields.
Field | Type | Option | Description |
---|---|---|---|
code | int | required | the error code. For more information, see return-code description |
message | String | required | error details |
{
"code": 3002,
"message": "Push.template field must be set correctly when type is template"
}
Call and Rerturn
HTTP status code
Reference Documents:HTTP-Status-Code
return code
Code | message | description | HTTP Status Code |
---|---|---|---|
20101 | push paramters invalid | registration_id invalid or not belong this appkey | 400 |
21001 | only support HTTP Post method | not support Get method | 405 |
21002 | A required parameter is missing | Must be corrected | 400 |
21003 | Illegal parameter value | Must be corrected | 400 |
21004 | Validation failed | Must be corrected,Reference for details:Call validation | 401 |
21005 | message body is too lang | Must be corrected, Notification+Message length is limited to 2048 bytes | 400 |
21008 | app_key invalid parameter | Must be corrected,Please carefully compare whether the appkey you passed is consistent with the application information, and whether there are more spaces | 400 |
21009 | System internal error | Must be corrected | 400 |
21011 | There are no push targets that meet the conditions | please check 'to' field | 400 |
21015 | Request parameter verification failed | Unexpected parameter exists | 400 |
21016 | Request parameter verification failed | Wrong parameter type, or the parameter length exceeds the limit | 400 |
21030 | Internal service timeout | Try again later | 503 |
23006 | Parameter error | Constant speed pushbig_push_duration Maximum exceeded 1440 | 400 |
27000 | System memory error | System memory error | 500 |
27001 | Parameter error | Try again later | 401 |
27008 | Parameter error | the distribution field in third_party_channel is not empty, but content of alert in notification is empty | 401 |
27009 | Parameter error | third_party_channel.distribution field format invalid or empty | 401 |
push limit
Channel | title length | content length | Sensitive words | other description |
---|---|---|---|---|
Engagelab Channel | No limit, but limit the total message body size | No limit, but limit the total message body size | - | the length of Notification and Message is limited to 4000 bytes. |
huawei Channel | < 40 char | < 1024 char | It is prohibited to carry the government, leader's name, Taiwan independence and other relevant contents | By default, the permission of [Marketing Notice] is silent notification. Silent push has no prompts such as sound and vibration. |
meizu Channel | < 32 char | < 100 char | Prohibit special characters,such as: # | |
xiaomi Channel | < 50 char | < 128 char | Prohibit special characters,such as: # >> | |
OPPO Channel | < 32 char | < 200 char | - | |
vivo Channel | < 40 char | < 100 char | ||
APNS Channel | < 20 char(40 english characters. ) | - | - |