Push API v4

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

This code block in the floating window

Sample Requests

Request header

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

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

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

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

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

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

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

Response Example

On success: { } On failure: { "code":400, "data":"", "message":"Error information" }

          On success:
{
   
}

On failure:
{   
    "code":400,  
    "data":"",
  "message":"Error information"
}

This code block in the floating window

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

This code block in the floating window

request_id

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

Sample Requests

{ "request_id":"12345678" }

          {
      "request_id":"12345678"
}

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

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

This code block in the floating window

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