Push API v4
向某单个设备或者某设备列表推送一条通知、或者消息。
推送的内容只能是 JSON 表示的一个推送对象。
标签/别名相关功能参考AppPushAPI即可。
info 这是 Push API 最近的版本。v4 版本的改进为:
- 使用 HTTP Basic Authentication 的方式做访问授权。这样整个 API 请求可以使用常见的 HTTP 工具来完成,比如:curl,浏览器插件等。
- 推送内容完全使用 JSON 的格式。
调用验证
详情参见 REST API 概述的 鉴权方式 说明。
调用地址
POST https://webpush.api.engagelab.cc/v4/push
请求示例
请求头
> 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 | String | 可选 | 当前业务发送方 |
to | String 或 JSON Object | 必填 | 发送目标 |
body | JSON Object | 必填 | 发送请求体 |
platform | String 或 JSON Array | 必填 | 推送平台 |
notification | JSON Object | 可选 | |
message | JSON Object | 可选 | |
options | JSON Object | 可选 | 推送参数 |
request_id | String | 可选 | 客户自定义的可选字段,客户用来标识是哪条请求,响应时返回。 |
custom_args | JSON Object | 可选 | 客户自定义的可选字段,回调时返回给客户。 |
from
当前业务发送方,String 类型,可选字段。
请求示例
{
"from":"push"
}
to
推送设备对象,表示一条推送可以被推送到哪些设备列表。确认推送设备对象,MTPush 提供了两种方式,分别是注册ID和广播。
推送目标
关键字 | 类型 | 含义 | 说明 | 备注 |
---|---|---|---|---|
all | String | 发广播 | 给全部设备进行推送 | 推送目标为30天内活跃过的设备。 |
registration_id | JSON Array | 注册ID | 数组。多个注册ID之间是 OR 关系,即取并集。 | 设备标识。一次推送最多 1000 个。 |
请求示例
- 推送给全部(广播):
{
"to": "all",
}
- 推送给多个注册ID:
{
"to": {
"registration_id": [
"4312kjklfds2",
"8914afd2",
"45fdsa31"
]
}
}
body
发送请求体。支持的字段如下:
关键字 | 类型 | 选项 | 含义 |
---|---|---|---|
platform | String 或 JSON Array | 必填 | 推送平台 |
notification | JSON Object | 可选 | |
message | JSON Object | 可选 | |
options | JSON Object | 可选 | 推送参数 |
platform
MTPush 当前仅支持 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"
}
}
}
}
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"
}
}
}
options
推送可选项。当前包含如下几个可选项:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
time_to_live | Int 或 String | 可选 | 离线消息保留时长(秒) | |
override_msg_id | Long | 可选 | 要覆盖的消息 ID | 如果当前的推送要覆盖之前的一条推送,这里填写前一条推送的 msg_id 就会产生覆盖效果,即: |
big_push_duration | Int | 可选 | 定速推送时长(分钟) | |
web_buttons | JSON Object | 可选 | 在通知消息上添加buttons | |
third_party_channel | JSON Object | 可选 | Web 系统通道配置信息 | 仅针对配置了系统通道的用户有效参数详情查看 third_party_channel 说明。 |
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"}
third_party_channel
本字段用来填写 Web 系统通道的个性化信息,key 名称为 w3push ,value 值为一个Json Object 对象,该对象里面仅包含一个可选的 distribution 字段,类型为 String
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
distribution | 必选 | String | Engagelab 和系统通道并存时,设置下发优先级 | 取值不能为空字符串。 |
调用示例如下:
{
"third_party_channel":{
"w3push":{
"distribution":"mtpush"
}
}
}
request_id
请求 id,客户自定义的可选字段。客户用来标识是哪条请求,响应时返回。
请求示例
{
"request_id":"12345678"
}
返回示例
custom_args
客户自定义的,可选字段,响应时不返回,回调时返回。
{
"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 状态码为 4xx 或者 5xx,响应体包含字段如下:
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
code | int | 必选 | 错误码,详见 错误码 说明 |
message | String | 必选 | 错误详情 |
{
"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 个英文字符) | 暂无 |