MobPush REST API 概述

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

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

频率控制
详情参见推送限制策略的 接口限制 说明。

调用地址
POST http://api.push.mob.com/v3/push/createPush
推送对象
以 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：财务
  DEVICE_REMINDER：设备提醒
  SYSTEM_REMINDER：系统提示
  MAIL：邮件
  PLAY_VOICE：语音播报（仅透传消息支持）
  MARKETING：内容推荐、新闻、财经动态、生活资讯、社交动态、调研、产品促销、功能推荐、运营活动（仅对内容进行标识，不会加快消息发送）
  作用二：申请特殊权限后，用于标识高优先级透传场景，取值如下：
  VOIP：音视频通话
  PLAY_VOICE：语音播报
  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"
}

}