创建推送 API

最新更新:2024-02-22

向某单个设备或者某设备列表推送一条通知、或者消息。 推送的内容只能是 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-usva.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": "business info" }' > 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": "business info"
}'
> 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 说明。

    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", "classification": 0, "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",
            "classification": 0,
            "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
    在文档中心打开