创建推送 API

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

请求频率限制

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

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

请求方式

POST

调用地址

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

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

          POST v4/push

        

调用验证

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

请求示例

请求头

          > 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 类型，可选字段。

请求示例

          {
    "from":"push"
}

        

to

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

推送目标

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

示例

• 推送给全部（广播）：

          {
  "to": "all",
}

        

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

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

        

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

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

        

• 推送给多个别名：

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

        

• 推送给多个注册ID：

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

        

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

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

        

推送实时活动

            {
      "to": {
          "live_activity_id": "LiveActivity-1"
      }
  }

        

body

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

platform

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

推送到所有平台：

          { "platform" : "all" }

        

指定特定推送平台：

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

        

notification

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

alert

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

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

        

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

android

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

          {
    "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://pushapi-sgp.engagelab.com/largeIcon.jpg",
            "small_icon": "http://www.small.com/small_icon.jpg",
            "intent": {
                "url": "intent:#Intent;component=pushapi-sgp.engagelab.com/com.example.mtpushdemo.SettingActivity;end"
            },
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

        

ios

iOS 平台上 APNs 通知。

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

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

服务端发送示例：

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

        

message

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

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

支持的字段如下：

示例：

          {
  "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 alert JSON Object

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

        

options

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

multi_language

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

请求参数

请求示例

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

        

返回示例

          成功时：
{
   
}

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

        

third_party_channel

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

请求参数

为统一多厂商通道策略并简化配置逻辑，现对 distribution_new 字段的配置方式做如下调整，您的旧厂商级配置仍可继续生效，但建议逐步迁移至全局配置以规避未来兼容风险。（2025.04.03起执行下列新规则）：

• 配置优先级（新规则）
  • 第一优先级：全局配置 third_party_channel.distribution_new（推荐新方式）
    示例："distribution_new": "pns_mtpush"
  • 第二优先级：厂商级配置 third_party_channel.{厂商key}.distribution_new（兼容旧方式）
    仅当全局配置未设置时生效
  • 无配置时：使用默认策略：pns_mtpush

请求示例

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

        

request_id

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

请求示例

          {
      "request_id":"12345678"
}

        

返回示例

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

        

custom_args

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

请求示例

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

        

返回参数

成功返回

          < HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id":"18","msg_id":"1828256757"}

        

失败返回

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

          {
    "error":{
    "code": 3002,
    "message": "Push.template field must be set correctly when type is template"
    }
}

        

调用返回

HTTP 状态码

参考文档：HTTP-Status-Code

错误码

推送限制

多语言码