create push API
Last updated:2023-03-02

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==
          > POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==

        
This code block in the floating window

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==
          {
    "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==

        
This code block in the floating window

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
  • The notification content body, which is the content that is pushed to the client.
  • One or the other must be present along with the message; the two cannot coexist.
  • message JSON Object Optional
  • The message content body, which is the content that is pushed to the client.
  • With notification, one or the other must be present, and the two cannot coexist.
  • 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" }
              {
        "from":"push"
    }
    
            
    This code block in the floating window

    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.
  • Push up to 20 at a time.
  • Valid tag composition: letters (case sensitive), numbers, underscores, Chinese characters.
  • Limit: The length of each tag is limited to 40 bytes. (UTF-8 encoding is required to determine the length)
  • 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.
  • A device can only be bound to one alias, but multiple devices can be bound to the same alias.
  • Push up to 1000 at a time.
  • Valid alias composition: letters (case sensitive), numbers, underscores, Chinese characters.
  • Limit: The length of each alias is limited to 40 bytes. (UTF-8 encoding is required to determine the length)
  • 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", }
              {
      "to": "all",
    }
    
            
    This code block in the floating window
    • 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" ] } }
              {
        "to":{
            "tag":[
                "Shenzhen",
                "Guangzhou",
                "Beijing"
            ]
        }
    }
    
            
    This code block in the floating window
    • 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" ] } }
              {
        "to":{
            "tag_and":[
                "Shenzhen",
                "female"
            ]
        }
    }
    
            
    This code block in the floating window
    • Push to multiple aliases:
    { "to":{ "alias":[ "4314", "892", "4531" ] } }
              {
        "to":{
            "alias":[
                "4314",
                "892",
                "4531"
            ]
        }
    }
    
            
    This code block in the floating window
    • Push to multiple registration IDs:
    { "to": { "registration_id": [ "4312kjklfds2", "8914afd2", "45fdsa31" ] } }
              {
      "to": {
        "registration_id": [
          "4312kjklfds2",
          "8914afd2",
          "45fdsa31"
        ]
      }
    }
    
            
    This code block in the floating window
    • 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" ] } }
              {
        "to":{
            "tag":[
                "Shenzhen",
                "Guangzhou"
            ],
            "tag_and":[
                "female",
                "members"
            ]
        }
    }
    
            
    This code block in the floating window

    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
  • The notification content body, which is the content that is pushed to the client.
  • 与 message Together, one of the two must exist, and the two cannot coexist.
  • message JSON Object Optional
  • The message content body, which is the content that is pushed to the client.
  • With notification, one or the other must be present, and the two cannot coexist.
  • 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" }
              { "platform" : "all" }
    
            
    This code block in the floating window

    Designation of specific push platforms:

    { "platform": [ "android", "ios" ] }
              {
      "platform": [
        "android",
        "ios"
      ]
    }
    
            
    This code block in the floating window

    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!" } }
              {
      "notification" : {
        "alert" : "Hello, Push!"
      }
    }
    
            
    This code block in the floating window

    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
  • If specified, it will override the alert information set at the parent level.
  • The content can be an empty string to indicate that it should not be displayed in the notification bar.
  • For limitations imposed by various push channels on this field, please refer to Push Limits.
  • title String Optional Notification Title
  • If specified, it will replace the app name in the notification display.
  • For limitations imposed by various push channels on this field, please refer to Push Limits.
  • 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
  • Available when style = 1, the content will be displayed in the notification bar as big text.
  • Supported on ROMs with API 16 or higher.
  • inbox JSONObject Optional Text Item Notification Bar Style
  • Available when style = 2, each key in the JSON corresponds to a value that will be displayed as a text item.
  • Supported on ROMs with API 16 or higher.
  • big_pic_path String Optional Big Picture Notification Bar Style
  • Available when style = 3, currently supports .jpg and .png format images.
  • Supported for network image URLs, local image paths (specify the relative path on the SD card).
  • Supported on ROMs with API 16 or higher.
  • 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:
  • Navigate to the target page: intent:#Intent;action=action path;component= package name /full activity name;end
  • Go to the app's home page: intent:#Intent;action=android.intent.action.MAIN;end (fixed address)
  • Navigate to a deeplink address: scheme://test?key1=val1&key2=val2
  • large_icon String Optional Large Notification Icon
  • Icon size should not exceed 300 KB.
  • Supported for network image URLs, local image paths (specify the relative path on the SD card).
  • small_icon String Optional Small Notification Icon
  • Notification small icon, the icon path can be a network image URL and should not exceed 300 KB in size.
  • If small_icon_uri is not populated, this small_icon field will be used by default.
  • sound String Optional Sound
  • Fill in the name of the sound file in the Android project's /res/raw/ path without the file name extension.
  • Note: For Android 8.0 and above, this attribute does not work when channel_id is passed.
  • badge_add_num Int Optional Set the Incremental Value for the Badge Number, to be added to the original badge number
  • This property currently only works for Huawei EMUI 8.0 and above, Xiaomi MIUI 6 and above, and vivo devices when using the manufacturer's channel.
  • If this field is not filled, it means the badge number will not change (for Xiaomi devices, regardless of whether the push goes through the Engagelab channel or the manufacturer's channel, it will default to +1).
  • Value range: 1-99. If a value within this range is set, the badge_add_num data for the next notification bar message configuration will be added to the original badge number. It is recommended to set it to 1.
  • Example: If badge_add_num is set to 1 and the original badge number is 2, after sending this badge message, the application badge number will be displayed as 3.
  • badge_class String Optional Application Entry Activity Class Corresponding to the Desktop Icon, e.g., "com.test.badge.MainActivity"
  • Effective only for Huawei channel push. If this value is filled with a non-main Activity class, the manufacturer's restriction logic will apply.
  • If you need to implement badge incrementing functionality, you need to use badge_add_num in conjunction with it; both must coexist, and missing either one is not allowed.
  • display_foreground String Optional App in the foreground, whether notifications should be displayed
  • When the value is "1," notifications will pop up in the notification bar when the app is in the foreground.
  • When the value is "0," notifications will not pop up in the notification bar when the app is in the foreground.
  • Note: By default, notifications will pop up in the notification bar when the app is in the foreground. This has been supported since MTPush Android SDK version 4.3.1.
  • { "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" } } } }
              {
        "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"
                }
            }
        }
    }
    
            
    This code block in the floating window

    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
  • The content specified here will override the alert message specified by the parent.
  • If the content is empty, it is not displayed in the notification bar.
  • The string form is supported as well as the officially defined alert payload
  • structure, which contains the officially supported keys such as title and subtitle.
  • sound String or JSON Object Optional Notification sound
  • General notification: String type.
  • If this field is not present, there is no audible alert for this message;
  • With this field, the specified sound is played if it is found, otherwise the default sound is played.
  • If this field is an empty string, iOS 7 is the default sound, iOS 8 and above is no sound.
  • Alert notification: JSON Object , which supports an officially defined payload structure containing officially supported keys such as critical, name and volume.
  • badge Int or String Optional Apply corner markers
  • The value of N can be set to N, +N, or -N, and the value of N is in the range [0,99]. If the uploaded corner value is 10, it means that the corner will be set to N, 10+N, 10-N (the corner is cleared by default if the value is less than 0).
  • Is 0 or the empty string, it means clear the corner.
  • If not filled in, it means that the corner numbers are not changed.
  • The MTPush Official API Library (SDK) will fill the badge value to "+1" by default.
  • 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.
  • true: Indicates support for the UNNotificationServiceExtension feature of iOS 10.
  • If this field is not carried, it is a normal Remote Notification and no arrival data can be counted.
  • 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" } } } }
              {
        "notification": {
            "ios": {
                "alert": "hello, Push!",
                "sound": "sound.caf",
                "badge": 1,
                "extras": {
                    "news_id": 134,
                    "my_key": "a value"
                }
            }
        }
    }
    
            
    This code block in the floating window

    Message received by the client:

    { "_j_msgid" = 813843507; aps = { alert = "hello,Push!"; badge = 1; sound = "sound.caf"; }; "my_key" = "a value"; "news_id" = 134; }
              {
      "_j_msgid" = 813843507;
      aps =     {
      alert = "hello,Push!";
      badge = 1;
      sound = "sound.caf";
    };
    "my_key" = "a value";
    "news_id" = 134;
    }
    
            
    This code block in the floating window

    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
    |
                  |
    
            
    This code block in the floating window

    | 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" } } }
              {
      "message": {
        "msg_content": "Hi,Push",
        "content_type": "text",
        "title": "msg",
        "extras": {
          "key": "value"
        }
      }
    }
    
            
    This code block in the floating window

    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)
  • If the user is not online at the time of the push, offline messages can be reserved for that user for a specified length of time so that they can be pushed again when they come online.
  • Default 86400 (1 day), maximum 15 days, if the maximum value supported by the vendor < the transmitted valid value, then the vendor maximum value prevails.
  • A setting of 0 means that offline messages are not kept and only users whose tweets are currently online can receive them.
  • 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:
  • The msg_id received offline is the overwritten content, even if the msg_id has been received by the Android-side user, the new message content will overwrite the previous notification if the notification bar has not been cleared.
  • If the msg_id does not exist within the specified override time frame, a 7006 error is returned, indicating that it is not a valid message override and the current message will not be pushed.
  • This field is valid only for Android Only Engagelab channel, Xiaomi channel, Meizu channel, OPPO channel, FCM channel, Huawei channel (EMUI10 and above devices) are supported.
  • 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.
  • true: Indicates that the production environment is pushed.
  • false: indicates that the development environment is pushed.
  • apns_collapse_id String Optional Update the identifier for iOS notifications
  • APNs new notifications that match a notification with the same apns-collapse-id field in the current notification center will update it with the new notification content and place it first in the notification center.
  • The collapse id must not exceed 64 bytes in length.
  • big_push_duration Int Optional Fixed speed push duration (minutes)
  • Also known as slow push, takes the original push speed, which was as fast as possible, and slows it down to push evenly to the target user of this push within a given n minutes; the maximum value is 1440.
  • 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": "" } } } }
                 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": ""
            }
          }
        }
       }
    
            
    This code block in the floating window
    Request Example
    Successful Response: { }
              Successful Response:
    {
       
    }
    
            
    This code block in the floating window
    Failed Response: { "code": 400, "data": "", "message": "Error Message" }
              
    Failed Response:
    {   
        "code": 400,  
        "data": "",
      "message": "Error Message"
    }   
    
            
    This code block in the floating window

    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.
  • mtpush: indicates that the push is forced to go down the Engagelab channel.
  • pns_mtpush: indicates that for fcm+ domestic manufacturer combination type users, the push is forced to go Xiaomi / Huawei / Meizu / oppo / Vivo / Glory channel first, and then invalid to go engagelab channel.
  • mtpush_pns: indicates that for fcm+ domestic vendor combination type users, push priority to go engagelab, engagelab is not online and then go to the vendor channel, the vendor as a secondary.
  • fcm_mtpush: indicates that for fcm+ domestic vendor combination type users, the push is forced to take the fcm channel first and then take the engagelab channel if it is invalid.
  • mtpush_fcm: indicates that for fcm+ domestic vendor combination type users, push priority goes to engagelab, engagelab is not online and then go to fcm channel, fcm as a secondary. ``Note: For the four strategies pns_mtpush/fcm_mtpush/mtpush_pns/mtpush_fcm, if there is only one system push channel available for the device (FCM or phone vendor), the mandatory priority will be ignored and the integrated successful system channel will be taken.
  • channel_id String Optional Notification bar message categories Support OPPO's private messageXiaomi's notification messageHuawei 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.
  • 0: represents the operation message.
  • 1: Represents system messages. ``At present, vivo is more strict in classifying system messages, refer to: vivo developer platform for specific rules.
  • 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.
  • 0: Indicates an official push.
  • 1:1: Indicates a test push.
  • 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
  • LOW: General message.
  • NORMAL: Important message.
  • HIGH: Very important message (supported by Huawei only)
  • urgency String Optional Huawei vendor-defined message priority To adapt the priority of Huawei phone vendor custom messages.
  • HIGH: Very important messages, HIGH level messages can be forced to pull up the application process when they reach the user's phone.
  • NORMAL: Important message. ``To set "HIGH", you need to apply for special permission from Huawei, refer to:How to apply for special permission
  • 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
  • Currently supports Xiaomi / Huawei manufacturers.
  • Preferred vendor field, vendor field is not populated, use small_icon within android 字段。
  • Xiaomi Support Xiaomi manufacturer's large icon idThe media_id and vendor local path for Huawei, Engagelab support.(Xiaomi officially no longer supports custom small icons, developers are advised not to continue to use Xiaomi small Icon related features).
  • 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
  • In order to adapt to the manufacturer's message large text style, currently supports Huawei / Honor / Xiaomi / OPPO, where Xiaomi OPPO supports up to 128 characters.
  • If the vendor field is not populated, the big_text field is defined in android.
  • Used when the field style=1 inside android.
  • 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,
  • true: only use the style set by its own channel.
  • false: you can use the style set in android.
  • 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 } }
              "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
        }
    }
    
            
    This code block in the floating window

    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" }
              {
          "request_id":"12345678"
    }
    
            
    This code block in the floating window

    Return Example

    { "msg_id": "1225764", "request_id": "12345678" }
              {
        "msg_id": "1225764",
        "request_id": "12345678"
    }
    
            
    This code block in the floating window

    custom_args

    Customer-defined, optional field that is not returned on response and is returned on callback.

    Request Example

    { "custom_args":"business info" }
              {
      "custom_args":"business info"
    }
    
            
    This code block in the floating window

    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"}
              < HTTP/1.1 200 OK
    < Content-Type: application/json
    {"request_id":"18","msg_id":"1828256757"}
    
            
    This code block in the floating window

    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" }
              {
        "code": 3002,
        "message": "Push.template field must be set correctly when type is template"
    }
    
            
    This code block in the floating window

    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: #
  • Both Chinese and English characters are counted as 1 character.
  • Some of the messages may be stored in the [Meizu Message Box] in the upper right corner of your Meizu phone.
  • Xiaomi Channel < 50 characters < 128 characters Prohibit special characters, such as: #, >>
  • Both Chinese and English characters are counted as 1 character.
  • Some messages may be present in unimportant notifications in the notification bar.
  • OPPO Channel < 32 characters < 200 characters No description yet
  • Both Chinese and English characters are counted as 1 character.
  • Turn off notification permissions by default.
  • vivo Channel < 40 characters < 100 characters
  • Prohibit special characters, such as: #, >>
  • Formal messages are prohibited: plain numbers, plain English, plain symbols, symbols plus numbers, test, test, curly brackets, middle brackets, etc.
  • English is 1 character, Chinese is 2 characters.
  • Turn off notification permissions by default.
  • The number of operational messages pushed from the same device in 1 day cannot exceed 5.
  • You cannot push the same operational message with the same content within 1 day from the same device.
  • APNS Channel < 20 characters (40 English characters)
  • Notification center and lock screen status display up to 110 characters and 55 Chinese characters.
  • The top popup window displays up to 62 characters and 31 Chinese characters, beyond which an ellipsis is displayed.
  • 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
    在文档中心打开