Create push API

最新の更新:2024-04-16

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 Rate Limits

Our API imposes limits on the call frequency to ensure the stability and fairness of the service. The QPS (Queries Per Second) limits for each AppKey are as follows:

  • Standard Limit: A maximum of 500 requests per second.
  • Advanced Limit: If you are a subscriber to our paid plan and your paid AppKey requires a higher QPS limit, please contact our business team: Sales@engagelab.com.

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.

POST v4/push
          
POST 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==

        
このコードブロックは、フローティングウィンドウに表示されます

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":{ "Engagelab": "push to you" } }' > 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":{
             "Engagelab": "push to you"
    }
}'
> 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
  • 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. The value contains a maximum of 128 characters.

    from

    Current service sender, String type, optional field.

    Request Example

    { "from":"push" }
              {
        "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 365 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.
    live_activity_id String Real-time Activity Identifier Corresponding to the value of liveActivityId in the iOS SDK. Must be provided when updating real-time activity.

    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:

    "to" : {"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 "to" is A and B and C


    Example

    • Push to all (broadcast):
    { "to": "all", }
              {
      "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" ] } }
              {
        "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" ] } }
              {
        "to":{
            "tag_and":[
                "Shenzhen",
                "female"
            ]
        }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます
    • Push to multiple aliases:
    { "to":{ "alias":[ "4314", "892", "4531" ] } }
              {
        "to":{
            "alias":[
                "4314",
                "892",
                "4531"
            ]
        }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます
    • Push to multiple registration IDs:
    { "to": { "registration_id": [ "4312kjklfds2", "8914afd2", "45fdsa31" ] } }
              {
      "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" ] } }
              {
        "to":{
            "tag":[
                "Shenzhen",
                "Guangzhou"
            ],
            "tag_and":[
                "female",
                "members"
            ]
        }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます
    • Push a live activity message
    { "to": { "live_activity_id": "LiveActivity-1" } }
                {
          "to": {
              "live_activity_id": "LiveActivity-1"
          }
      }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    Body

    Send request body. The supported fields are as follows:

    Keyword Type Options Meaning
    platform String or JSON Array Required Push platform
    notification JSON Object Optional
  • Notification content, which is the content pushed to the client.
  • Must exist along with message, and the two cannot coexist.
  • message JSON Object Optional
  • Message content, which is the content pushed to the client.
  • Must exist along with notification, and the two cannot coexist.
  • live_activity JSON Object Optional
  • Live activity message content, which is the content pushed to the client.
  • Must exist along with notification or message, and live_activity cannot coexist with notification or message.
  • options JSON Object Optional Push parameters

    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 dev environment, False means push development environment; if not specified, push production environment.

    Push to all platforms:

    { "platform" : "all" }
              { "platform" : "all" }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    Designation of specific push platforms:

    { "platform": [ "android", "ios" ] }
              {
      "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, see android description
    ios JSON Object Optional ios platform properties ios platform push parameters, see ios 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!"
      }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    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 Limit.
  • 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 JPEG (FCM channel only), .BMP (FCM channel only) .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.
  • The maximum size for images is 1MB.
  • 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"
                }
            }
        }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    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"
                }
            }
        }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    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;
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    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" } } }
              {
      "message": {
        "msg_content": "Hi,Push",
        "content_type": "text",
        "title": "msg",
        "extras": {
          "key": "value"
        }
      }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    live_activity

    Note: Real-time activity messages require the use of an iOS P8 certificate, which corresponds to selecting "Token Authentication Configuration" in WebPortal's iOS authentication method settings.

    Real-time activity message content body includes the following field information:

    Keyword Type Options Description
    ios JSON Object Required For detailed fields, refer to the section iOS JSON Object.

    iOS JSON Object

    Keyword Type Options Description
    event string Required Creation: "start", Update: "update", End: "end"; required when event=start
    attributes-type string Optional Real-time activity type, a value defined by the developer; mandatory when event=start
    content-state JSON Object Required Real-time activity dynamic content, must match the client SDK value (corresponds to Apple's content-state field).
    alert JSON Object Optional Refer to iOS alert JSON Object for details.
    dismissal-date int Optional Display time for the end of real-time activity.
    attributes JSON Object Optional Real-time activity static content, must match the client SDK value (corresponds to Apple's attributes field).
    stale-date int Optional Expiry time for displaying the real-time activity; if less than the current time, the activity will not update.
    relevance-score int Optional Priority of displaying the real-time activity on the Island of Intelligence, values from 1 to 100, positively correlated with the importance of the activity; default highest if not specified.
    apns-priority int Optional 5 or 10, default is 10; notifications with apns-priority=5 won't consume Apple's rate limit, exceeding the limit will restrict notifications.

    iOS alert JSON Object

    Keyword Type Options Description
    title string Optional Title displayed on Apple Watch messages.
    body string Optional Content shown on Apple Watch messages.
    sound string Optional Notification sound.
    • iOS real-time activity messages for Engagelab Push are forwarded to Apple servers. Apple requires that dynamic update data for real-time activity messages (ActivityKit) not exceed 4096 bytes.
    • Engagelab Push, due to repackaging requirements and considering security redundancy, stipulates that the total length within "live_activity" parameters for "iOS": { } and the contents inside the braces should not exceed 3584 bytes. JPush uses UTF-8 encoding, meaning one Chinese character occupies 3 bytes.

    Real-time Activity Push Example

    The attributes-type and live_activity_id used for real-time activities are reported from the developer SDK. Before using real-time activities, device push-to-start token and update-token must be reported. For detailed procedures, refer to the Apple manufacturer's real-time activity instructions.

    • Creat

      { "from": "push", "to": { "registration_id": [ "161a3797c816b134042" ] }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "start", "content-state": { "eventStr": "hello", "eventTime":1685952000 }, "attributes": { "name": "1", "number": 2, "tag": "mytag" }, "alert": { "title": "hello", "body": "welcome" }, "attributes-type": "my_la_type", "relevance-score": 100, "apns-priority": 100 } } }, "request_id": "12345678", "custom_args": "12345678" }
                {
          "from": "push",
         "to": {
              "registration_id": [
                  "161a3797c816b134042"
              ]
          },
          "body": {
              "platform": "ios",
              "live_activity": {
                  "ios": {
                      "event": "start",
                      "content-state": {
                          "eventStr": "hello",
                          "eventTime":1685952000
                      },
                      "attributes": {
                          "name": "1",
                          "number": 2,
                          "tag": "mytag"
                      },
                      "alert": {
                          "title": "hello",
                          "body": "welcome"
                      },
                      "attributes-type": "my_la_type",
                      "relevance-score": 100,
                      "apns-priority": 100
                  }
              }
          },
          "request_id": "12345678",
          "custom_args": "12345678"
      }
      
              
      このコードブロックは、フローティングウィンドウに表示されます
    • Update

      { "from": "push", "to": { "live_activity_id": "my_la_id" }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "update", "content-state": { "eventStr": "test_live", "eventTime": 198 }, "alert": { "title": "123411", "body": "123411" } } } }, "request_id": "12345678", "custom_args": "12345678" }
                {
         "from": "push",
         "to": {
               "live_activity_id": "my_la_id"
          },
          "body": {
              "platform": "ios",
              "live_activity": {
                  "ios": {
                      "event": "update",
                      "content-state": {
                          "eventStr": "test_live",
                          "eventTime": 198
                      },
      
                      "alert": {
                          "title": "123411",
                          "body": "123411"
                      }
                  }
              }
          },
          "request_id": "12345678",
          "custom_args": "12345678"
      }
      
              
      このコードブロックは、フローティングウィンドウに表示されます

    voip

    iOS VOIP function. This type does not support coexistence with other iOS message types. Refer to the request parameter structure:

    { "from": "push", "to": { "registration_id": [ "1a0018970a91da03de5" ] }, "request_id": "12345", "custom_args": "12345", "body": { "platform": "ios", "voip": { "key": "value // Any custom key/value pair that will be passed to the APP" } } }
              { 
        "from": "push", 
        "to": { 
            "registration_id": [ "1a0018970a91da03de5" ] 
        }, 
        "request_id": "12345", 
        "custom_args": "12345", 
        "body": { 
            "platform": "ios", 
            "voip": { 
                "key": "value // Any custom key/value pair that will be passed to the APP" 
            } 
        } 
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    Options

    The current push notification options include the following:

    Keyword Type Option Meaning Description
    time_to_live Int or String Optional Offline message retention time (seconds) If the user is offline at the time of the push, the message can be retained for a specified duration to be pushed again when they come online. Default is 86400 (1 day), maximum is 15 days. If the maximum supported by the carrier is less than the set value, the carrier's maximum is used. Setting to 0 means offline messages are not retained; only users who are online at the time of push will receive the message.
    override_msg_id Long Optional Message ID to override If the current push is meant to override a previous one, entering the previous push's msg_id will have the effect of overriding it. In this case, the msg_id will receive the updated content offline, even if the Android user has already received the message and if the notification has not been cleared from the notification bar, the new content will overwrite the previous notification. The overriding function is effective for: 1 day. If the msg_id does not exist within the specified time limit for override, a 7006 error is returned indicating an invalid message override operation, and the current message will not be pushed. This field is only effective for Android and only supports Engagelab channel, Xiaomi channel, Meizu channel, OPPO channel, FCM channel, and Huawei channel (EMUI10 and above devices).
    apns_production Boolean Optional APNs production environment This field is only valid for iOS Notifications. If not specified, it defaults to the development environment. Note: MTPush official API Library (SDK) defaults to the "development environment". true: Indicates pushing to the production environment. false: Indicates pushing to the development environment.
    apns_collapse_id String Optional Identifier to update iOS notifications If a new APNs notification matches an existing notification in the Notification Center with the same apns-collapse-id, the new notification content will update it and place it at the top of the Notification Center. The collapse id must not exceed 64 bytes in length.
    big_push_duration Int Optional Duration for paced pushing (minutes) Also known as slow pushing, it reduces the original fast pushing speed, distributing the push evenly to the target users over the specified n minutes; the maximum is 1440.
    multi_language json object Optional Multilingual push settings Adaptation settings for multilingual push content, see multi_language for details.
    third_party_channel JSON Object Optional Android manufacturer channel configuration information Parameters valid only for users configured with manufacturer channels, see third_party_channel for details.
    classification Int Optional Push message classification setting EngageLab does not judge or calibrate the specified message type. If not specified, defaults to 0. 0: Represents operational messages. 1: Represents system messages.
    voice_value String Optional Voice file value Multiple parameters are separated by commas, with '#' indicating the need for parsing; otherwise, it directly matches the language file by default. Note that if the number has a decimal point, the uploaded file name must be point.mp3. Supported languages currently include "en" (English), "zh-Hans" (Simplified Chinese), and "zh-Hant" (Traditional Chinese). If the specified language of the push content does not match the corresponding language rules, then the push content will not be converted into voice broadcast.
    enhanc_message Bool Optional Enable in-app message display true - enable enhancement; false - disable enhancement. If notification permissions are disabled, enabling this feature will display the notification bar message content as an in-app message when the user is running the app in the foreground. The default value for this feature is false and it will only be active when explicitly enabled.

    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": ""
            }
          }
        }
       }
    
            
    このコードブロックは、フローティングウィンドウに表示されます
    Request Example
    Successful Response: { }
              Successful Response:
    {
       
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます
    Failed Response: { "code": 400, "data": "", "message": "Error Message" }
              
    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.
  • 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", "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",
            "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" }
              {
          "request_id":"12345678"
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    Return Example

    { "msg_id": "1225764", "request_id": "12345678" }
              {
        "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":{ "args1": "args1" } }
              {
      "custom_args":{
        "args1": "args1"
      }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    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"}
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    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"
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    Call returns

    HTTP Status Code

    Reference Document:HTTP-Status-Code

    Error Code

    Code Description Detailed Explanation HTTP Status Code
    20101 Invalid push parameters Registration ID is invalid or does not belong to the current appkey 400
    21001 Only supports HTTP Post method Does not support the Get method 405
    21002 Required parameter missing Must be corrected 400
    21003 Invalid parameter value Must be corrected 400
    21004 Verification failed Must be corrected, see: Call for verification 401
    21005 Message body too large Must be corrected, Notification+Message length limit is 2048 bytes 400
    21008 Invalid app_key parameter Must be corrected, carefully compare the transmitted appkey with the application information, check for extra spaces 400
    21009 Internal system error Must be corrected 400
    21011 No suitable push target found Check the 'to' field 400
    21015 Request parameter validation failed Unexpected parameters present 400
    21016 Request parameter validation failed Parameter type error, or parameter length exceeds limit 400
    21030 Internal service timeout Retry later 503
    21050 Incorrect live_activity event parameter Event parameter must be "start", "update", or "end" 400
    21051 Incorrect live_activity audience parameter During live activity creation, push target can only be broadcast or registration-based 400
    21052 Incorrect live_activity attributes-type parameter When event=start, attributes-type cannot be empty 400
    21053 Incorrect live_activity content-state parameter Content-state cannot be empty 400
    21054 live_activity parameter error, notification and custom message not allowed simultaneously voip, message, notification, live_activity cannot coexist 400
    21055 live_activity ios non-p8 certificate Live activity only supports p8 certificate 400
    21056 live_activity only supports ios platform platform parameter must be ios 400
    21057 voip message not allowed to coexist with other message types voip, message, notification, live_activity cannot coexist 400
    21058 voip only supports ios platform platform parameter must be ios 400
    23006 Parameter error Fixed-rate push big_push_duration exceeds maximum value of 1440 400
    23008 Interface rate limited Single application push interface QPS reaches limit (500 qps) 400
    23009 Push permission error Current push IP address not in the application IP whitelist 400
    27000 Internal memory error Please retry 500
    27001 Parameter error Verification information is empty 401
    27008 Parameter error Distribution inside third_party_channel is not empty, but notification's alert content is empty 401
    27009 Parameter error Invalid or empty format for distribution in third_party_channel 401
    21038 Push permission error VIP expired or not activated 401
    21306 Parameter error Notification messages and custom messages cannot be pushed simultaneously 401
    21059 Parameter error This message type does not support big_push_duration 401

    Push Limit

    Manufacturer Channel Title Length Content Length Sensitive Words Other Notes
    Engagelab Channel < 50 characters No limit, but limit the total size of the message body to 4000 bytes - The length of Notification + Message in MTPush is limited to 4000 bytes.
    Huawei Channel < 40 characters < 1024 characters Prohibit content related to government, leaders, Taiwan independence, etc. The default [Marketing Notification] permission is Silent Notification; Silent Push has no sound, vibration, or other alerts.
    Glory Channel No limit, but total message body size < 4096 bytes No limit, but total message body size < 4096 bytes Prohibit content related to government, leaders, Taiwan independence, etc. -
    Phantom Channel < 32 characters < 100 characters Prohibit special characters, such as "#" Messages may be stored in the [Meizu Message Box] in the upper right corner of Meizu phones. Both Chinese and English characters are counted as 1 character.
    Xiaomi Channel < 50 characters < 128 characters Prohibit special characters, such as "#", ">>" Messages may appear in unimportant notifications in the notification bar. Both Chinese and English characters are counted as 1 character.
    OPPO Channel < 32 characters < 200 characters No description yet Notification permissions are turned off by default. Both Chinese and English characters are counted as 1 character.
    vivo Channel < 40 characters < 100 characters Prohibit special characters and formal messages, such as plain numbers, plain English, etc. English characters count as 1, Chinese as 2. Notification permissions are turned off by default. The number of operational messages from the same device is capped at 5 per day. Identical operational messages cannot be pushed from the same device on the same day.
    APNS Channel < 20 characters (40 English characters) Notification center and lock screen display up to 110 characters (55 Chinese characters). Top popup displays up to 62 characters (31 Chinese characters), with an ellipsis for longer messages. No description yet No description yet

    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
    Thai th
    Vietnamese vi
    Indonesian id
    Norwegian no
    Swedish sv
    Polish pl
    Turkish tr
    Hebrew he
    Portuguese pt
    Romanian ro
    Hungarian hu
    Finnish fi
    Greek el
    在文档中心打开
    icon
    営業に連絡する