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, and vice versa. 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.

If tag_not is used alone, we will perform tag_not processing among broadcast users.

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 offline during the push, offline messages can be retained for the specified duration for the user, so they can be pushed again when the user comes online. Default is 86400 (1 day), maximum is 15 days. If the maximum value supported by the system browser is less than the valid value passed, the system's maximum value will apply. Setting it to 0 means offline messages will not be retained, and only currently online users will receive the push.
override_msg_id	Long	Optional	Message ID to override	If the current push is to override a previous push, fill in the msg_id of the previous push here to achieve the override effect, i.e.: The offline message received for this msg_id will be the overridden content. Even if the msg_id has already been received by the user on the web, if the notification bar has not been cleared, the new message content will override the previous notification. The override function is effective within a time limit of 1 day. If the specified msg_id does not exist within the override time limit, error 1003 will be returned, indicating that it is not a valid message override operation, and the current message will not be pushed.
big_push_duration	Int	Optional	Duration of throttled push (minutes)	Also known as slow push, it reduces the original as-fast-as-possible push speed, evenly distributing the push to target users over the given n minutes; the maximum value is 1440. A maximum of 20 throttled pushes can exist simultaneously. If not set, it is not a throttled push.
web_buttons	JSON Object	Optional	Add buttons to notification messages	A maximum of 2 buttons can be added. Button names and redirect links can be set. For details, see web_buttons.
multi_language	JSON Object	Optional	Multi-language push settings	Multi-language adaptation settings for push content. For details, see multi_language description.
third_party_channel	JSON Object	Optional	Web system channel configuration information	Valid parameter only for users configured with system channels. For details, see third_party_channel description.
plan_id	String	Optional	Push plan identifier	A plan identifier value must be created first, which can be created in the console or via API.
cid	String	Optional	Push request identifier to prevent duplicate pushes	Only allows letters, numbers, underscores, and hyphens, with a maximum length of 64 characters. Note that this field must be unique under the same AppKey.

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

web_buttons

Use the web_buttons parameter to describe the button's id, text, icon, and url. The parameter descriptions are as follows:

Keyword	Type	Options	Meaning	Description
id	Required	String	button id	Supported from chrom48+ version
text	Required	String	button content	Supported from chrom48+ version
icon	Optional	String	button icon	Supported from chrom50+ version
url	Required	String	button redirect link	Supported from chrom48+ version. If web_buttons is used, the url field in the web parameter will not take effect

Example of invocation is as follows:

[ { "id": "like-button", "text": "Like", "icon": "http://i.imgur.com/N8SN8ZS.png", "url": "https://yoursite.com" }, { "id": "read-more-button", "text": "Read more", "icon": "http://i.imgur.com/MIxJp1L.png", "url": "https://yoursite.com" } ] #### 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.<li>first_ospush: indicates that the push is sent through the system channel first, but the push is not sent through the Engagelab channel.<li>mtpush: indicates that the push is forcibly sent through the Engagelab channel.<li>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).<li>ospush：Indicates that push is forced to be delivered only through the system channel.| Example： ```json { "third_party_channel":{ "w3push":{ "distribution":"mtpush" } } }

              
              [
  {
    "id": "like-button",
    "text": "Like",
    "icon": "http://i.imgur.com/N8SN8ZS.png",
    "url": "https://yoursite.com"
  },
  {
    "id": "read-more-button",
    "text": "Read more",
    "icon": "http://i.imgur.com/MIxJp1L.png",
    "url": "https://yoursite.com"
  }
]


#### 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.<li>first_ospush: indicates that the push is sent through the system channel first, but the push is not sent through the Engagelab channel.<li>mtpush: indicates that the push is forcibly sent through the Engagelab channel.<li>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).<li>ospush：Indicates that push is forced to be delivered only through the system channel.| 

Example：
```json
{
  "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 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 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	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
Ukrainian	uk
Lao	lo
Portuguese (Portugal)	pt_PT
Portuguese (Brazil)	pt_BR
Spanish (Argentina)	es_AR
Spanish (Spain)	es_ES
Spanish (Latin America)	es_419