创建推送 API

向某单个设备或者某设备列表推送一条通知、或者消息。推送的内容只能是 JSON 表示的一个推送对象。

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

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

请求频率限制

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

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

请求方式

POST

调用地址

接口服务地址与数据中心选择接入点一一对应，请选择与您的应用服务接入点对应的调用地址。

目前EngageLab已部署支持了两个数据中心接入点，不同服务接入点之间数据完全隔离，您可根据创建产品时选择的数据中心接入点选择调用地址。

新加坡数据中心调用地址：

POST https://push.api.engagelab.cc/v4/push

美国弗吉尼亚数据中心调用地址

POST https://push-usva.api.engagelab.cc/v4/push

德国法兰克福数据中心调用地址

POST https://push-defra.api.engagelab.cc/v4/push

调用验证

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

请求示例

请求头

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

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

此代码块在浮窗中显示

请求体

{ "from": "push", "to": "all", "body": { "platform": "all", "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android", "builder_id": 1, "extras": { "newsid": 321 } }, "ios": { "alert": "Hi, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "message": { "msg_content": "Hi,MTPush", "content_type": "text", "title": "msg", "extras": { "key": "value" } }, "options": { "time_to_live": 60, "apns_production": false } }, "request_id": "12345678", "custom_args":{ "Engagelab": "push to you" } } > POST /v4/push HTTP/1.1 > Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==

          {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "all",
        "notification": {
            "android": {
                "alert": "Hi, Push!",
                "title": "Send to Android",
                "builder_id": 1,
                "extras": {
                    "newsid": 321
                }
            },
            "ios": {
                "alert": "Hi, MTPush!",
                "sound": "default",
                "badge": "+1",
                "extras": {
                    "newsid": 321
                }
            }
        },
        "message": {
            "msg_content": "Hi,MTPush",
            "content_type": "text",
            "title": "msg",
            "extras": {
                "key": "value"
            }
        },
        "options": {
            "time_to_live": 60,
            "apns_production": false
        }
    },
    "request_id": "12345678",
    "custom_args":{
             "Engagelab": "push to you"
    }
}
> POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==

此代码块在浮窗中显示

请求参数

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

关键字	类型	选项	含义
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

推送设备对象，表示一条推送可以被推送到哪些设备列表。确认推送设备对象，App Push 提供了多种方式，比如：别名、标签、注册ID、分群、广播等。

推送目标

广播外的设备选择方式，有如下几种：

关键字	类型	含义	说明	备注
all	String	发广播	给全部设备进行推送	推送目标为30天内活跃过的设备。
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编码）
registration_id	JSON Array	注册ID	数组。多个注册ID之间是 OR 关系，即取并集。	设备标识。一次推送最多 1000 个。

数组里多个值之间隐含的关系是是 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",
}

此代码块在浮窗中显示

推送给多个标签（只要在任何一个标签范围内都满足）：在深圳、广州、或者北京

{ "to":{ "tag":[ "深圳", "广州", "北京" ] } }

          {
    "to":{
        "tag":[
            "深圳",
            "广州",
            "北京"
        ]
    }
}

此代码块在浮窗中显示

推送给多个标签（需要同时在多个标签范围内）：在深圳并且是“女”

{ "to":{ "tag_and":[ "深圳", "女" ] } }

          {
    "to":{
        "tag_and":[
            "深圳",
            "女"
        ]
    }
}

此代码块在浮窗中显示

推送给多个别名：

{ "to":{ "alias":[ "4314", "892", "4531" ] } }

          {
    "to":{
        "alias":[
            "4314",
            "892",
            "4531"
        ]
    }
}

此代码块在浮窗中显示

推送给多个注册ID：

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

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

此代码块在浮窗中显示

可同时推送指定多类推送目标：在深圳或者广州，并且是 “女” “会员”

{ "to":{ "tag":[ "深圳", "广州" ], "tag_and":[ "女", "会员" ] } }

          {
    "to":{
        "tag":[
            "深圳",
            "广州"
        ],
        "tag_and":[
            "女",
            "会员"
        ]
    }
}

此代码块在浮窗中显示

body

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

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

platform

MTPush 当前支持 Android， iOS 平台的推送。其关键字分别为："android", "ios"。

如果目标平台为 iOS 平台，需要在 options 中通过 apns_production 字段来制定推送环境。True 表示推送生产环境，False 表示要推送开发环境；如果不指定则为推送开发环境。

