Push API v4

向某单个设备或者某设备列表推送一条通知、或者消息。

推送的内容只能是 JSON 表示的一个推送对象。

标签/别名相关功能参考AppPushAPI即可。

info 这是 Push API 最近的版本。v4 版本的改进为：

使用 HTTP Basic Authentication 的方式做访问授权。这样整个 API 请求可以使用常见的 HTTP 工具来完成，比如：curl，浏览器插件等。
推送内容完全使用 JSON 的格式。

请求频率限制

我们的API对调用频率有限制，以确保服务的稳定性和公平性。每个AppKey的QPS（每秒查询量）限制如下：

标准限制：每秒最多500次请求。
高级限制：如果您是我们的付费计划用户，且您的付费AppKey需要更高的QPS限制，请联系我们的商务团队：Sales@engagelab.com。

调用验证

详情参见 REST API 概述的鉴权方式说明。

调用地址

POST /v4/push

          
POST /v4/push

此代码块在浮窗中显示

请求示例

请求头

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

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

此代码块在浮窗中显示

请求体

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

此代码块在浮窗中显示

请求参数

推送的参数结构体，详见下表：

关键字	类型	选项	含义
from	String	可选	当前业务发送方
to	String 或 JSON Object	必填	发送目标
body	JSON Object	必填	发送请求体
platform	String 或 JSON Array	必填	推送平台
notification	JSON Object	可选	通知内容体，是被推送到客户端的内容。与 message 一起二者必须有其一，二者不可以并存。
message	JSON Object	可选	消息内容体，是被推送到客户端的内容。与 notification 一起二者必须有其一，二者不可以并存。
options	JSON Object	可选	推送参数
request_id	String	可选	客户自定义的可选字段，客户用来标识是哪条请求，响应时返回。
custom_args	JSON Object	可选	客户自定义的可选字段，回调时返回给客户。

from

当前业务发送方，String 类型，可选字段。

请求示例

{ "from":"push" }

          {
    "from":"push"
}

此代码块在浮窗中显示

to

推送设备对象，表示一条推送可以被推送到哪些设备列表。确认推送设备对象，MTPush 提供了两种方式，分别是注册ID和广播。

推送目标

关键字	类型	含义	说明	备注
all	String	发广播	给全部设备进行推送	推送目标为365天内活跃过的设备。
registration_id	JSON Array	注册ID	数组。多个注册ID之间是 OR 关系，即取并集。	设备标识。一次推送最多 1000 个。
tag	JSON Array	标签	数组。多个标签之间是 OR 的关系，即取并集。	用标签来进行大规模的设备属性、用户属性分群。一次推送最多 20 个。有效的 tag 组成：字母（区分大小写）、数字、下划线、汉字。限制：每一个 tag 的长度限制为 40 字节。（判断长度需采用UTF-8编码）
tag_and	JSON Array	标签AND	数组。多个标签之间是 AND 关系，即取交集。	注意与 tag 区分，一次推送最多 20 个。
tag_not	JSON Array	标签NOT	数组。多个标签之间，先取多标签的并集，再对该结果取补集。	一次推送最多 20 个。
alias	JSON Array	别名	数组。多个别名之间是 OR 关系，即取并集。	用别名来标识一个用户。一个设备只能绑定一个别名。一次推送最多 1000 个。有效的 alias 组成：字母（区分大小写）、数字、下划线、汉字。限制：每一个 alias 的长度限制为 40 字节。（判断长度需采用UTF-8编码）

数组里多个值之间隐含的关系是是 OR，即取并集;但 tag_and 不同，其数组里多个值之间是 AND 关系，即取交集。

tag_not 不能单独使用，其他 5 种类型至少需要有其一。如果值数组长度为 0，表示该类型不存在。

这几种类型可以并存。并存时多项的隐含关系是 AND，即取交集。例如：

"to" : {"tag" : [ "tag1", "tag2"], "tag_and" : ["tag3", "tag4"], "tag_not" : ["tag5", "tag6"] }

先计算 "tag" 字段的结果 tag1 或 tag2 = A;

再计算 "tag_and" 字段的结果 tag3 且 tag4 = B;

再计算 "tag_not" 字段的结果 非 (tag5 或 tag6) = C;

"to" 的最终结果为 A 且 B 且 C 。

请求示例

推送给全部（广播）：

{ "to": "all", }

          {
  "to": "all",
}

此代码块在浮窗中显示

推送给多个注册ID：

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

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

此代码块在浮窗中显示

body

发送请求体。支持的字段如下：

