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.

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

        

Call validation

For more information, see the REST API overview of Authentication Method description。

Request Example

Request Header

          > POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==

        

Request Body

          {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "all",
        "notification": {
            "alert" :"Hello, Push!",
            "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:

from

Current service sender, String type, optional field.

Request Example

          {
    "from":"push"
}

        

to

Push Device Object, which indicates the list of devices to which a push can be pushed. To confirm the push device object, App Push provides various ways, such as: alias, tag, registration ID, subgroup, broadcast, etc.

Push Target

There are several ways to choose equipment outside of broadcasting, as follows:

Example

• Push to all (broadcast):

          {
  "to": "all",
}

        

• Push to multiple tags (as long as they are met within any of the tags): in Shenzhen, Guangzhou, or Beijing

          {
    "to":{
        "tag":[
            "Shenzhen",
            "Guangzhou",
            "Beijing"
        ]
    }
}

        

• Push to multiple tags (need to be in the range of multiple tags at the same time): in Shenzhen and "female"

          {
    "to":{
        "tag_and":[
            "Shenzhen",
            "female"
        ]
    }
}

        

• Push to multiple aliases:

          {
    "to":{
        "alias":[
            "4314",
            "892",
            "4531"
        ]
    }
}

        

• Push to multiple registration IDs:

          {
  "to": {
    "registration_id": [
      "4312kjklfds2",
      "8914afd2",
      "45fdsa31"
    ]
  }
}

        

• Can be pushed simultaneously to specify multiple types of push targets: in Shenzhen or Guangzhou and are "female" "members"

          {
    "to":{
        "tag":[
            "Shenzhen",
            "Guangzhou"
        ],
        "tag_and":[
            "female",
            "members"
        ]
    }
}

        

• Push a live activity message

            {
      "to": {
          "live_activity_id": "LiveActivity-1"
      }
  }

        

Body

Send request body. The supported fields are as follows:

Platform

MTPush currently supports push for Android and iOS platforms. The keywords are: "android", "ios" respectively.

Push to all platforms:

          { "platform" : "all" }

        

Designation of specific push platforms:

          {
  "platform": [
    "android",
    "ios"
  ]
}

        

Notification

The "Notification" object, which is one of the entity content objects of a push (the other is "Message"), is pushed to the client as a "Notification".

Alert

The "alert" property in this location (directly under the notification object) is a shortcut definition, and if the alert message is the same across platforms, the alert may not be defined under the platform, and this will prevail. If there is a definition for each platform, it will override the definition here.

          {
  "notification" : {
    "alert" : "Hello, Push!"
  }
}

        

The notification object defined above will be pushed to multiple platforms specified by "platform" and will all have the same notification alert message.

Android

Notifications on the Android platform are displayed by the MTPush SDK in accordance with specific notification bar styles. The supported fields are as follows:

          {
    "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://pushapi-sgp.engagelab.comlargeIcon.jpg",
            "small_icon": "http://www.small.com/small_icon.jpg",
            "intent": {
                "url": "intent:#Intent;component=push.pushapi-sgp.engagelab.com/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:

Example of server-side delivery:

          {
    "notification": {
        "ios": {
            "alert": "hello, Push!",
            "sound": "sound.caf",
            "badge": 1,
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

        

Message received by the client:

          {
  "_j_msgid" = 813843507;
  aps =     {
  alert = "hello,Push!";
  badge = 1;
  sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}

        

Message

In-app messages. Also called: custom messages, pass-through messages.

• This part is not displayed on the notification bar, the MTPush SDK receives the message content and passes it to the App.
• iOS gets this part in a push in-app message channel (not APNS) with the app in the foreground.

The supported fields are as follows:

Example:

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

iOS JSON Object

iOS alert JSON Object

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

  This code block in the floating window

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

  This code block in the floating window

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

        

Options

The current push notification options include the following:

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

Request Example

             HTTP Request Method: POST
   Request URL: /v4/grouppush or /v4/push
   Request Data Format: JSON
   Request Example:
   {
    "options": {
      "multi_language": {
        "en": {
          "content": "",
          "title": "",
          "ios_subtitle": ""
        }
      }
    }
   }

        

Request Example

          Successful Response:
{
   
}

        

          
Failed Response:
{   
    "code": 400,  
    "data": "",
  "message": "Error Message"
}   

        

Third_party_channel

This field is used to fill in the personalized information of the Android vendor channel, the key only supports 7 Android vendor channels, xiaomi, huawei, meizu, oppo, vivo, fcm, honor, one or more of them can exist at the same time, the KEY of each vendor type can currently contain the following options:

Request Parameter

To unify multi-vendor channel strategies and simplify configuration logic, the configuration method for the distribution_new field is adjusted as follows. Your legacy vendor-level configurations will remain effective, but it is recommended to gradually migrate to global configurations to avoid future compatibility risks. (New rules will take effect from 2025.04.03):

• Configuration Priority (New Rules)
  • First Priority: Global configuration third_party_channel.distribution_new (Recommended new method)
    Example: "distribution_new": "pns_mtpush"
  • Second Priority: Vendor-level configuration third_party_channel.{vendor_key}.distribution_new (Legacy compatible method)
    Only takes effect when global configuration is not set
  • No Configuration: default strategy: pns_mtpush

Request Example

          {
    "third_party_channel": {
        "distribution_new": "pns_mtpush",
        "xiaomi": {
            "channel_id": "*******",
            "small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png",
            "small_icon_color": "#ABCDEF"
        },
        "huawei": {
            "importance": "NORMAL",
            "small_icon_uri": "https://xx.com/xx.jpg",
            "only_use_vendor_style": true
        },
        "oppo": {
            "channel_id": "*******",
            "large_icon": "3653918_5f92b5739ae676f5745bcbf4"
        },
        "vivo": {
            "pushMode": 0
        }
    }
}

        

Request_id

Request id, an optional field defined by the customer. Used by the client to identify which request is being made and returned on response.

Request Example

          {
      "request_id":"12345678"
}

        

Return Example

          {
    "msg_id": "1225764",
    "request_id": "12345678"
}

        

Custom_args

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

Request Example

          {
  "custom_args":{
    "args1": "args1"
  }
}

        

Return parameter

Successful return

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

          {
    "error":{
    "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

Push Limit

Multi-language code