推送到所有平台：

{ "platform" : "all" }

          { "platform" : "all" }

此代码块在浮窗中显示

指定特定推送平台：

{ "platform": [ "android", "ios" ] }

          {
  "platform": [
    "android",
    "ios"
  ]
}

此代码块在浮窗中显示

notification

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

关键字	类型	选项	含义	说明
alert	String 或 JSON Object	必填	内容	消息内容本身。若 android、ios 下没有指定 alert，则以此为准。
android	JSON Object	选填	android 平台属性	android 平台推送参数，详见android 说明
ios	JSON Object	选填	ios 平台属性	ios 平台推送参数，详见ios 说明

alert

这个位置的 "alert" 属性（直接在 notification 对象下），是一个快捷定义，各平台的 alert 信息如果都一样，则可不定义平台下的 alert，以此为准。如果各平台有定义，则覆盖这里的定义。

{ "notification" : { "alert" : "Hello, Push!" } }

          {
  "notification" : {
    "alert" : "Hello, Push!"
  }
}

此代码块在浮窗中显示

上面定义的 notification 对象，将被推送到 "platform" 指定的多个平台，并且其通知 alert 信息都一样。

android

Android 平台上的通知，被 MTPush SDK 按照一定的通知栏样式展示。支持的字段如下：

关键字	类型	选项	含义	说明
alert	String 或 JSON Object	必填	通知内容	这里指定后会覆盖上级统一指定的 alert 信息。内容可以为空字符串，表示不展示到通知栏。各推送通道对此字段的限制详见推送限制。
title	String	可选	通知标题	如果指定了，则通知里原来展示 App 名称的地方，将展示 title。各推送通道对此字段的限制详见推送限制。
builder_id	Int	可选	通知栏样式ID	Android SDK 可设置通知栏样式，这里根据样式 ID 来指定该使用哪套样式。
channel_id	String	可选	Android 通知栏通道 ID	不超过 1000 字节，Android 8.0开始可以进行NotificationChannel 配置，这里根据 channel ID 来指定通知栏展示效果。
priority	Int	可选	通知栏展示优先级	默认为 0，范围为 -2～2。
category	String	可选	通知栏条目过滤或排序	完全依赖 rom 厂商对 category 的处理策略。
style	Int	可选	通知栏样式类型	用来指定通知栏样式类型，默认为 0。
big_text	String	可选	大文本通知栏样式	当 style = 1 时可用，内容会被通知栏以大文本的形式展示出来。支持 api 16 以上的 rom。
inbox	JSONObject	可选	文本条目通知栏样式	当 style = 2 时可用， json 的每个 key 对应的 value 会被当作文本条目逐条展示。支持 api 16 以上的 rom。
big_pic_path	String	可选	大图片通知栏样式	当 style = 3 时可用，目前支持 .jpg 和 .png 格式的图片。支持网络图片 url、本地图片的 path，如果是 http／https 的 url，会自动下载；如果要指定开发者准备的本地图片就填 sdcard 的相对路径。支持 api 16 以上的 rom。
extras	JSON Object	可选	扩展字段	这里自定义 JSON 格式的 Key/Value 信息，以供业务使用。
intent	JSON Object	可选	指定跳转页面(推荐)	使用 intent 里的 url 指定点击通知栏后跳转的目标页面。建议填写 intent 字段，否则点击通知可能无跳转动作。此字段支持以下三种类型: 跳转到目标页:`intent:#Intent;action=action 路径;component= 包名 /Activity 全名;end<li>应用首页: intent:#Intent;action=android.intent.action.MAIN;end (固定为此地址) <li>跳转到deeplink地址:` scheme://test?key1=val1&key2=val2
large_icon	String	可选	通知大图标	图标大小不超过 300 k。支持网络图片 url、本地图片的 path，如果是 http／https 的 url，会自动下载；如果要指定开发者准备的本地图片就填 sdcard 的相对路径。
small_icon	String	可选	通知小图标	通知小图标，图标路径可以是以 http 或 https 开头的网络图片，大小不能超过 300 k。若没有填充厂商 small_icon_uri，则默认使用该 small_icon 字段展示。
sound	String	可选	铃声	填写 Android 工程中 /res/raw/ 路径下铃声文件名称，无需文件名后缀。注意：针对 Android 8.0 以上，当传递了 channel_id 时，此属性不生效。
badge_add_num	Int	可选	设置角标数字累加值，在原角标的基础上进行累加	此属性目前仅针对华为 EMUI 8.0 及以上、小米 MIUI 6 及以上、vivo 设备走厂商通道时生效。此字段如果不填，表示不改变角标数字（小米设备由于系统控制，不论推送走 Engagelab 通道下发还是厂商通道下发，即使不传递依旧是默认 +1 的效果）。取值范围为：1-99，若设置了取值范围内的数字，下一条通知栏消息配置的 badge_add_num 数据会和原角标数量进行相加，建议取值为 1。举例：badge_add_num 取值为 1，原角标数为 2，发送此角标消息后，应用角标数显示为 3。
badge_class	String	可选	桌面图标对应的应用入口Activity类，比如“com.test.badge.MainActivity”	仅华为通道推送时生效，此值如果填写非主 Activity 类，以厂商限制逻辑为准。若需要实现角标累加功能，需配合 badge_add_num 使用，二者需要共存，缺少其一不可。
display_foreground	String	可选	APP 在前台，通知是否展示	值为 "1" 时，APP 在前台会弹出通知栏消息。值为 "0" 时，APP 在前台不会弹出通知栏消息。注：默认情况下 APP 在前台会弹出通知栏消息，MTPush Android SDK v4.3.1 版本开始支持。

