logo
简体中文
English
繁體中文
简体中文
日本語
ภาษาไทย
联系我们
登录
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTP
EngageLab 文档 >AppPush >REST API >创建推送 API
EngageLab 文档 >AppPush >REST API >创建推送 API

创建推送 API

最新更新：2024-05-08

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

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

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

请求频率限制

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

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

请求方式

POST

调用地址

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

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

POST v4/push
          POST 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": { "alert" :"Hello, Push!", "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": {
            "alert" :"Hello, Push!",
            "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 可选 客户自定义的可选字段，回调时返回给客户。最大不超过128个字符。

    from

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

    请求示例

    { "from":"push" }
              {
    "from":"push"
}
    此代码块在浮窗中显示

    to

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

    推送目标

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

    关键字 类型 含义 说明 备注
    all String 发广播 给全部设备进行推送 推送目标为365天内活跃过的设备。
    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 个。
    live_activity_id string 实时活动标识 字符串，对应 iOS SDK liveActivityId 的值 实时活动更新的时候必填

    数组里多个值之间隐含的关系是是 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":[
            "女",
            "会员"
        ]
    }
}
    此代码块在浮窗中显示

    推送实时活动

    { "to": { "live_activity_id": "LiveActivity-1" } }
                {
      "to": {
          "live_activity_id": "LiveActivity-1"
      }
  }
    此代码块在浮窗中显示

    body

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

    关键字 类型 选项 含义
    platform String 或 JSON Array 必填 推送平台
    notification JSON Object 可选
  • 通知内容体，是被推送到客户端的内容。
  • voip、message、notificatioin、live_activity任一消息不可与其他消息并存
    		•
    message JSON Object 可选
  • 消息内容体，是被推送到客户端的内容。
  • voip、message、notificatioin、live_activity任一消息不可与其他消息并存
    		•
    live_activity JSON Object 可选
  • 实时活动消息内容体，是被推送到客户端的内容。
  • voip、message、notificatioin、live_activity任一消息不可与其他消息并存
    		•
    voip JSON Object 可选
  • voip消息内容体，是被推送到客户端的内容。
  • voip、message、notificatioin、live_activity任一消息不可与其他消息并存
    		•
    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 时可用，目前支持 .JPEG(仅FCM通道) .BMP (仅FCM通道) .jpg 和 .png 格式的图片。
  • 支持网络图片 url、本地图片的 path，如果是 http／https 的 url，会自动下载；如果要指定开发者准备的本地图片就填 sdcard 的相对路径。
  • 支持 api 16 以上的 rom。
  • 图片大小上限是1MB。
    		•
    extras JSON Object 可选 扩展字段 这里自定义 JSON 格式的 Key/Value 信息，以供业务使用。
    intent JSON Object 可选 指定跳转页面(推荐) 使用intent字段中的URL指定单击通知栏后要跳转的目标页面。建议填写intent字段，否則单击通知可能無法指定跳转操作。此字段支持以下三种类型：
  • 跳转到目标页面：“intent：#Intent；action=action路径；component=包名/Activity全名；end”
  • 應用程序首頁：“intent：#Intent；action=android.intent.action.MAIN；end”（固定为此地址）
  • 跳转到深度链接地址：“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"
    }
  }
}
    此代码块在浮窗中显示

    live_activity

    注意：实时活动消息要求使用 iOS P8 证书，对应 WebPortal 集成设置中 iOS 鉴权方式需要选择「Token Authentication配置」方式。

    实时活动消息内容体，有如下字段信息：

    关键字 类型 选项 说明
    ios JSON Object 必填 详细字段参考下表iOS JSON Object 部分。

    iOS JSON Object

    关键字 类型 选项 说明
    event string 必填 创建：“start”，更新：“update”，结束："end"；必填
    attributes-type string 可选 实时活动类型，开发者自定义值，当event=start时该参数必填
    content-state JSON Object 必填 实时活动动态内容，需与客户端 SDK 值匹配（对应 Apple 官方的content-state 字段）。
    alert JSON Object 可选 参考下表iOS alert JSON Object 说明。
    dismissal-date int 可选 实时活动结束展示时间。
    attributes JSON Object 可选 实时活动静态内容，需与客户端 SDK 值匹配（对应 Apple 官方的attributes字段）。
    stale-date int 可选 实时活动显示过期时间，如果该时间小于当前时间，实时活动将不会更新
    relevance-score int 可选 实时活动在灵动岛上展示的优先级，取值[1,100],该值和实时活动的重要性呈正相关，不填默认为最高
    apns-priority int 可选 为5或10 ，不填默认为10。因为时候活动通知每小时是有频控限制的，apns-priority=5的通知将不消耗苹果厂商频控配额，当超出频控上限，推送通知将被限制

    iOS alert JSON Object

    关键字 类型 选项 说明
    title string 可选 显示到Apple Watch的消息标题。
    body string 可选 显示到Apple Watch的消息内容。
    sound string 可选 提示音。
    • iOS 实时活动消息（Live Activity） Engagelab Push 要转发给苹果服务器。苹果要求实时活动消息 （ActivityKit）远程推送的动态更新数据大小不超过 4096 字节。
    • Engagelab Push 因为需要重新组包，并且考虑一点安全冗余，要求 "live_activity" 参数体内 "iOS":{ } 及大括号内的总体长度不超过：3584 个字节。JPush 使用 utf-8 编码，所以一个汉字占用 3 个字节长度。

    实时活动推送示例

    实时活动使用的attributes-type和live_activity_id均来自开发者sdk上报，在使用实时活动前必须上报设备的push-to-start token和update-token，详细流程参考苹果厂商实时活动说明

    • 创建实时活动

      { "from": "push", "to": { "registration_id": [ "161a3797c816b134042" ] }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "start", "content-state": { "eventStr": "hello", "eventTime":1685952000 }, "attributes": { "name": "1", "number": 2, "tag": "mytag" }, "alert": { "title": "hello", "body": "welcome" }, "attributes-type": "my_la_type", "relevance-score": 100, "apns-priority": 100 } } }, "request_id": "12345678", "custom_args": "12345678" }
                {
    "from": "push",
   "to": {
        "registration_id": [
            "161a3797c816b134042"
        ]
    },
    "body": {
        "platform": "ios",
        "live_activity": {
            "ios": {
                "event": "start",
                "content-state": {
                    "eventStr": "hello",
                    "eventTime":1685952000
                },
                "attributes": {
                    "name": "1",
                    "number": 2,
                    "tag": "mytag"
                },
                "alert": {
                    "title": "hello",
                    "body": "welcome"
                },
                "attributes-type": "my_la_type",
                "relevance-score": 100,
                "apns-priority": 100
            }
        }
    },
    "request_id": "12345678",
    "custom_args": "12345678"
}
      此代码块在浮窗中显示

    • 更新实时活动

      { "from": "push", "to": { "live_activity_id": "my_la_id" }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "update", "content-state": { "eventStr": "test_live", "eventTime": 198 }, "alert": { "title": "123411", "body": "123411" } } } }, "request_id": "12345678", "custom_args": "12345678" }
                {
   "from": "push",
   "to": {
         "live_activity_id": "my_la_id"
    },
    "body": {
        "platform": "ios",
        "live_activity": {
            "ios": {
                "event": "update",
                "content-state": {
                    "eventStr": "test_live",
                    "eventTime": 198
                },

                "alert": {
                    "title": "123411",
                    "body": "123411"
                }
            }
        }
    },
    "request_id": "12345678",
    "custom_args": "12345678"
}
      此代码块在浮窗中显示

    voip

    iOS VOIP 功能。 该类型不支持和 iOS 的 其他消息类型并存，请求参数结构参考：

    { "from": "push", "to": { "registration_id": [ "1a0018970a91da03de5" ] }, "request_id": "12345", "custom_args": "12345", "body": { "platform": "ios", "voip": { "key": "value // 任意自定义 key/value 对，会透传给 APP" } } }
              {
    "from": "push",
    "to": {
        "registration_id": [
            "1a0018970a91da03de5"
        ]
    },
    "request_id": "12345",
    "custom_args": "12345",
    "body": {
        "platform": "ios",
        "voip": {
            "key": "value  // 任意自定义 key/value 对，会透传给 APP"
        }
    }
}
    此代码块在浮窗中显示

    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：代表系统消息。
    voice_value String 可选 语音文件值 多个参数用英文逗号隔开，带了#的表示需要解析的，没带的就直接默认匹配mp3文件。注意数值如果有小数点的，上传的文件名必须为point.mp3。目前支持的语言包括 "en"（英语）、"zh-Hans"（简体中文）和 "zh-Hant"（繁体中文）。如果推送内容的指定语言没有匹配上对应的语言规则，则该推送内容不会转为语音播报。
    enhanc_message Bool 可选 启启用通知消息增强显示 false-关闭，true-开启。如果通知权限被关闭，启用此功能后，当用户在前台运行 APP 时，会通过应用内消息的方式展示原本通知栏中的消息内容。此功能的默认值为 false，只有在明确开启时才会生效。

    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 手机厂商通知栏消息分类，由开发者自行向手机厂商申请，具体申请规则参考：厂商消息分类使用指南 。
  • 注意华为数据处理位置为中国区的应用不支持该字段，详情参见 华为自定义通知渠道 。
  • android 下也有 channel_id 字段，若本字段有填充，则优先使用，若无填充则以 android.channel_id 的定义为准。
  • 特别注意：由于 OPPO 厂商 2024.11.20 实施OPPO消息分类新规，建议您同时填写此字段和下面的category、notify_level字段。
    		•
    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 可选 华为厂商自定义消息场景标识 为了适配华为、vivo、OPPO 手机厂商消息，用于标识「云端通知」消息类型，确定消息提醒方式，对特定类型消息加快发送。
  • 对应值及其说明参考：华为 category 值说明 、vivo 分类标准。
  • oppo category 值说明
  • 说明1：华为需完成 自分类权益申请 。
  • 说明2：华为从 2023.09.15 开始基于《华为消息分类标准》对其云端通知和本地通知进行共同管控推送，开发者通过EngageLab服务发起推送时，请注意此字段传值要符合华为官方「华为云端通知 category」取值要求。
  • 说明3：vivo 具体规则参考 vivo 官方说明。
  • 说明4：OPPO于2024.11.20实施消息分类新规，具体规则参考 OPPO 官方说明。
    		•
    notify_level Int 可选 OPPO通知栏消息提醒等级
  • 官方取值定义：1-通知栏、2-通知栏+锁屏、16-通知栏+锁屏+横幅+震动+铃声；请开发者按照官网定义传递，EngageLab仅做透传处理。
  • 根据官方说明 notify_level 字段，仅对「服务与通讯类」消息生效。
  • 使用notify_level参数时，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 必选 错误详情
    { "error":{ "code": 3002, "message": "Push.template field must be set correctly when type is template" } } 
              {
    "error":{
    "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
    21050 live_activity event参数错误 event参数必须为“start”，“update”、"end" 400
    21051 live_activity audience参数错误 实时活动创建时，推送目标只能是广播或者reg推送 400
    21052 live_activity attributes-type参数错误 event=start时，attributes-type不允许为空 400
    21053 live_activity content-state参数错误 content-state不允许为空 400
    21054 live_activity 参数错误,不允许同时通知和自定义消息 voip、message、notificatioin、live_activity不能并存 400
    21055 live_activity ios非p8证书 实时活动仅支持p8证书 400
    21056 live_activity 仅支持ios平台 platform参数必须是ios 400
    21057 voip 消息不允许和其他消息类型并存 voip、message、notificatioin、live_activity不能并存 400
    21058 voip 仅支持ios平台 platform参数必须是ios 400
    21059 参数错误 该消息类型不支持 big_push_duration 401
    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
    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
    在文档中心打开
    icon
    联系销售