Push API v4 | WebPush Developer Guide REST API

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 !", "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 !",
            "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	Optional	web push url	Notification click jump address. If provided, it must be a valid URL.
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	String	Required	button id	Supported from chrom48+ version
text	String	Required	button content	Supported from chrom48+ version
icon	String	Optional	button icon	Supported from chrom50+ version
url	String	Required	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" } ]

              
              [
  {
    "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"
  }
]

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. The default is first_ospush. 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	Required	The response property is always present. The custom ID submitted in the request is returned as is; if omitted in the request, it is usually an empty string.
msg_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	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 4000 bytes	400
21007	Illegal input parameter	The receiver_value parameter is illegal	400
21008	Invalid app_key parameter	Must be corrected. Check whether the transmitted appkey is a 24-character string and whether it contains extra spaces	400
21009	Internal system error	please contact the support team	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
21036	Parameter error	Notification messages and custom messages cannot be pushed simultaneously	400
21037	Invalid group_key	group_key is not a 24-character string, or the corresponding app group does not exist	400
21038	Push permission error	VIP expired or not activated	400
21039	Web Button parameter error	The Web Button id, url, or text is empty	400
21040	Web Button count exceeds the limit	The number of Web Buttons cannot exceed 2	400
21041	Invalid Web Button URL	The Web Button url format is invalid	400
21042	Duplicate Web Button ID	Web Button ids in the same request cannot be duplicated	400
21043	Push permission error	The app has an unpaid bill	400
21061	Content or callback configuration validation failed	The push content contains sensitive words, or the requested callback_url is not configured in the current app's callback addresses	400
21062	File push target count exceeds the limit	The number of push targets in the file exceeds the app quota or system limit	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	Invalid authentication information	The AppKey in Basic Auth is 24 characters long but the application does not exist, or the application authentication information is invalid	401
27006	override_msg_id does not exist	No push record found for the override_msg_id	400
27007	Invalid override_msg_id format	override_msg_id is negative or has an invalid format	400
27008	Parameter error	Distribution inside third_party_channel is not empty, but notification's alert content is empty	400
27009	Parameter error	Invalid or empty format for distribution in third_party_channel	400
27104	Segment ID does not exist	The segment ID does not exist. Create or update the segment first	400
27200	Invalid msg_id	The msg_id format is invalid	400
27201	msg_id does not exist or does not belong to the app	The msg_id does not exist, or does not belong to the current appkey	400
27202	Message already withdrawn	The message corresponding to msg_id has already been withdrawn	400
27203	System error	System error, please retry	400
27204	Message withdrawal time exceeded	The message has exceeded the allowed withdrawal time	400
27300	Invalid push plan ID	The plan_id format is invalid	400
27301	Invalid push plan description	The plan_description length exceeds the limit	400
27302	Push plan count exceeds the limit	The number of available push plans has reached the upper limit	400
27303	Empty push plan ID	plan_id cannot be empty	400
27304	Push plan ID too long	The plan_id length exceeds the limit	400
27305	Push plan does not exist	The specified plan_id does not exist under the current appkey	400
27306	Push plan ID count exceeds the limit	The number of plan_ids exceeds the limit	400
28100	Invalid schedule task parameter	The schedule task parameter is invalid	400
28101	Schedule task authentication failed	Basic Authentication failed	401
28102	Invalid scheduled push parameter	The push parameter is empty or invalid	400
28103	Invalid scheduled push time	The single time or trigger time format is incorrect	400
28104	Schedule task does not exist	The requested schedule task does not exist	404
28105	Schedule task has no push target	No matching push target at the scheduled time	400
28200	Schedule task system error	An unexpected internal service error occurred	500

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