{ "notification": { "android": { "alert": "hello, MTPush!", "title": "Push test", "builder_id": 3, "style": 1, "big_text": "big text content", "inbox":JSONObject, "big_pic_path": "picture url", "priority": 0, "category": "category str", "large_icon": "http://push.api.engagelab.cc/largeIcon.jpg", "small_icon": "http://www.small.com/small_icon.jpg", "intent": { "url": "intent:#Intent;component=push.api.engagelab.cc/com.example.mtpushdemo.SettingActivity;end" }, "extras": { "news_id": 134, "my_key": "a value" } } } }

          {
    "notification": {
        "android": {
            "alert": "hello, MTPush!",
            "title": "Push test",
            "builder_id": 3,
            "style": 1,
            "big_text": "big text content",
            "inbox":JSONObject,
            "big_pic_path": "picture url",
            "priority": 0,
            "category": "category str",
            "large_icon": "http://push.api.engagelab.cc/largeIcon.jpg",
            "small_icon": "http://www.small.com/small_icon.jpg",
            "intent": {
                "url": "intent:#Intent;component=push.api.engagelab.cc/com.example.mtpushdemo.SettingActivity;end"
            },
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

此代码块在浮窗中显示

ios

iOS 平台上 APNs 通知。

该通知内容会由 MTPush 代理发往 Apple APNs 服务器，并在 iOS 设备上以系统通知的方式呈现。

该通知内容满足 APNs 的规范，支持的字段如下：

关键字	类型	选项	含义	说明
alert	String 或 JSON Object	必填	通知内容	这里指定内容将会覆盖上级统一指定的 alert 信息。内容为空则不展示到通知栏。支持字符串形式也支持官方定义的 alert payload 结构，在该结构中包含 title 和 subtitle 等官方支持的 key。
sound	String 或 JSON Object	可选	通知提示声音	普通通知： String 类型。如果无此字段，则此消息无声音提示；有此字段，如果找到了指定的声音就播放该声音，否则播放默认声音。如果此字段为空字符串，iOS 7 为默认声音，iOS 8 及以上系统为无声音。告警通知： JSON Object , 支持官方定义的 payload 结构，在该结构中包含 critical 、name 和 volume 等官方支持的 key 。
badge	Int 或 String	可选	应用角标	可设置为 N、+N、-N，N 的取值范围为 [0,99]。若上传的角标值 value 为 10，表示角标会设置为 N、10+N、10-N（值小于 0 时默认清除角标）。为 0 或空字符串，则表示清除角标。如果不填，表示不改变角标数字。 MTPush 官方 API Library(SDK) 会默认填充badge值为"+1"。
content-available	Boolean	可选	推送唤醒	推送的时候携带"content-available":true 说明是 Background Remote Notification，如果不携带此字段则是普通的Remote Notification。详情参考：Background Remote Notification
mutable-content	Boolean	可选	通知扩展	iOS 10 新增的 Notification Service Extension 功能，用于上报每条 APNs 信息的送达状态，使用该功能需要客户端实现 Service Extension 接口，并在服务端使用 mutable-content 字段完成设置。 true：说明支持 iOS 10 的UNNotificationServiceExtension 功能。如果不携带此字段则是普通的 Remote Notification，无法统计抵达数据。
category	String	可选		iOS 8 才支持。设置APNs payload中的"category"字段值。
extras	JSON Object	可选	扩展字段	这里自定义 Key/value 信息，以供业务使用。
thread-id	String	可选	通知分组	iOS 的远程通知通过该属性来对通知进行分组，同一个 thread-id 的通知归为一组。
interruption-level	String	可选	通知优先级和交付时间的中断级别	iOS 15 的通知级别，取值只能是 active,critical,passive,timeSensitive 中的一个，详情参考：UNNotificationInterruptionLevel。

iOS 通知 MTPush 要转发给 APNs 服务器。 MTPush 中 Notification + Message 长度限制为 4000 个字节。 MTPush 在推送时使用 utf-8 编码，所以一个汉字占用 3 个字节长度。

服务端发送示例：

{ "notification": { "ios": { "alert": "hello, Push!", "sound": "sound.caf", "badge": 1, "extras": { "news_id": 134, "my_key": "a value" } } } }

          {
    "notification": {
        "ios": {
            "alert": "hello, Push!",
            "sound": "sound.caf",
            "badge": 1,
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

此代码块在浮窗中显示

客户端收到的消息：

{ "_j_msgid" = 813843507; aps = { alert = "hello,Push!"; badge = 1; sound = "sound.caf"; }; "my_key" = "a value"; "news_id" = 134; }

          {
  "_j_msgid" = 813843507;
  aps =     {
  alert = "hello,Push!";
  badge = 1;
  sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}

此代码块在浮窗中显示

message

应用内消息。或者称作：自定义消息，透传消息。

此部分内容不会展示到通知栏上，MTPush SDK 收到消息内容后透传给 App。App 需要自行处理。
iOS 在推送应用内消息通道（非 APNS）获取此部分内容，需 App 处于前台。

支持的字段如下：

关键字	类型	选项	含义
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 Android 端用户已经收到，如果通知栏还未清除，则新的消息内容会覆盖之前这条通知。覆盖功能起作用的时限是：1 天，如果在覆盖指定时限内该 msg_id 不存在，则返回 7006 错误，提示不是一次有效的消息覆盖操作，当前的消息不会被推送。该字段仅对 Android 有效仅支持Engagelab 通道、小米通道、魅族通道、OPPO 通道、FCM 通道、华为通道（EMUI10 及以上的设备）。
apns_production	Boolean	可选	APNs 是否生产环境	该字段仅对 iOS 的 Notification 有效，如果不指定则为推送开发环境。注意：MTPush 官方 API LIbrary (SDK) 默认设置为推送 “开发环境”。 true：表示推送生产环境。 false：表示推送开发环境。
apns_collapse_id	String	可选	更新 iOS 通知的标识符	APNs 新通知如果匹配到当前通知中心有相同 apns-collapse-id 字段的通知，则会用新通知内容来更新它，并使其置于通知中心首位。 collapse id 长度不可超过 64 bytes。
big_push_duration	Int	可选	定速推送时长(分钟)	又名缓慢推送，把原本尽可能快的推送速度，降低下来，给定的 n 分钟内，均匀地向这次推送的目标用户推送；最大值为 1440。
multi_language	json object	可选	多语言推送设置	推送内容多语言适配设置，详情查看multi_language 说明。
third_party_channel	JSON Object	可选	Android 厂商通道配置信息	仅针对配置了厂商通道的用户有效参数，详情查看third_party_channel 说明。
classification	Int	可选	推送消息分类设置	EngageLab不对指定的消息类型进行判断或校准。不填默认为 0。 0：代表运营消息。 1：代表系统消息。

multi_language

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

请求参数

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

请求示例

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

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

此代码块在浮窗中显示

返回示例

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

          成功时：
{
   
}

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

此代码块在浮窗中显示

third_party_channel

本字段用来填写 Android 厂商通道的个性化信息，key 只支持 xiaomi、huawei、meizu、oppo、vivo、fcm、honor 这 7 个 Android 厂商通道，可以为其中一个或者多个同时存在，每个厂商类型的 KEY 当前可包含如下几个可选项：

注：多个key存在的情况下，distribution_new取值以厂商通道（xiaomi、huawei、meizu、oppo、vivo、honor）的设置为准。

请求参数

关键字	类型	选项	含义	说明
distribution_new	String	必选	Engagelab 和厂商通道并存时，设置下发优先级	取值不能为空字符串。 mtpush：表示推送强制走 Engagelab 通道下发。 pns_mtpush：表示针对 fcm+ 国内厂商组合类型用户，推送强制优先走小米 / 华为 / 魅族 /oppo/vivo/荣耀通道下发，无效再走engagelab通道。 mtpush_pns：表示针对 fcm+ 国内厂商组合类型用户，推送优先走engagelab，engagelab不在线再走厂商通道，厂商作为辅助。 fcm_mtpush：表示针对 fcm+ 国内厂商组合类型用户，推送强制优先走 fcm 通道下发，无效再走engagelab通道 mtpush_fcm：表示针对 fcm+ 国内厂商组合类型用户，推送优先走engagelab，engagelab不在线再走 fcm 通道，fcm 作为辅助。``注：针对pns_mtpush/fcm_mtpush/mtpush_pns/mtpush_fcm这四种策略而言，如果设备可用的系统推送通道仅有一种（FCM或者手机厂商），则会忽略强制优先级，走集成成功的系统通道。
channel_id	String	可选	通知栏消息分类	支持OPPO 的私信、小米的通知消息、华为消息分类类别，分类 ChannelID 值需开发者自行向厂商申请。
classification	Int	可选	通知栏消息分类	vivo 手机厂商通知栏消息分类，不填默认为 0。 0：代表运营消息。 1：代表系统消息。``目前 vivo 对系统消息分类较为严格，具体规则参考：vivo开发者平台。
pushMode	Int	可选	vivo推送模式	不填默认为 0。详情参考vivo pushMode，使用测试推送需要手动在 vivo 后台配置测试设备的 ID 。 0：表示正式推送。 1：表示测试推送。
importance	String	可选	华为/荣耀通知栏消息智能分类	为了适配华为手机厂商的通知栏消息智能分类，对应华为的 importance 字段，不填充默认为 "NORMAL"，参考：华为通知消息智能分类。 LOW：一般消息。 NORMAL：重要消息。 HIGH：非常重要消息（仅华为支持）。
urgency	String	可选	华为厂商自定义消息优先级	为了适配华为手机厂商自定义消息的优先级。 HIGH：非常重要消息，HIGH 级别消息到达用户手机时可强制拉起应用进程。 NORMAL：重要消息。``设置“HIGH”需要向华为申请特殊权限，参考：特殊权限如何申请。
category	String	可选	华为厂商自定义消息场景标识	为了适配华为手机厂商自定义消息，标识高优先级透传消息的特殊场景，或用于标识消息类型以对特定类型消息加快发送，对应值及其说明参考：category 值说明。
small_icon_uri	String	可选	厂商消息小图标样式	目前支持小米 / 华为厂商。优先使用厂商字段，厂商字段没有填充，则使用 android 内的 small_icon 字段。小米支持小米厂商的大图标 id，华为、支持 Engagelab 的 media_id 及厂商本地路径。(小米官方后续不再支持自定义小图标，建议开发者不要继续使用小米 small Icon 相关特性功能)。
small_icon_color	String	可选	小米厂商小图标样式颜色	为了适配小米厂商的消息小图标样式颜色，不填充默认是灰色 (小米官方后续不在支持自定义小图标，建议开发者不要继续使用小米 small icon 相关特性功能)。
big_text	String	可选	厂商消息大文本样式	为了适配厂商的消息大文本样式, 目前支持华为/荣耀/小米/OPPO，其中小米OPPO最多支持128个字符。优先使用此厂商字段，厂商字段没有填充，则使用 android 里面定义 big_text 字段。 android里面字段style=1时使用。
only_use_vendor_style	Boolean	可选	是否使用自身通道设置样式	是否只使用自身通道设置的样式，不使用 android 里面设置的样式，默认为 false， true：只使用自身通道设置的样式。 false：可使用 android 里面设置的样式。

请求示例

"third_party_channel": { "xiaomi": { "distribution_new": "mtpush", "channel_id": "*******", "small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png", "small_icon_color": "#ABCDEF", }, "huawei": { "distribution_new": "mtpush_pns", "importance": "NORMAL", "small_icon_uri": "https://xx.com/xx.jpg", "only_use_vendor_style": true }, "meizu": { "distribution_new": "mtpush" }, "fcm": { "distribution_new": "mtpush" }, "oppo": { "distribution_new": "mtpush", "channel_id": "*******", "large_icon": "3653918_5f92b5739ae676f5745bcbf4", }, "vivo": { "distribution_new": "mtpush", "pushMode": 0 } }

          "third_party_channel": {
    "xiaomi": {
        "distribution_new": "mtpush",
        "channel_id": "*******",
        "small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png",
        "small_icon_color": "#ABCDEF",
    },
    "huawei": {
        "distribution_new": "mtpush_pns",
        "importance": "NORMAL",
        "small_icon_uri": "https://xx.com/xx.jpg",
        "only_use_vendor_style": true
    },
    "meizu": {
        "distribution_new": "mtpush"
    },
    "fcm": {
        "distribution_new": "mtpush"
    },
    "oppo": {
        "distribution_new": "mtpush",
        "channel_id": "*******",
        "large_icon": "3653918_5f92b5739ae676f5745bcbf4",
    },
    "vivo": {
        "distribution_new": "mtpush",
        "pushMode": 0
    }
}

此代码块在浮窗中显示

request_id

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

请求示例

{ "request_id":"12345678" }

          {
      "request_id":"12345678"
}

此代码块在浮窗中显示

返回示例

{ "msg_id": "1225764", "request_id": "12345678" }

          {
    "msg_id": "1225764",
    "request_id": "12345678"
}

此代码块在浮窗中显示

custom_args

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

请求示例

{ "custom_args":{ "args1": "args1" } }

          {
  "custom_args":{
    "args1": "args1"
  }
}

此代码块在浮窗中显示

返回参数

成功返回

字段	类型	选项	描述
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
21030	内部服务超时	稍后重试	503
23006	参数错误	定速推送 big_push_duration 超过最大值 1440	400
23008	接口限速	单应用推送接口 qps 达到上限(500 qps)	400
23009	推送权限错误	当前推送ip地址不在应用ip白名单内	400
27000	系统内存错误	请重试	500
27001	参数错误	校验信息为空	401
27008	参数错误	third_party_channel 里面的 distribution 不为空，但是 notification 的 alert 内容为空	401
27009	参数错误	third_party_channel 中 distribution 格式无效或为空	401
21038	推送权限错误	VIP已过期或未开通	401
21306	参数错误	通知消息和自定义消息不能同时推送	401

推送限制

厂商通道	标题长度	内容长度	敏感词	其他说明
Engagelab 通道	＜ 50 个字符	<500字符	-	MTPush 中 Notification/Message 长度限制为 4096 个字节。
华为通道	＜ 40 个字符	＜ 1024 字符	禁止携带政府，领导人名称、台独等相关内容	默认【营销通知】的权限为静默通知，静默推送没有声音、震动等提示。
荣耀通道	不限制，但消息体总大小<4096字节	不限制，但消息体总大小＜ 4096 字节	禁止携带政府，领导人名称、台独等相关内容	-
魅族通道	＜ 32 个字符	＜ 100 个字符	禁止特殊字符，如：#	中英文字符均计算为 1 个字符。部分消息可能会存入魅族手机右上角【魅族消息盒子】中。
小米通道	＜ 50 个字符	＜ 128 个字符	禁止特殊字符，如：#、>>	中英文字符均计算为 1 个字符。部分消息可能会存在通知栏的不重要通知里。
OPPO 通道	＜ 32 个字符	＜ 200 个字符	暂无说明	中英文字符均计算为 1 个字符。默认关闭通知权限。
vivo 通道	＜ 40 个字符	＜ 100 个字符	禁止特殊字符，如：#、>> 正式消息禁止：纯数字、纯英文、纯符号、符号加数字，测试、test、大括号、中括号等	英文为 1 个字符，中文为 2 个字符。默认关闭通知权限。同设备 1 天内运营消息的推送条数不能超过 5 条。同设备 1 天内不能重复推送内容相同的运营消息。
APNS 通道	＜ 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
Turkish	th
Vietnamese	vi
Indonesian	id
Norwegian	no
Swedish	sv
Polish	pl
Turkish	tr
Hebrew	he
Portuguese	pt
Romanian	ro