Push API v4

最新更新:2023-11-16

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

推送的内容只能是 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 https://webpush.api.engagelab.cc/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 个。

    请求示例

    • 推送给全部(广播):
    { "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
    Turkish th
    Vietnamese vi
    Indonesian id
    Norwegian no
    Swedish sv
    Polish pl
    Turkish tr
    Hebrew he
    在文档中心打开
    Contact Sales