Push API v4

最新の更新:2023-03-02
  • Push a notification or message to a single device or a device list

  • The push content can only be one push object in JSON format

  • For label/alias related functions, please refer to AppPushAPI.

This is the latest version of Push API. The improvement of the v4 version is as follows:

  • Use HTTP Basic Authentication to authorize access. In this way, the entire API request can be completed using common HTTP tools, such as curl and browser plug-ins
  • The push content is 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.

Call Validation

For more information, see Authentication method

Call Address

POST v4/push
          POST v4/push

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

Sample Requests

Request header

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

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

Request body

{ "from": "push", "to": "all", "body": { "platform": "web", "notification": { "alert": "Hi,MTPush !",//optional "web": { "alert": "web_push", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } } }, "request_id": "12345678", "custom_args": "business info" }
          {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",//optional
            "web": {
                "alert": "web_push",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        }
    },
    "request_id": "12345678",
    "custom_args": "business info"
}

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

Request Parameters

The parameter structure of the push, as detailed in the following table.

Keyword Type Option Description
from String Optional Current business sender
to String 或 JSON Object Required Send target
body JSON Object Required Send request body
platform String or JSON Array Required Push platform
notification JSON Object Optional
  • The notification body, which is the content pushed to the client.
  • Together with message, they must have one, and they cannot coexist.
  • message JSON Object Optional
  • The message body, which is the content pushed to the client.
  • Together with notification, they must have one, and they cannot coexist.
  • options JSON Object Optional Push parameters
    request_id String Optional A custom optional field that is used by the customer to identify the request and is returned upon response.
    custom_args JSON Object Optional Optional fields customized by the customer, which are returned to the customer during callback.

    from

    The sender of the current business. The value is of the String type and is optional.

    Sample Requests

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

    to

    Push device object, which indicates the list of devices to which a push can be pushed. Confirm the push device object. MTPush provides two methods: Registration ID and broadcast.

    Push target

    Keyword Type Meaning Description Note
    all String Broadcast Push all devices Push the target devices that have been active within 30 days.
    registration_id JSON Array Registration ID Array. The relationship between multiple registration IDs is OR, that is, the Union. The device ID. A maximum of 1,000 messages can be pushed at a time.
    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)

  • 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


    Sample Requests

    • Push to all (broadcast):
    { "to": "all", }
              {
      "to": "all",
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます
    • Push to multiple registration IDs:
    { "to": { "registration_id": [ "4312kjklfds2", "8914afd2", "45fdsa31" ] } }
              {
      "to": {
        "registration_id": [
          "4312kjklfds2",
          "8914afd2",
          "45fdsa31"
        ]
      }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    body

    The body of the request. Supported fields are as follows:

    Keyword Type Option Description
    platform String or JSON Array Required Push platform
    notification JSON Object Optional
  • The notification body, which is the content pushed to the client.
  • Together with message, they must have one, and they cannot coexist.
  • message JSON Object Optional
  • The message body, which is the content pushed to the client.
  • Together with notification, they must have one, and they cannot coexist.
  • options JSON Object Optional Push parameters

    platform

    MTPush currently only supports Web platform push, so the keyword specified by platform is "web".

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

    notification

    The notification object is one of the pushed entity content objects (the other is a message) and is pushed to the web as a notification

    Keyword Type Option Meaning Description
    web JSON Object Required Platform properties Platform push parameters,see web

    web

    Notifications on the Web platform

    Keyword Type Option Meaning Description
    alert String or JSON Object Required Contents The message content itself, which is specified here, overwrites the alert information specified by the superior.
    url String Required web push url Notification click jump address
    title String Optional Title Message title
    Extras JSON Object Optional Extended fields Here, you can customize the Key / Value information in JSON format for business use.
    icon String optional notification icon recommended 192*192px, no mandatory limit; mandatory limit size up to 1M, limited format: JPG, PNG, GIF, support Chrome, Firefox (Safari and Edge systems cannot be customized by default)
    image String Optional Big image for notification Recommended 360*180px, no mandatory limit; mandatory maximum size limit 1M, limited format: JPG, PNG, GIF, Chrome, Edge supported (Firefox and Safari not supported)
    { "notification": { "web": { "alert": "hello, Push!", "title": "Push Test", "url":"http://www.google.com", "icon":"", "image":"", "extras": { "news_id": 134, "my_key": "a value" } } } }
              {
        "notification": {
            "web": {
                "alert": "hello, Push!",
                "title": "Push Test",
                "url":"http://www.google.com",
                "icon":"",
                "image":"",
                "extras": {
                    "news_id": 134,
                    "my_key": "a value"
                }
            }
        }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    message

    In-App messages. Or custom messages. This part of the content is not displayed on the browser. After receiving the message, the SDK transmits it to the Web, and the Web processes the business logic

    The message contains the following fields:

    Keyword Type Option Description
    msg_content String or JSON Object Required Message content
    title String Optional Message title
    content_type String Optional Message content type
    Extras JSON Object Optional Optional parameters in 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"
        }
      }
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    options

    Push options. The following options are available:

    Keyword Type Option Meaning Description
    time_to_live Int or String Optional Offline message retention duration (seconds)
  • If the user is not online during the push, you can keep the specified length of offline messages for the user to push again when the user is online.
  • The default value is 86400 (1 day) and the maximum value is 15 days. If the maximum value supported by the system browser is less than the valid value passed, the system maximum value shall prevail.
  • If you set this parameter to 0, offline messages are not retained. Only users who push messages online can receive messages.
  • override_msg_id Long Optional The ID of the message to overwrite. If the current push is to overwrite the previous push, the msg_id of the previous push will generate the overwrite effect, that is:
  • The message received offline by the msg_id is overwritten. Even if the msg_id web user has received the message, if the notification bar has not been cleared, the new message content overwrites the previous notification.
  • The time limit for the overwrite function is 1 day. If the msg_id does not exist within the specified time limit, a 1003 error is returned, indicating that the message is not a valid overwrite operation and the current message will not be pushed.
  • big_push_duration Int Optional Fixed speed push duration (minutes)
  • Also known as slow push, it reduces the original push speed as fast as possible and evenly pushes it to the target users within a given n minutes. The maximum value is 1440.
  • A maximum of 20 fixed-speed pushes can exist at the same time.
  • If this parameter is not set, it is not a fixed-speed push.
  • multi_language json object Optional Multi-language push settings Settings for multi-language adaptation of push content, see multi_language for more details.
    third_party_channel JSON Object Optional Web system channel configuration information View valid parameters only for users with system channels configured third_party_channel.

    multi_language

    This field is the multi-language push function of the EngageLab Push service. It allows you to push customized notification content to users in different languages. By specifying multiple languages and their corresponding message content, title, and iOS subtitle in the push request, you can send appropriate push notifications according to the user's language settings.

    Request Parameters
    Keyword Type Option Meaning Description
    en string Optional Multi-language key Corresponds to the user's language, see the appendix for key codes
    content string Optional Message content Replace the data in notification.web.alert, message.msg_content based on the user's language
    title string Optional Message title Replace the data in notification.web.title, message.title based on the user's language
    Request Example
    HTTP request method: Post Request URL: /v4/push POST data format: json POST data example: { "options": { "multi_language": { "en": { "content": "", "title": "", } } } }
                 HTTP request method: Post
       Request URL: /v4/push
       POST data format: json
       POST data example:
       {
        "options": {
          "multi_language": {
            "en": {
              "content": "",
              "title": "",
            }
          }
        }
       }
    
            
    このコードブロックは、フローティングウィンドウに表示されます
    Response Example
    On success: { } On failure: { "code":400, "data":"", "message":"Error information" }
              On success:
    {
       
    }
    
    On failure:
    {   
        "code":400,  
        "data":"",
      "message":"Error information"
    }   
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    third_party_channel

    This field is used to fill in the personalized information of the Web system channel. The key name is w3push, and the value is a Json Object Object. The Object contains only one optional distribution field of the type String

    Keyword Type Option Meaning Description
    distribution Required String When the Engagelab and the system channel coexist, set the delivery priority. The value cannot be an empty string.
  • first_ospush: indicates that the push is sent through the system channel first, but the push is not sent through the Engagelab channel.
  • mtpush: indicates that the push is forcibly sent through the Engagelab channel.
  • secondary_push: indicates that the push takes the Engagelab first, and the Engagelab is not online and then goes through the system channel. The system channel is used as an auxiliary method (this method is recommended).
  • ospush:Indicates that push is forced to be delivered only through the system channel.
  • Example:

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

    request_id

    The id of the request. The customer identifies the request and returns the response

    Sample Requests

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

    Response Example

    custom_args

    The user-defined optional field. It is not returned when it responds, but returned when it is called back.

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

    Response parameters

    Success Response

    field type option description
    request_id String Optional The custom ID submitted on request, returned as is on response.
    message_id String Required The message ID to uniquely identify a message.
    < HTTP/1.1 200 OK < Content-Type: application/json {"request_id": "18", "msg_id": "1828256757"}
              < HTTP/1.1 200 OK
    < Content-Type: application/json
    {"request_id": "18", "msg_id": "1828256757"}
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    Failure response

    The http status code is 4xx or 5xx and the response body contains the following fields.

    Field Type Option Description
    code int required the error code. For more information, see return-code description
    message String required error details
    { "code": 3002, "message": "Push.template field must be set correctly when type is template" }
              {
        "code": 3002,
        "message": "Push.template field must be set correctly when type is template"
    }
    
            
    このコードブロックは、フローティングウィンドウに表示されます

    Response

    HTTP status code

    References:HTTP-Status-Code

    Return code

    Code Description Detailed explanation HTTP status code
    20101 The push parameter is invalid. The registration_id is invalid or does not belong to the current appkey. 400
    21001 Only HTTP Post methods are supported. The Get method is not supported. 405
    21002 Required parameters are missing. Must be corrected 400
    21003 Invalid parameter value Must be corrected 400
    21004 Verification failed. It must be corrected. For more information, see call verification. 401
    21005 The message body is too large. It must be corrected. The length of the Notification + Message must be limited to 2048 bytes. 400
    21008 The app_key parameter is invalid. It must be corrected. Please carefully compare whether the appkey you passed is the same as that in the application information and whether there are more spaces. 400
    21009 Internal system error Must be corrected 400
    21011 There are no push targets that meet the conditions. Please check 400
    21015 Request parameter verification failed. Unexpected parameters 400
    21016 Request parameter verification failed. The parameter type is incorrect or the parameter length exceeds the limit. 400
    21030 Internal Service timeout Try again later 503
    23006 Parameter error The maximum value of big_push_duration is 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 The verification information is empty. 401
    27008 Parameter error The distribution in third_party_channel is not empty, but the alert content of the notification is empty. 401
    27009 Parameter error The format of distribution in third_party_channel is invalid or empty. 401

    Push Restrictions

    Channel Subject length Content length Other instructions
    Engagelab 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 MTPush is limited to 4000 bytes.
    System Channel <20 characters (40 English characters)
  • The notification center and lock screen status can display up to 110 characters and 55 Chinese characters.
  • A maximum of 62 characters and 31 Chinese characters are displayed in the top pop-up window, and ellipsis is displayed in the excess part.
  • 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
    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
    Contact Sales