关键字	类型	选项	含义
platform	String 或 JSON Array	必填	推送平台
notification	JSON Object	可选	通知内容体，是被推送到客户端的内容。与 message 一起二者必须有其一，二者不可以并存。
message	JSON Object	可选	消息内容体，是被推送到客户端的内容。与 notification 一起二者必须有其一，二者不可以并存。
options	JSON Object	可选	推送参数

platform

MTPush 当前仅支持 Web 平台的推送，所以 platform 指定的关键字为："web"。

{ "platform" : "web" }

          { "platform" : "web" }

此代码块在浮窗中显示

notification

“通知”对象，是一条推送的实体内容对象之一（另一个是“消息”），是会作为“通知”推送到 web 端的。

关键字	类型	选项	含义	说明
web	JSON Object	必填	平台属性	平台推送参数

web

Web 平台上的通知。

关键字	类型	选项	含义	说明
alert	String 或 JSON Object	必填	内容	消息内容本身，这里指定了，将会覆盖上级统一指定的 alert 信息。
url	String	必填	web 推送 url	通知点击跳转地址
title	String	可选	标题	消息标题
extras	JSON Object	可选	扩展字段	这里自定义 JSON 格式的 Key / Value 信息，以供业务使用。
icon	String	可选	通知 icon	建议 192*192px，不强制限制；强制限制大小上限 1M，限制格式：JPG、PNG、GIF，支持 Chrome、Firefox（Safari 和 Edge 系统默认无法自定义）
image	String	可选	通知大图	建议 360*180px，不强制限制；强制限制大小上限 1M，限制格式：JPG、PNG、GIF，支持 Chrome、Edge（Firefox 和 Safari 不支持）

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

应用内消息。或者称作：自定义消息，透传消息。此部分内容不会展示在浏览器上，SDK 收到消息内容后透传给 Web，Web 自行处理业务逻辑。

消息包含如下字段：

关键字	类型	选项	含义
msg_content	String 或 JSON Object	必填	消息内容本身
title	String	可选	消息标题
content_type	String	可选	消息内容类型
extras	JSON Object	可选	JSON 格式的可选参数

示例：

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

推送可选项。当前包含如下几个可选项：

关键字	类型	选项	含义	说明
time_to_live	Int 或 String	可选	离线消息保留时长(秒)	若推送时用户不在线，可为该用户保留指定时长的离线消息，以便其上线时再次推送。默认 86400 （1 天），最长 15 天，若系统浏览器支持的最大值 < 传递的有效值，则以系统最大值为准。设置为 0 表示不保留离线消息，只有推送当前在线的用户可以收到。
override_msg_id	Long	可选	要覆盖的消息 ID	如果当前的推送要覆盖之前的一条推送，这里填写前一条推送的 msg_id 就会产生覆盖效果，即：该 msg_id 离线收到的消息是覆盖后的内容，即使该 msg_id web端用户已经收到，如果通知栏还未清除，则新的消息内容会覆盖之前这条通知。覆盖功能起作用的时限是：1 天，如果在覆盖指定时限内该 msg_id 不存在，则返回 1003 错误，提示不是一次有效的消息覆盖操作，当前的消息不会被推送。
big_push_duration	Int	可选	定速推送时长(分钟)	又名缓慢推送，把原本尽可能快的推送速度，降低下来，给定的 n 分钟内，均匀地向这次推送的目标用户推送；最大值为 1440。最多能同时存在 20 条定速推送。未设置则不是定速推送。
web_buttons	JSON Object	可选	在通知消息上添加buttons	最多添加2个button。可设置button名称和跳转连接，详情查看web_buttons。
multi_language	json object	可选	多语言推送设置	推送内容多语言适配设置，详情查看multi_language 说明。
third_party_channel	JSON Object	可选	Web 系统通道配置信息	仅针对配置了系统通道的用户有效参数详情查看 third_party_channel 说明。

multi_language

本字段是 EngageLab Push 服务的多语言推送功能。它允许您为不同语言的用户推送定制化的通知内容。通过在推送请求中指定多个语言及对应的消息内容、标题和 iOS 子标题，您可以针对用户的语言设置发送适当的推送通知。

请求参数

关键字	类型	选项	含义	说明
en	string	可选	多语言key	对应推送用户语言，key码详见附录
content	string	可选	消息内容	根据用户语言替换notification.web.alert、message.msg_content里的数据
title	string	可选	消息标题	根据用户语言替换notification.web.title、message.title里的数据

请求示例

http请求方式: Post 请求地址：/v4/push POST数据格式:json POST数据例子: { "options": { "multi_language": { "en": { "content": "", "title": "", } } } }

             http请求方式: Post
   请求地址：/v4/push
   POST数据格式:json
   POST数据例子:
   {
    "options": {
      "multi_language": {
        "en": {
          "content": "",
          "title": "",
        }
      }
    }
   }

