create push API
Push a notification or message to a single device or a list of devices.
The pushed content can only be a pushed object represented by JSON.
This is the latest version of the Push API. The improvements in the v4 version are:
- 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 content is completely in JSON format.
Request method
POST
Call address
The interface service address is in one-to-one correspondence with the selected access point of the data center. Please select the calling address corresponding to your application service access point.
At present, EngageLab has deployed and supported two data center access points, and the data between different service access points is completely isolated. You can select the invocation address according to the data center access point selected when creating the product.
- Singapore data center calling address:
POST https://push.api.engagelab.cc/v4/push
- Call address of data center in Virginia, USA
POST https://push-usva.api.engagelab.cc/v4/push
Call validation
For more information, see the REST API overview of Authentication Method description。
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"
}'
> POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==
Request Parameter
The parameter structure of the push, as detailed in the following table:
Keyword | Type | Option | Meaning |
---|---|---|---|
from | String | Optional | Current service sender |
to | String or JSON Object | Required field | Send target |
body | JSON Object | Required field | Send request体 |
platform | String or JSON Array | Required field | Push Platform |
notification | JSON Object | Optional | |
message | JSON Object | Optional | |
options | JSON Object | Optional | Push parameter |
request_id | String | Optional | Customer-defined optional field that the customer uses to identify which request is being returned in response. |
custom_args | JSON Object | Optional | Customer-defined optional fields that are returned to the customer on callback. |
from
Current service sender, String type, optional field.
Request Example
{
"from":"push"
}
to
Push Device Object, which indicates the list of devices to which a push can be pushed. To confirm the push device object, App Push provides various ways, such as: alias, tag, registration ID, subgroup, broadcast, etc.
Push Target
There are several ways to choose equipment outside of broadcasting, as follows:
Keyword | Type | Meaning | Description | Note |
---|---|---|---|---|
all | String | Send broadcast | Push for all devices | The push targets devices that have been active within 30 days. |
tag | JSON Array | Tag | Arrays. The relationship between multiple tags is OR, i.e., take the concatenation. | Use tags to perform large-scale device attribute, user attribute subgroups. |
tag_and | JSON Array | Tag AND | Array. Multiple tags are in an AND relationship, i.e., they take the intersection. | Note the distinction with tags, up to 20 at a time. |
tag_not | JSON Array | Tag NOT | Array. Between multiple labels, the merged set of multiple labels is taken first, and then the complementary set is taken for that result. | Push up to 20 at a time 个。 |
alias | JSON Array | Alias | Array. Multiple aliases are OR relations, i.e., they take a concatenation. | Identify a user with an alias. |
registration_id | JSON Array | Sign up ID | Array. Multiple registration IDs are OR related to each other, i.e., they are taken as a concatenation. | Device identification. Push up to 1000 at a time. |
The implicit relationship between multiple values in an array is OR, i.e., taking the concatenation; however, tag_and is different in that the relationship between multiple values in an array is AND, i.e., taking the intersection.
tag_not cannot be used alone, at least one of the other 5 types is required. If the length of the value array is 0, the type does not exist.
These types can coexist. The implicit relationship between multiple polynomials when coexisting is AND, i.e., taking the intersection. For example:
"audience" : {"tag" : [ "tag1", "tag2"], "tag_and" : ["tag3", "tag4"], "tag_not" : ["tag5", "tag6"] }
Calculate the result of the "tag" field first tag1 or tag2 = A
;
Then calculate the result of the "tag_and" field tag3 and tag4 = B
;
Then calculate the result of the "tag_not" field not (tag5 or tag6) = C
;
The final result of "audience" is A and B and C
。
Example
- Push to all (broadcast):
{
"to": "all",
}
- Push to multiple tags (as long as they are met within any of the tags): in Shenzhen, Guangzhou, or Beijing
{
"to":{
"tag":[
"Shenzhen",
"Guangzhou",
"Beijing"
]
}
}
- Push to multiple tags (need to be in the range of multiple tags at the same time): in Shenzhen and "female"
{
"to":{
"tag_and":[
"Shenzhen",
"female"
]
}
}
- Push to multiple aliases:
{
"to":{
"alias":[
"4314",
"892",
"4531"
]
}
}
- Push to multiple registration IDs:
{
"to": {
"registration_id": [
"4312kjklfds2",
"8914afd2",
"45fdsa31"
]
}
}
- Can be pushed simultaneously to specify multiple types of push targets: in Shenzhen or Guangzhou and are "female" "members"
{
"to":{
"tag":[
"Shenzhen",
"Guangzhou"
],
"tag_and":[
"female",
"members"
]
}
}
body
Send request body. The supported fields are as follows:
Keyword | Type | Option | Meaning |
---|---|---|---|
platform | String or JSON Array | Required field | Push Platform |
notification | JSON Object | Optional | |
message | JSON Object | Optional | |
options | JSON Object | Optional | Push parameter |
platform
MTPush currently supports push for Android and iOS platforms. The keywords are: "android", "ios" respectively.
If the target platform is iOS, you need to set the push environment by apns_production field in options. true means push production environment, False means push development environment; if not specified, push production environment.
Push to all platforms:
{ "platform" : "all" }
Designation of specific push platforms:
{
"platform": [
"android",
"ios"
]
}
notification
The "Notification" object, which is one of the entity content objects of a push (the other is "Message"), is pushed to the client as a "Notification".
Keyword | Type | Option | Meaning | Description |
---|---|---|---|---|
alert | String or JSON Object | Required field | Content | The content of the message itself. If alert is not specified under android or ios, it will be used. |
android | JSON Object | Optional | android platform properties | Android platform push parameters, seeandroid description |
ios | JSON Object | Optional | ios platform properties | ios platform push parameters, seeios description |
alert
The "alert" property in this location (directly under the notification object) is a shortcut definition, and if the alert message is the same across platforms, the alert may not be defined under the platform, and this will prevail. If there is a definition for each platform, it will override the definition here.
{
"notification" : {
"alert" : "Hello, Push!"
}
}
The notification object defined above will be pushed to multiple platforms specified by "platform" and will all have the same notification alert message.
android
Notifications on the Android platform are displayed by the MTPush SDK in accordance with specific notification bar styles. The supported fields are as follows:
Keyword | Data Type | Optional | Meaning | Description |
---|---|---|---|---|
alert | String or JSON Object | Required | Notification Content | |
title | String | Optional | Notification Title | |
builder_id | Int | Optional | Notification Bar Style ID | The Android SDK can set custom notification layouts, and this field specifies which style to use. |
channel_id | String | Optional | Android Notification Channel ID | Up to 1000 bytes, starting from Android 8.0, you can configure Notification Channels. This field specifies the notification bar display effect based on the channel ID. |
priority | Int | Optional | Notification Bar Display Priority | Default is 0, with a range of -2 to 2. |
category | String | Optional | Notification Bar Entry Filtering or Sorting | This depends entirely on the manufacturer's handling strategy for the category. |
style | Int | Optional | Notification Bar Style Type | Used to specify the notification bar style type, default is 0. |
big_text | String | Optional | Big Text Notification Bar Style | |
inbox | JSONObject | Optional | Text Item Notification Bar Style | |
big_pic_path | String | Optional | Big Picture Notification Bar Style | |
extras | JSON Object | Optional | Extra Fields | Define custom Key/Value information in JSON format for business use. |
intent | JSON Object | Optional | Specify the Target Page for Navigation (Recommended) | Use the intent field to specify the target page to navigate to when the notification bar is clicked. It is recommended to fill in the intent field, otherwise clicking the notification may have no navigation action. This field supports three types:intent:#Intent;action=action path;component= package name /full activity name;end intent:#Intent;action=android.intent.action.MAIN;end (fixed address)scheme://test?key1=val1&key2=val2 |
large_icon | String | Optional | Large Notification Icon | |
small_icon | String | Optional | Small Notification Icon | |
sound | String | Optional | Sound | |
badge_add_num | Int | Optional | Set the Incremental Value for the Badge Number, to be added to the original badge number | |
badge_class | String | Optional | Application Entry Activity Class Corresponding to the Desktop Icon, e.g., "com.test.badge.MainActivity" | |
display_foreground | String | Optional | App in the foreground, whether notifications should be displayed |
{
"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 notifications on the iOS platform.
The notification content is sent by the MTPush agent to the Apple APNs server and is presented on the iOS device as a system notification.
The notification content meets the APNs specification and supports the following fields:
Keyword | Type | Option | Meaning | Description |
---|---|---|---|---|
alert | String or JSON Object | Required field | Notice content | |
sound | String or JSON Object | Optional | Notification sound | |
badge | Int or String | Optional | Apply corner markers | |
content-available | Boolean | Optional | Push to wake up | For details, please refer to: "content-available":true when pushing, it means it is Background Remote Notification, if it doesn't, it is normal Remote Notification:Background Remote Notification |
mutable-content | Boolean | Optional | Notification extension | Notification Service Extension feature added to iOS 10 to report the delivery status of each APNs message, using this feature requires the client to implement the Service Extension interfaceand use the mutable-content field on the server side to complete the setup. |
category | String | Optional | Only supported in iOS 8. Set the value of the "category" field in the APNs payload. | |
extras | JSON Object | Optional | Extended Fields | Here the Key/value information is customized for business use. |
thread-id | String | Optional | Notification group | The iOS remote notifications are grouped by this property, so that notifications from the same thread-id are grouped together. |
interruption-level | String | Optional | Notification of disruption levels for priority and delivery times | For iOS 15, the notification level can only be one of active,critical,passive,timeSensitive, refer to:UNNotificationInterruptionLevel。 |
iOS notifications for MTPush to be forwarded to APNs servers. Notification + Message length in MTPush is limited to 4000 bytes. MTPush uses utf-8 encoding when pushing, so one Chinese character occupies 3 bytes in length.
Example of server-side delivery:
{
"notification": {
"ios": {
"alert": "hello, Push!",
"sound": "sound.caf",
"badge": 1,
"extras": {
"news_id": 134,
"my_key": "a value"
}
}
}
}
Message received by the client:
{
"_j_msgid" = 813843507;
aps = {
alert = "hello,Push!";
badge = 1;
sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}
message
In-app messages. Also called: custom messages, pass-through messages.
- This part is not displayed on the notification bar, the MTPush SDK receives the message content and passes it to the App.
- iOS gets this part in a push in-app message channel (not APNS) with the app in the foreground.
The supported fields are as follows:
Keyword | Type | Option | Meaning |
---|---|---|---|
msg_content | String or JSON Object | Required field | |
Message content |
|
| title | String | Optional | Message Title | | content_type | String | Optional | Message content type | | extras | JSON Object | Optional | Optional parameters for JSON format |
Example:
{
"message": {
"msg_content": "Hi,Push",
"content_type": "text",
"title": "msg",
"extras": {
"key": "value"
}
}
}
options
Push options. The following options are currently included:
Keyword | Type | Option | Meaning | Description |
---|---|---|---|---|
time_to_live | Int or String | Optional | Off-line message retention time (seconds) | |
override_msg_id | Long | Optional | Message ID to override | If the current push is to overwrite a previous push, filling in the msg_id of the previous push here will have the effect of overwriting, i.e: |
apns_production | Boolean | Optional | APNs are production environments or not | This field is only valid for Notification for iOS, if not specified it is pushing the production environment. Note: The official MTPush API LIbrary (SDK) is set to push the "Development Environment" by default. |
apns_collapse_id | String | Optional | Update the identifier for iOS notifications | |
big_push_duration | Int | Optional | Fixed speed push duration (minutes) | |
multi_language | json object | Optional | Multi-language push settings | Push content multi-language adaptation settings, see detailsmulti_language Description. |
third_party_channel | JSON Object | Optional | Android vendor channel configuration information | Valid parameters only for users who have configured vendor channels, see detailsthird_party_channel Description. |
multi_language
This field is for the multi-language push feature of the EngageLab Push service. It allows you to send customized notification content to users in different languages. By specifying multiple languages along with their corresponding message content, titles, and iOS subtitles in the push request, you can send appropriate push notifications based on the user's language settings.
Request Parameters
Keyword | Type | Options | Meaning | Description |
---|---|---|---|---|
en | string | Optional | Language key | Corresponds to the user's language, see the appendix for key codes. |
content | string | Optional | Message content | Replaces the data in notification.android.alert, notification.ios.alert, notification.web.alert, and message.msg_content based on the user's language. |
title | string | Optional | Message title | Replaces the data in notification.android.title, notification.ios.alert, notification.web.title, and message.title based on the user's language. |
ios_subtitle | string | Optional | iOS subtitle | Replaces the data in notification.ios.alert based on the user's language. |
Request Example
HTTP Request Method: POST
Request URL: /v4/grouppush or /v4/push
Request Data Format: JSON
Request Example:
{
"options": {
"multi_language": {
"en": {
"content": "",
"title": "",
"ios_subtitle": ""
}
}
}
}
Request Example
Successful Response:
{
}
Failed Response:
{
"code": 400,
"data": "",
"message": "Error Message"
}
third_party_channel
This field is used to fill in the personalized information of the Android vendor channel, the key only supports 7 Android vendor channels, xiaomi, huawei, meizu, oppo, vivo, fcm, honor, one or more of them can exist at the same time, the KEY of each vendor type can currently contain the following options:
Note: In case of multiple keys, distribution_new takes the value of the vendor channel (xiaomi, huawei, meizu, oppo, vivo, honor) as the setting.
Request Parameter
Keyword | Type | Option | Meaning | Description |
---|---|---|---|---|
distribution_new | String | Required option | When Engagelab and vendor channels coexist, set the downlink priority. |
|
channel_id | String | Optional | Notification bar message categories | Support OPPO's private message、Xiaomi's notification message、Huawei News Categories category, the category ChannelID value should be requested by the developer from the vendor. |
classification | Int | Optional | Notification bar message categories | vivo phone manufacturer notification bar message category, unfilled default is 0. |
pushMode | Int | Optional | vivo push mode | Default is 0. For details, refer tovivo pushModeTo use test push, you need to manually configure the ID of the test device in the vivo backend. |
importance | String | Optional | Huawei/Glory notification bar message intelligent classification | In order to adapt to Huawei cell phone manufacturer's notification bar message intelligent classification, corresponding to Huawei's importance field, do not fill the default "NORMAL", reference: Huawei notification message intelligent classification。 |
urgency | String | Optional | Huawei vendor-defined message priority | To adapt the priority of Huawei phone vendor custom messages. |
category | String | Optional | Huawei vendor custom message scenario logo | In order to adapt Huawei cell phone vendor-defined messages to identify special scenarios of high-priority transmissions messages, or for identifying message types to speed up the delivery of specific types of messages, the corresponding values and their descriptions refer to:Category Value Description。 |
small_icon_uri | String | Optional | Small icon style for vendor messages | |
small_icon_color | String | Optional | Xiaomi manufacturer small icon style color | In order to adapt to the color of the small icon style of the Xiaomi manufacturer's message, do not fill the default is gray (Xiaomi official follow-up does not support custom small icons, developers are advised not to continue to use Xiaomi small icon-related features). |
big_text | String | Optional | Large text style for vendor messages | |
only_use_vendor_style | Boolean | Optional | Whether to use its own channel setting style | Whether to use only the style set in its own channel, not the style set in android, the 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
Request id, an optional field defined by the customer. Used by the client to identify which request is being made and returned on response.
Request Example
{
"request_id":"12345678"
}
Return Example
{
"msg_id": "1225764",
"request_id": "12345678"
}
custom_args
Customer-defined, optional field that is not returned on response and is returned on callback.
Request Example
{
"custom_args":"business info"
}
Return parameter
Successful return
Field | Type | Option | Description |
---|---|---|---|
request_id | String | Optional | The custom ID submitted on request is returned as is on response. |
message_id | String | Required | Message ID, which uniquely identifies a message. |
< HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id":"18","msg_id":"1828256757"}
Failure to return
The http status code is 4xx or 5xx and the response body contains the following fields:
Field | Type | Option | Description |
---|---|---|---|
code | int | Required | Error code, see [Error code](#Error code) Description |
message | String | Required | Error Details |
{
"code": 3002,
"message": "Push.template field must be set correctly when type is template"
}
Call returns
HTTP Status Code
Reference Document:HTTP-Status-Code
Error Code
Code | Descrption | Detailed explanation | HTTP Status Code |
---|---|---|---|
20101 | Invalid push parameter | registration_id is invalid or does not belong to the current appkey | 400 |
21001 | Only HTTP Post methods are supported | Get method is not supported | 405 |
21002 | Missing required parameters | Must be corrected | 400 |
21003 | Parameter value is not legal | Must be corrected | 400 |
21004 | Verification failure | Must be corrected, see: Call Verification for details | 401 |
21005 | Message body is too large | Must be corrected, Notification+Message length is limited to 2048 bytes | 400 |
21008 | app_key parameter is illegal | Must be corrected, please carefully compare the appkey you passed with the one in the application information, whether there are extra spaces | 400 |
21009 | Internal system errors | Must be corrected | 400 |
21011 | No push targets meet the conditions | Please check the to field | 400 |
21015 | Request parameter checksum failure | Presence of unintended parameters | 400 |
21016 | Request parameter checksum failure | The parameter type is wrong, or the parameter length exceeds the limit | 400 |
21030 | Internal service timeout | Try again later | 503 |
23006 | Parameter error | Fixed speed push big_push_duration over max 1440 | 400 |
23008 | Interface speed limit | Single application push interface qps reaches upper limit (500 qps) | 400 |
27000 | System memory error | Please try again | 500 |
27001 | Parameter error | Check information is empty | 401 |
27008 | Parameter error | The distribution in third_party_channel is not empty, but the alert of the notification is empty | 401 |
27009 | Parameter error | Invalid or empty distribution format in third_party_channel | 401 |
21038 | permission denied | VIP has expired or has not been activated | 401 |
Push Limit
Manufacturer Channel | Title Length | Content Length | sensitive words | Other notes |
---|---|---|---|---|
Engagelab Channel | No limit, but limit the total size of the message body | No limit, but limit the total size of the message body | - | The length of Notification + Message in MTPush is limited to 4000 bytes. |
Huawei Channel | < 40 characters | < < 1024 characters | Prohibit the carrying of government, leader names, Taiwan independence and other related content | The default [Marketing Notification] permission is Silent Notification, Silent Push has no sound, vibration and other alerts. |
Glory Channel | No limit, but total message body size <4096 bytes | No limit, but total message body size < 4096 bytes | Prohibit the carrying of government, leader names, Taiwan independence and other related content | - |
Phantom Channel | < 32 characters | < 100 characters | Prohibit special characters,such as: # | |
Xiaomi Channel | < 50 characters | < 128 characters | Prohibit special characters, such as: #, >> | |
OPPO Channel | < 32 characters | < 200 characters | No description yet | |
vivo Channel | < 40 characters | < 100 characters | ||
APNS Channel | < 20 characters (40 English characters) | No description yet | None |
Multi-language code
Language | Language Code |
---|---|
English | en |
Arabic | ar |
Chinese (Simplified) | zh-Hans |
Chinese (Traditional) | zh-Hant |
Czech | cs |
Danish | da |
Dutch | nl |
French | fr |
German | de |
Hindi | hi |
Italian | it |
Japanese | ja |
Korean | ko |
Malay | ms |
Russian | ru |
Spanish | es |
Turkish | th |
Vietnamese | vi |