![](https://s5-media.51cto.com/ost/pc/static/noavatar.gif)
MobPush REST API的推送 API之创建推送 原创
向某单个设备或者某设备列表推送一条通知、消息。
推送的内容只能是 JSON 表示的一个推送对象。
调用验证
详情参见 REST API 概述的 鉴权方式 说明。
频率控制
详情参见推送限制策略的 接口限制 说明。
调用地址
推送对象
- 以 JSON 格式表达,表示一条推送相关的所有信息
参数 | 类型 | 必须 | 说明 |
workno | string | 否 | 自定义任务id,默认由MobTech自动生成,无需传递(需保证唯一性) |
source | string | 是 | 固定值webapi |
appkey | string | 是 | MobTech提供的AppKey |
pushTarget | object | 是 | 推送目标 |
pushTarget.target | number | 是 | 推送目标类型 - 1:广播 - 2:别名(alias) - 3:标签(tags) - 4:rid - 5:地理位置(city) - 6:用户分群 - 9:复杂地理位置推送(pushAreas) - 14:fileid推送 |
pushTarget.alias | string [] | target等于2时必填 | 推送别名集合,集合元素限制1000个以内。 例:["alias1","alias2"] |
pushTarget.tags | string [] | target等于3时必填 | 推送标签集合,集合元素限制1000个以内。 例:["tag1","tag2"] |
pushTarget.tagsType | number | 否 | 标签组合方式,target等于3时可用 - 1:并集 - 2:交集 - 3:补集(暂未实现) 不填默认值为 - 1:并集 |
pushTarget.rids | string[] | target等于4时必填 | 推送rid集合,集合元素限制1000个以内。 例:["id1","id2"] |
pushTarget.city | string | target等于5时可选,且city、province、country 必选一个不为空 | 推送地理位置的城市 例:上海市 |
pushTarget.province | string | target等于5时可选,且city、province、country 必选一个不为空 | 推送地理位置的省份 例:浙江省 |
pushTarget.country | string | target等于5时可选,且city、province、country 必选一个不为空 | 推送地理位置的国家 例:中国 |
pushTarget.block | string | target等于6时必填 | 用户分群ID 注:该功能暂未实现 |
pushTarget.pushAreas | object | target等于9时必填 | 复杂地理位置 |
pushTarget.pushAreas.countries | object [] | 是 | 国家列表 |
pushTarget.pushAreas.countries.country | string | 是 | 国家名称 |
pushTarget.pushAreas.countries.provinces | object [] | 否 | 指定需要推送的省份列表 |
pushTarget.pushAreas.countries.provinces.province | string | 是 | 省份名称 |
pushTarget.pushAreas.countries.provinces.cities | string [] | 否 | 需要推送的城市列表 |
pushTarget.pushAreas.countries.provinces.excludeCities | string [] | 否 | 指定不需要推送的城市列表,当指定[cities]时,这个字段不起作用 |
pushTarget.pushAreas.countries.provinces.excludeProvinces | string [] | 否 | 指定不需要推送的省份列表,当设置[provinces]时,这个不起作用 |
pushTarget.fileId | string | target等于14时必填 | fileid |
pushTarget.appPackages | string [] | 否 | 指定推送的包名列表,如不填则使用默认包名进行推送 |
pushNotify | object | 是 | 推送展示细节配置 |
pushNotify.plats | number [] | 是 | 推送生效渠道 - 1:android - 2:iOS - 8:harmony 例:[1, 2, 8] |
pushNotify.iosProduction | number | plats数组值含有2时可选 | iOS环境 - 0:测试环境 - 1:生产环境(默认) |
pushNotify.offlineSeconds | number | 否 | 离线消息保存时间,单位:秒,默认值为86400,离线时间设置必须大于等于5分钟。 注:魅族厂商的离线保留时间范围是1~72小时,设置的离线保留时间如超出该范围将会导致消息无法使用魅族厂商通道,其他厂商不受影响 |
pushNotify.content | string | 是 | 推送内容 注1:内容长度超过厂商限制会被截断。 注2:vivo不支持纯表情。 |
pushNotify.title | string | 否 | 通知标题 注1:默认通知标题为应用名称 注2:标题长度超过厂商限制会被截断 注3:vivo不允许纯表情 |
pushNotify.type | number | 是 | 推送类型 - 1:通知 - 2:自定义 |
pushNotify.customParamSwitch | boolean | 否 | 是否开启个性化参数,默认为false 注:开启后,pushNotify.content参数支持${{}}个性化通知占位符 |
pushNotify.customParamDefaultContent | string | 否 | 个性化参数默认内容,${{}}个性化通知占位符无法替换时会使用。 注:开启个性化参数时必填 |
pushNotify.androidNotify | object | 否 | Android通知消息对象 |
pushNotify.androidNotify.content | string [] | 否 | 推送内容,配合style参数使用,默认: 0 - style=0 不生效 - style=1 部分机型可以生效覆盖 - style=2 传入图片链接,部分低版本手机不支持 - style=3 对应传入文字内容 |
pushNotify.androidNotify.customStyle | object | 否 | 自定义样式 |
pushNotify.androidNotify.customStyle.styleNo | integer | 否 | 样式序号 - 1:样式1 - 2:样式2 - 3:样式3 |
pushNotify.androidNotify.customStyle.backgroundUrl | string | 否 | 背景图Url |
pushNotify.androidNotify.customStyle.smallIcons | string | 否 | 小图标 |
pushNotify.androidNotify.customStyle.buttonCopy | string | 否 | 按钮文案 |
pushNotify.androidNotify.customStyle.buttonJumpUrl | string | 否 | 点击按钮跳转的链接 |
pushNotify.androidNotify.warn | string | 否 | 提醒类型,可多选组合 - 1:提示音 - 2:震动 - 3:指示灯 例:12(提示音+震动) |
pushNotify.androidNotify.style | integer | 否 | 显示样式标识 - 0:默认 - 1:长内容 - 2:大图 - 3:横幅 - 4:自定义样式 |
pushNotify.androidNotify.sound | string | 否 | 自定义声音 |
pushNotify.androidNotify.icon | string | 否 | 附带小图标的推送 注1:icon和image只能二选一,同时传输则取icon中的数据 注2:目前客户端版本暂不支持 |
pushNotify.androidNotify.image | string | 否 | 推送大图标的url地址 注1:icon和image只能二选一,同时传输则取icon中的数据 注2:透传消息不支持 注3:小米厂商对图片尺寸有严格要求,不符合要求则不会按照大图样式进行推送,具体要求为:宽高固定为876*324px,格式需为PNG/JPG/JPEG,大小小于1M 注4:OPPO厂商大图需要申请权限,否则会报错导致客户端收不到推送消息 |
pushNotify.androidNotify.androidChannelId | string | 否 | 安卓通知渠道ID 注:当输入该参数后,MobPush通道和厂商通道都会使用该channelId;当androidChannelId 和 pushFactoryExtra中的channelId同时使用填写时,那MobPush通道使用androidChannelId,厂商通道使用pushFactoryExtra中设置的channelId |
pushNotify.androidNotify.androidBadgeType | number | 否 | 角标类型 - 1:角标数值取androidBadge值 - 2:角标数值为androidBadge当前值加1 注:透传消息不支持 |
pushNotify.androidNotify.androidBadge | number | 否 | 角标数值 |
pushNotify.androidNotify.notifyRepeat | object | 否 | 消息重弹配置项 |
pushNotify.androidNotify.notifyRepeat.repeatSwitch | integer | 是 | 重弹开关可取值: - 0:关闭 - 1:开启 |
pushNotify.androidNotify.notifyRepeat.repeatTimes | integer | 是 | 重弹次数,可取值:1 - 5 |
pushNotify.androidNotify.notifyRepeat.repeatInterval | integer | 是 | 重弹时间间隔,单位:秒,可取值:5~86400 |
pushNotify.androidNotify.nativeCategory | string | 否 | TCP消息类别,当前仅华为机型支持可选枚举值: promo 营销推广 recommendation 内容推荐 social 社交动态 call 通话 email 邮件 msg 即时聊天 navigation 导航 reminder 事项提醒 service 财务 alarm 闹钟/计时器 stopwatch 秒表 progress 进度 location_sharing 位置共享 注:参数为空时,默认赋值为:promo |
pushNotify.harmonyNotify | object | 否 | harmony通知消息对象 |
pushNotify.harmonyNotify.title | string | 否 | 如果不设置,则默认的通知标题为应用的名称 |
pushNotify.harmonyNotify.style | number | 否 | 类型 - 1: 默认通知 - 5: 多行文本样式 |
pushNotify.harmonyNotify.content | string [] | 否 | content: style样式具体内容 |
pushNotify.harmonyNotify.image | string | 否 | 推送大图标的url地址 |
pushNotify.harmonyNotify.group | string | 否 | 组通知名称 |
pushNotify.harmonyNotify.label | string | 否 | 通知标签 |
pushNotify.harmonyNotify.additionalText | string | 否 | 通知附加内容,是对通知内容的补充 |
pushNotify.harmonyNotify.briefText | string | 否 | 通知概要内容,是对通知内容的总结 |
pushNotify.harmonyNotify.expandedTitle | string | 否 | 通知展开时的标题 |
pushNotify.harmonyNotify.slotType | integer | 否 | 渠道类型 - 0:未知类型 - 1:社交类型 - 2:服务类型 - 3:内容类型 - 4:实况类型 - 5:客户服务类型 - 65535:其他类型 |
pushNotify.harmonyNotify.badge | integer | 否 | 角标 |
pushNotify.iosNotify | object | 否 | iOS通知消息对象 |
pushNotify.iosNotify.badge | number | 否 | 角标 |
pushNotify.iosNotify.badgeType | number | 否 | badge类型 - 1:绝对值 不能为负数 - 2增减(正数增加,负数减少),减到0以下会设置为0 |
pushNotify.iosNotify.category | string | 否 | APNs的category字段,只有IOS8及以上系统才支持此参数推送 |
pushNotify.iosNotify.sound | string | 否 | APNs通知,通过这个字段指定声音,默认为default(系统默认声音),如设置为空值则为静音。如设置为其他字符,则需要您的应用中配置了该声音才可以正常发声。 |
pushNotify.iosNotify.subtitle | string | 否 | 副标题 |
pushNotify.iosNotify.slientPush | number | 否 | 如果只携带content-available: 1,不携带任何badge,sound 和消息内容等参数, 则可以不打扰用户的情况下进行内容更新等操作即为“Silent Remote Notifications” |
pushNotify.iosNotify.contentAvailable | number | 否 | 将该键设为 1 则表示有新的可用内容。带上这个键值,意味着你的 App 在后台启动了或恢复运行了,application:didReceiveRemoteNotification:fetchCompletionHandler:被调用了 |
pushNotify.iosNotify.mutableContent | number | 否 | - 1 使用富文本 - 0 不设置 注:默认为0,配合attachmentType 和attachment使用 |
pushNotify.iosNotify.attachmentType | number | 否 | 富文本类型 - 0:无 - 1:图片 - 2:视频 - 3:音频 |
pushNotify.iosNotify.attachment | string | 否 | ios富文本内容 |
pushNotify.taskCron | number | 否 | 是否是定时消息 - 0:否(默认) - 1:是 |
pushNotify.taskTime | number | taskCron=1时必填 | 定时消息发送时间,单位:毫秒时间戳 例:1594277916000 |
pushNotify.speed | number | 否 | 每秒推送速率的趋势,默认为0(代表不开启) |
pushNotify.skipOnline | number | 否 | 是否跳过在线设备 - 1:跳过 - 0:不跳过(默认) |
pushNotify.skipFactory | number | 否 | 是否跳过厂商通道 - 1:跳过 - 0:不跳过(默认) |
pushNotify.policy | number | 否 | 推送策略 - 1:先走tcp,再走厂商 - 2:先走厂商,再走tcp - 3:只走厂商 - 4:只走tcp - 5:设备亮屏推送 注:厂商透传只支持策略3或4 |
pushNotify.extrasMapList | object [] | 否 | 附加参数列表 例:{"key1":"value1","key2":"value2",…} |
pushOperator | object | 否 | 运营保障相关配置 |
pushOperator.dropType | number | 否 | 运营保障消息修改类型,推荐使用专用接口进行操作 - 1:取消 - 2:替换 - 3:撤回 |
pushOperator.dropId | string | 是 | 推送任务的唯一ID |
pushForward | object | 否 | link 相关打开配置 |
pushForward.url | string | 否 | link跳转 moblink功能的的uri |
pushForward.scheme | string | 是 | scheme moblink功能的的scheme |
pushForward.schemeDataList | object [] | 否 | scheme参数 例:{"key1":"value1","key2":"value2",…} |
pushForward.nextType | integer | 否 | 后续动作 - 0:打开首页 - 1:link跳转 - 2:scheme 跳转 - 3:Intent |
pushForward.intentUrl | string | 否 | Intent页面地址 |
harmonyForward | object | 否 | 备注: 鸿蒙跳转相关 |
harmonyForward.nextType | integer | 后续操作类型 - 0: 打开首页 - 4: 打开应用自定义页面 | |
harmonyForward.uri | string | 否 | 打开应用自定义页面的uri |
harmonyForward.action | string | 否 | nextType=4,uri与action至少填1个 |
harmonyForward.abilityName | string | 否 | 页面名称 |
harmonyForward.entities | string[] | 否 | 标识能够接收的Entity值的集合。 |
harmonyForward.bundleName | string | 否 | 包名 |
pushCallback | object | 否 | 推送回调配置 |
pushCallback.url | string | 否 | 回调地址点击查看详情 |
pushCallback.params | object | 否 | JSON对象自定义参数 例: { "key": "value" } |
reportCallback | object | 否 | 厂商回调配置 |
reportCallback.url | string | 否 | 回调地址点击查看详情 |
pushFactoryExtra | object | 否 | 厂商特殊配置 |
pushFactoryExtra.huaweiExtra | object | 否 | 华为厂商特殊配置 |
pushFactoryExtra.huaweiExtra.importance | string | 否 | 消息类型 - LOW:资讯营销类 - NORMAL:服务与通讯类 注:资讯营销类的消息提醒方式为静默通知,仅在下拉通知栏展示。 服务与通讯类的消息提醒方式为锁屏+铃声+震动 |
pushFactoryExtra.huaweiExtra.category | string | 否 | 作用一:完成自分类权益申请后,用于标识消息类型,确定消息提醒方式,对特定类型消息加快发送,取值如下: IM:即时聊天 VOIP:音视频通话 SUBSCRIPTION:订阅 TRAVEL:出行 HEALTH:健康 WORK:工作事项提醒 ACCOUNT:帐号动态 EXPRESS:订单&物流 FINANCE:财务 DEVICEREMINDER:设备提醒 MAIL:邮件 PLAYVOICE:语音播报(仅透传消息支持) |
pushFactoryExtra.xiaomiExtra | object | 否 | 小米厂商特殊配置 |
pushFactoryExtra.xiaomiExtra.channelId | string | 否 | 小米渠道Id 适配定制化渠道 |
pushFactoryExtra.oppoExtra | object | 否 | OPPO厂商特殊配置 |
pushFactoryExtra.oppoExtra.channelId | string | 否 | OPPO渠道Id 适配定制化渠道 |
pushFactoryExtra.vivoExtra | object | 否 | VIVO厂商特殊配置 |
pushFactoryExtra.vivoExtra.classification | int | 否 | VIVO消息类型 - 0:运营类型消息 - 1:系统类型消息 |
pushFactoryExtra.vivoExtra.category | string | 否 | 二级分类,传值参见二级分类标准中category说明 1、填写category后,可以不填写classification、messageSort,但若填写classification、messageSort,请保证category与messageSort或classification是正确对应关系,否则返回错误码10097; 2、赋值请按照消息分类规则填写,且必须大写;若传入错误无效的值,否则返回错误码10096; |
pushFactoryExtra.honorExtra | object | 否 | 荣耀厂商特殊配置 |
pushFactoryExtra.honorExtra.importance | string | 否 | 消息类型 - LOW:资讯营销类 - NORMAL:服务与通讯类 注:资讯营销类的消息默认展示方式为静默通知,仅在下拉通知栏展示。 服务与通讯类的消息默认展示方式为锁屏展示+下拉通知栏展示 |
userExtra | object | 否 | 用于解释推送任务的字段扩充 |
userExtra.pushWorkDesc | string | 否 | 推送任务的解释说明,由用户设置 |
userExtra.activityTask | integer | 否 | 活动任务 - 0:不是活动任务(默认) - 1:是活动任务 |
userExtra.activityWorkId | string | activityTask为1时必传 | 活动ID,不能超过20个字符,且唯一不可重复 |
groupId | string | 否 | AB分组测试ID |
请求示例
curl --location --request POST 'http://api.push.mob.com/v3/push/createPush' \
--header 'Content-Type: application/json' \
--header 'key: 2f2d7a68f8a40' \
--header 'sign: eb276f35cf6480169b2d3e2e509db680' \
--data-raw '{"source":"webapi","appkey":"2f2d7a68f8a40","pushTarget":{"target":1},"pushNotify":{"plats":[1],"content":"推送的内容","type":1}}'
响应示例
- 请求成功
{
"status": 200,
"res": {
"batchId": "4bp4tw9ttc06xgch6o",
"fetched": null,
"uninstalls": null,
"closes": null,
"notFounds": null
},
"error": null
}
- 请求失败
{
"status": 5801,
"res": null,
"error": "数据校验失败"
}
- 响应参数
参数 | 类型 | 说明 |
status | int | 返回码 |
res | object | 消息体 |
res.batchId | string | 本次推送的任务ID |
error | string | 返回码描述 |
调用示例
推送广播
{
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 1
},
"pushNotify": {
"plats": [
1
],
"content": "推送的内容",
"type": 1
}
}
推送广播并附加参数
{
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 1
},
"pushNotify": {
"plats": [
1,
2
],
"content": "推送的内容",
"type": 1,
"iosProduction": 0,
"extrasMapList": [
{
"key": "ContentTypeasd",
"value": "personal_chat"
}
]
}
}
推送标签
{
"source": "webapi",
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 3,
"tags": [
"男",
"上海",
"老师"
]
},
"pushNotify": {
"plats": [
1
],
"content": "推送的内容",
"type": 1
}
}
推送别名
{
"source": "webapi",
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 2,
"alias": [
"alias_1",
"alias_2"
]
},
"pushNotify": {
"plats": [
1
],
"content": "推送的内容",
"type": 1
}
}
推送RegisterID
{
"source": "webapi",
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 4,
"rids": [
"c262bac10d05ec1c9b04126d"
]
},
"pushNotify": {
"plats": [
1
],
"content": "推送的内容",
"type": 1
}
}
自定义消息(透传消息)
{
"source": "webapi",
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 1
},
"pushNotify": {
"plats": [
1
],
"content": "推送内容",
"type": 2,
}
}
Android通知大图模式
{
"source": "webapi",
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 1
},
"pushNotify": {
"plats": [
1
],
"content": "推送内容",
"type": 1,
"androidNotify": {
"content": [
"Android推送内容1",
"Android推送内容2"
],
"style": 2
}
}
}
Android通知横幅模式
{
"source": "webapi",
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 1
},
"pushNotify": {
"plats": [
1
],
"content": "推送内容",
"type": 1,
"androidNotify": {
"content": [
"Android推送内容1",
"Android推送内容2"
],
"style": 3
}
}
}
Android通知自定义声音
音频文件放到项目res/raw目录下,只需传音频文件的文件名
{
"source": "webapi",
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 1
},
"pushNotify": {
"plats": [
1
],
"content": "推送内容",
"type": 1,
"androidNotify": {
"content": [
"Android推送内容1",
"Android推送内容2"
],
"style": 2,
"warn": "1",
"sound": "warn",
"androidChannelId": "channelId"
}
}
}
跳转首页并传递附加参数
{
"source": "webapi",
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 1
},
"pushNotify": {
"plats": [
1
],
"content": "推送内容",
"type": 1,
"androidNotify": {
"content": [
"Android推送内容1",
"Android推送内容2"
],
"style": 2,
"warn": "1",
"sound": "warn"
},
"extrasMapList": [
{
"key": "extrakey",
"value": "extravalue"
}
]
},
"pushForward": {
"nextType": 0
}
}
跳转到指定界面并且传递携带scheme数据
{
"source": "webapi",
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 1
},
"pushNotify": {
"plats": [
1
],
"content": "推送内容",
"type": 1,
"androidNotify": {
"content": [
"Android推送内容1",
"Android推送内容2"
],
"style": 2,
"warn": "1",
"sound": "warn"
}
},
"pushForward": {
"nextType": 2,
"scheme": "mlink://com.mob.mobpush.linkone",
"schemeDataList": [
{
"key": "schemekey",
"value": "schemevalue"
}
]
}
}
打开网页
{
"source": "webapi",
"appkey": "moba6b6c6d6",
"pushTarget": {
"target": 1
},
"pushNotify": {
"plats": [
1
],
"content": "推送内容",
"type": 1,
"androidNotify": {
"content": [
"Android推送内容1",
"Android推送内容2"
],
"style": 2,
"warn": "1",
"sound": "warn"
}
},
"pushForward": {
"nextType": 1,
"url": "http://www.mob.com"
}
}
![](https://s5-media.51cto.com/ost/pc/static/noavatar.gif)