此代码块在浮窗中显示

返回示例

成功时： { } 失败时： { "code":400, "data":"", "message":"错误信息" }

          成功时：
{
   
}

失败时：
{   
    "code":400,  
    "data":"",
  "message":"错误信息"
}

此代码块在浮窗中显示

web_buttons

使用web_buttons参数，描述按钮的id、文本、图标和url。参数描述如下：

关键字	类型	选项	含义	说明
id	必选	String	button id	chrom48+版本支持
text	必选	String	button 内容	chrom48+版本支持
icon	可选	String	button icon	chrom50+版本支持
url	必选	String	button 跳转链接	chrom48+版本支持，若使用web_buttons,则web字段中的url不生效

调用示例如下：

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

此代码块在浮窗中显示

third_party_channel

本字段用来填写 Web 系统通道的个性化信息，key 名称为 w3push ，value 值为一个Json Object 对象,该对象里面仅包含一个可选的 distribution 字段，类型为 String

关键字	类型	选项	含义	说明
distribution	必选	String	Engagelab 和系统通道并存时，设置下发优先级	取值不能为空字符串。 first_ospush：表示推送优先走系统通道下发，无效走 Engagelab 通道下发。 mtpush：表示推送强制走 Engagelab 通道下发。 secondary_push：表示推送优先走 Engagelab ， Engagelab 不在线再走系统通道，系统通道作为辅助（建议此种方式）。 ospush：表示推送强制仅走系统通道下发。

调用示例如下：

{ "third_party_channel":{ "w3push":{ "distribution":"mtpush" } } }

          {
  "third_party_channel":{
    "w3push":{
      "distribution":"mtpush"
    }
  }
}

此代码块在浮窗中显示

request_id

请求 id，客户自定义的可选字段。客户用来标识是哪条请求，响应时返回。

请求示例

{ "request_id":"12345678" }

          {
      "request_id":"12345678"
}

此代码块在浮窗中显示

返回示例

custom_args

客户自定义的，可选字段，响应时不返回，回调时返回。

{ "custom_args":"business info" }

          {
  "custom_args":"business info"
}

此代码块在浮窗中显示

返回参数

成功返回

字段	类型	选项	描述
request_id	String	可选	请求时提交的自定义 ID，响应时原样返回。
message_id	String	必选	消息 ID，唯一标识某一条消息。

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

此代码块在浮窗中显示

失败返回

http 状态码为 4xx 或者 5xx，响应体包含字段如下：

字段	类型	选项	描述
code	int	必选	错误码，详见错误码说明
message	String	必选	错误详情

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

此代码块在浮窗中显示

调用返回

HTTP 状态码

参考文档：HTTP-Status-Code

错误码

Code	描述	详细解释	HTTP Status Code
20101	推送参数无效	registration_id 无效或不属于当前 appkey	400
21001	只支持 HTTP Post 方法	不支持 Get 方法	405
21002	缺少了必须的参数	必须改正	400
21003	参数值不合法	必须改正	400
21004	验证失败	必须改正，详情请看：调用验证	401
21005	消息体太大	必须改正， Notification+Message 长度限制为 2048 字节	400
21008	app_key 参数非法	必须改正，请仔细对比你所传的 appkey 是否与应用信息中的一致，是否多了空格	400
21009	系统内部错误	必须改正	400
21011	没有满足条件的推送目标	请检查 to 字段	400
21015	请求参数校验失败	存在非预期的参数	400
21016	请求参数校验失败	参数类型错误，或者参数长度超出限制	400
21039	web button参数错误	button id、url或者text为空	400
21040	web button参数错误	button数量超过2个	400
21041	web button参数错误	url格式非法
21042	web button参数错误	button id重复
21030	内部服务超时	稍后重试	503
23006	参数错误	定速推送 big_push_duration 超过最大值 1440	400
23008	接口限速	单应用推送接口 qps 达到上限(500 qps)	400
27000	系统内存错误	请重试	500
27001	参数错误	校验信息为空	401
27008	参数错误	third_party_channel 里面的 distribution 不为空，但是 notification 的 alert 内容为空	401
27009	参数错误	third_party_channel 中 distribution 格式无效或为空	401

推送限制

系统通道	标题长度	内容长度	其他说明
Engagelab 通道	不限制，但限制消息体总大小	不限制，但限制消息体总大小	MTPush 中 Notification + Message 长度限制为 4000 个字节。
系统通道	＜ 20 个字符（40 个英文字符）	通知中心和锁屏状态最多显示 110 个字符，55 个汉字。顶部弹窗最多显示 62 个字符，31 个汉字，超过部分会显示省略号。	暂无

多语言码

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