PushTask

更新时间:
复制为 MD 格式

名称

类型

描述

示例值

object

推送任务对象

Action

string

推送方式。可选参数,默认为 PUSH_IMMEDIATELY(立即推送)。

重要

批量推送接口 CreateMassPushTask 仅支持以下推送方式:

  • PUSH_IMMEDIATELY(立即推送)

  • SCHEDULED_PUSH(定时推送)

PUSH_IMMEDIATELY

Target

object

指定消息推送的目标对象。当操作类型ActionCREATE_CONTINUOUS_PUSH(创建连续推送任务)时,此参数为可选。

Type

string

推送目标类型。

重要

批量推送接口 CreateMassPushTask 和 持续推送 CONTINUOUS_PUSH 仅支持以下三种目标类型:

  • DEVICE(设备)

  • ACCOUNT(账号)

  • ALIAS(别名)

DEVICE

Value

string

根据 Target.Type 设置推送目标,多个目标以逗号分隔。目标类型及目标值详细说明如下:

说明
  • DEVICE:设备 ID,如 deviceid1,deviceid2,最多 1000 个。

  • ACCOUNT:账号 ID,如 account1,account2,最多 1000 个。

  • ALIAS:别名,如 alias1,alias2,最多 1000 个。

  • TAG:支持单个或多个标签,格式参见标签格式规范

  • ALL:全量推送,无需设置值,全推可能会导致费用增加,请您酌情使用。

value

Platform

string

平台类型,可选参数。

IOS

Message

object

发送给设备的透传消息数据。总长度不超过 4000 字节。

说明

长度计算说明

  • 长度计算基于 Message 对象经过 JSON 序列化后,使用 UTF-8 编码的字符串字节长度。

  • 中文字符在 UTF-8 编码下通常占用 3 个字节

Title

string

发送的消息标题。

title

Body

string

发送的消息内容。

{"key": "value"}

Notification

object

发送给设备的厂商通知数据。

重要

当同时设置了 MessageNotification 时,设备只会收到一个,发送规则如下:

  • 当设备在线,透传消息数据;

  • 当设备离线,发送系统通知;

Title

string

推送的通知标题。

说明

长度限制如下:

  • iOS/Harmony 限制字节长度不超过 200

  • Android 限制字符长度不超过 50

您有一条新消息

Body

string

推送的通知内容。

说明

长度限制如下:

  • iOS/Harmony/Android 限制字符长度不超过 200

尊敬的客户,您好!您的预约订单已取消成功。

Ios

object

iOS 通知配置

Subtitle

string

iOS 通知副标题内容。

请查收订单。

Music

string

iOS 通知声音。指定存放在 app bundle 或沙盒 Library/Sounds 目录下的音频文件名,请参见: iOS 推送如何设定通知声音

说明
  • 若指定为空串(””),通知为静音

  • 若不设置,默认填充 default 为系统提示音

default

Badge

integer

iOS 应用角标。

1

BadgeAutoIncrement

boolean

是否开启角标自增功能,可选参数,默认为 false。

说明
  • 不可和角标设定参数一起使用

  • 角标自增功能由阿里云推送服务器维护每个设备的角标计数,需使用 1.9.5 以上版本的 SDK,通过 SDK 主动同步角标数字到服务端

false

Silent

boolean

控制是否启用静默推送模式。

说明
  • 发送静默通知,可不填 titlebody 参数

false

Mutable

boolean

启用扩展通知,控制 iOS 通知是否支持 Notification Service Extension 处理。

说明
  • 当发送静默通知时,必须设置为 true

  • Extension 处理时间不能超过 30 秒

  • 超时会导致通知显示原始内容

  • 需要在应用中添加 Notification Service Extension

true

Category

string

指定 iOS 通知的类别标识符,用于定义通知的交互行为和展示样式。

说明
  • Category 需要在 App 中预先注册才能生效。

  • 不同的 Category 可以定义不同的操作集合。

MESSAGE_REPLY

CollapseId

string

用于控制通知合并的唯一标识符,相同标识的通知将被覆盖显示。

order_status_update_12345

ThreadId

string

iOS 通知分组的线程标识符,用于将相关通知归类折叠显示。

说明
  • 相同 thread-id 的通知会自动分组显示

  • 多条相关通知折叠为一个通知组

  • 用户可展开查看组内所有通知

news_category_tech

InterruptionLevel

string

中断级别,可选参数,枚举值如下:

  • passive:系统在不点灯、不播放声音的情况下将通知添加到通知列表中。

  • active:系统立即显示通知,点亮屏幕,并可以播放声音。

  • time-sensitive:系统立即呈现通知,点亮屏幕,并可以播放声音,但不会突破系统通知控制。

  • critical:系统立即显示通知,屏幕亮起,并绕过静音开关播放声音。

active

RelevanceScore

number

通知消息的相关性评分,用于控制通知的优先级和展示策略。

0.5

ExtParameters

string

iOS 通知的自定义扩展属性。

说明
  • 参数必须以标准的 JSON Map 格式传入,格式错误将导致解析失败。

{"attachment": "https://xxxx.xxx/notification_pic.png"}

LiveActivity

object

灵动岛参数对象。

重要
  • 灵动岛推送仅支持按照 DEVICE 类型单台设备进行推送

  • 推送灵动岛时,可不填 title 和 body 参数

Id

string

Live Activity 的唯一标识符,用于关联设备端活动实例与服务端推送目标。

重要
  • ID 必须与客户端 SDK 中 registerLiveActivityPushToken 方法的 forActivityId 参数保持一致

  • 服务端推送时使用此 ID 定位具体的活动实例

FOOD_DELIVERY_ORD20231201001

Event

string

启动、更新、结束实时活动。

start

AttributesType

string

待启动的 Live Activity 类型。

说明

Event 为 start 时必填

OrderActivityAttributes

Attributes

string

iOS 灵动岛(Live Activities)推送的静态透传参数,用于传递不变的业务标识信息。

说明

Event 为 start 时必填

{ "orderId": "ORD20231201001", "restaurantName": "美味餐厅", "customerAddress": "xxxxxx号", "orderType": "delivery" }

ContentState

string

灵动岛活动的动态透传参数,包含可实时更新的状态信息和变化数据。

说明
  • 避免过于频繁的更新(建议间隔≥5 秒)

  • 批量更新多个字段,减少推送次数

  • 考虑用户体验,避免界面闪烁

  • 有效的 JSON 字符串

{ "status": "delivering", "estimatedTime": "10分钟", "progress": 80, "driverName": "李师傅", "currentStep": "配送员正在路上"} }

DismissalDate

integer

设定已结束的灵动岛活动在锁屏界面的保留时间,让用户在活动结束后仍可查看信息,秒级 Unix 时间戳。

1701439800

StaleDate

integer

设定 iOS 灵动岛活动内容的过期时间戳,秒级 Unix 时间戳。

说明
  • 到达指定时间后,系统会自动将活动标记为过期状态

  • 过期的活动会从灵动岛和锁屏界面中移除

  • 防止过时信息长期占用用户界面

1701425400

ApnsEnv

string

iOS 的通知是通过 APNS 中心来发送的,需要填写对应的环境信息。可选参数,默认是生产环境。

  • DEV:开发环境,适用于 Xcode 直接安装调试的应用。

  • PRODUCT:生产环境,适用于 App Store、TestFlight、Ad Hoc 及企业分发的应用。

DEV

Hmos

object

鸿蒙通知配置。

Category

string

通知消息类别,可选参数,默认是 MARKETING 类别。

说明

完成申请通知消息自分类权益后,用于标识消息类型,不同的通知消息类型影响消息展示和提醒方式。详情参见鸿蒙官网 Notification.category

IM

SlotType

string

使用指定类型的通知渠道。

说明
  • 仅对阿里云自有通道有效。

  • 详情参见鸿蒙官网 SlotType

SOCIAL_COMMUNICATION

NotifyId

integer

指定每条消息在通知栏显示时的唯一标识(notifyId)。若未提供,推送服务将自动生成一个唯一标识。不同通知消息可使用相同的 notifyId,以实现新消息覆盖旧消息的功能。请参考鸿蒙官网 Notification.notifyId

123456

Action

string

指定应用内页面的 ability 对应的 action。

说明

详情请参考鸿蒙官网 ClickAction.action

com.example.action

Uri

string

应用内置页面 ability 对应的 uri。

说明
  • 当存在多个 Ability 时,分别填写不同 Ability 的 action 和 uri,优先使用 action 查找对应的应用内置页面。

  • 详情参见鸿蒙官网 ClickAction.uri

https://www.example.com:8080/push/example

RenderStyle

string

通知消息样式,可选参数,默认是普通通知。

NORMAL

ImageUrl

string

通知右侧大图标 URL,URL 使用的协议必须是 HTTPS 协议。

说明
  • 支持图片格式为 png、jpg、jpeg、heif、gif、bmp,图片长*宽<25000 像素。

  • 详情参见鸿蒙官网 Notification.image

https://example.com/xxx.png

InboxContent

array

RenderStyleMULTI_LINE 时,需填写此字段,用于定义多行文本样式的内容。最多支持 3 条内容。

string

文本。

1. 您有一个事项待处理

ExtParameters

string

设定通知消息的自定义扩展属性,用于传递额外的业务数据。

说明

参数必须以标准的 JSON Map 格式传入,格式错误将导致解析失败。

{"key": "value"}

TestMessage

boolean

启用测试消息。

说明

true

ReceiptId

string

鸿蒙通道回执 ID,该回执 ID 可以在鸿蒙通道推送运营平台的回执参数配置中查看。

说明
  • 如果在鸿蒙通道推送运营平台配置的默认回执配置是阿里云回执,则无需提供,如果不是,建议优先在阿里云 EMAS 移动推送控制台中配置鸿蒙通道默认回执 ID。

  • 详情参见鸿蒙官网 pushOptions.receiptId

RCPB***DFD5

ExtensionPush

boolean

启用鸿蒙通知扩展。

说明
  • 通知扩展消息需要先在鸿蒙官网申请权限才能发送,相关内容请参考鸿蒙文档发送通知扩展消息。

  • 鸿蒙 SDK 1.2.0 版本开始支持。

false

ExtensionExtraData

string

通知扩展消息的额外数据。

说明
  • 发送鸿蒙通知扩展消息时有效。

  • 概念上等同鸿蒙通知扩展消息的 extraData 字段,具体定义参考鸿蒙 ExtensionPayload 说明。

  • 鸿蒙 SDK 1.2.0 版本开始支持。

text

BadgeSetNum

integer

鸿蒙应用角标设置数字。

说明
  • 参考鸿蒙角标 setNum 字段说明。

  • 鸿蒙 SDK 1.2.0 版本开始支持。

1

BadgeAddNum

integer

鸿蒙应用角标累加数字。

说明

1

LiveViewPayload

string

鸿蒙实况窗数据结构 LiveViewPayload 的 JSON 字符串,开发接入请参考文档HarmonyOS 实况窗推送指南

{ "activityId": 1, "operation": 0, "event": "TAXI", "status": "DRIVER_ON_THE_WAY", "activityData": { "notificationData": { "type": 3 } } }

Sound

string

鸿蒙自定义铃声文件名

music.mp3

SoundDuration

integer

自定义消息通知铃声时长,单位秒,范围 [1,60],铃声时长不足时将会循环播放

2

Android

object

Android 通知配置

VendorChannelActivity

string

指定点击通知后跳转的 Activity。

警告 当使用安卓厂商通道时,必须填写该选项。

com.alibaba.cloudpushdemo.bizactivity

ChannelId

string

设置 Android app 的 channelId,需要与厂商 App 中的 channelId 能对应上。

说明
  • 因 OPPO 通知私信通道的 channel_id 与 app 的 channelId 相同,故 OPPO 通道推送时,channel_id 取此值。

  • 华为、FCM、阿里云自有通道推送中,channel_id 取此值。

  • 具体用途请参见常见问题: Android 8.0 以上设备通知接收不到

8.0up

RenderStyle

string

通知样式,取值为:

  • 0:标准模式(默认)

  • 1:长文本模式(支持华为、荣耀、小米、OPPO、魅族、自有通道)

  • 2:大图模式(支持自有通道)

  • 3:列表模式(支持华为、荣耀、小米、OPPO、自有通道)

0

PictureUrl

string

大图模式下的图片 URL,当前支持:自有通道:安卓 SDK 3.6.0 及以上。

https://imag.example.com/image.png

ImageUrl

string

大图标 URL。 当前支持:

  • 华为 EMUI(仅长文本模式、Inbox 模式下适用)。

  • 荣耀 Magic UI(仅长文本模式下适用)。

  • 自有通道(安卓 SDK3.5.0 及以上)。

https://imag.example.com/image.png

InboxContent

array

Inbox 模式下的正文,内容为合法的 JSON Array,且元素不超过 5 个。当前支持:

  • 华为:EMUI9 及以上

  • 荣耀:Magic UI 4.0 及以上

  • 小米:MIUI10 及以上

  • OPPO:ColorOS 5.0 以上

  • 自有通道:安卓 SDK3.6.0 及以上

string

正文

1. 第一条待处理事项

NotifyId

integer

Android 通知栏消息的唯一标识符,用于控制通知的覆盖和替换行为。相同 NotifyId 的新通知会自动覆盖旧通知。

说明

支持:华为、小米、OPPO、Vivo、魅族等厂商通道(FCM 除外)

233856727

GroupId

string

消息分组,同一组消息在通知栏里只显示最新一条和当前该组接受到的消息总数目,不会展示所有消息也无法展开。当前支持:

  • 华为

  • 荣耀

  • 自有通道

group-1

ExtParameters

string

Android 通知的自定义扩展属性。

说明
  • 参数必须以标准的 JSON Map 格式传入,格式错误将导致解析失败。

{"key1":"value1"}

Music

string

华为厂商通道通知声音。指定存放在客户端项目 app/src/main/res/raw/ 目录下的音频文件名,不需要携带文件格式后缀名。若不设置,则使用默认铃声。

alicloud_notification_sound

BadgeSetNum

integer

设置角标数字固定值,取值范围[1~99]。

说明
  • 厂商通道推送仅华为、荣耀通道生效。

  • 阿里云自有通道推送时仅华为机型、荣耀机型与 vivo 机型上生效。

4

BadgeAddNum

integer

设置角标累加值,在原角标的基础上进行累加。

说明
  • 支持华为荣耀 通道。

  • BadgeAddNumBadgeSetNum 同时存在时,以后者为准。

1

BadgeActivity

string

角标设置应用入口 Activity 的全类名。

说明

仅华为/荣耀产商通道推送时有效

com.alibaba.cloudpushdemo.bizactivity

TestMessage

boolean

设置厂商通道通知类型:

  • false:正式通知(默认)。

  • true:测试通知。

说明

当前支持:华为通道、荣耀通道、vivo 通道、OPPO 流体云。

false

Options

object

通道详细配置。

Accs

object

阿里云自有配置

说明

仅走阿里云自有通道时有效

CustomStyle

integer

Android 自定义通知栏样式,取值:1-100。

说明

需要客户端配置完成样式预设,参考文档自定义通知样式接口

1

Priority

integer

Android 通知在通知栏展示时排列位置的优先级。可取值: -2,-1,0,1,2。

0

ThreadId

string

消息分组,同一组消息在通知栏里折叠展示,可展开,不同组通知分开展示。

说明

安卓 SDK3.9.2 及以上

order_ORD20231201001

OpenType

string

点击通知后动作。可取值:

  • APPLICATION:打开应用(默认值)

  • ACTIVITY:打开指定页面 OpenActivity

  • URL:打开 URL

  • NONE:无跳转

APPLICATION

OpenActivity

string

设定点击通知打开的 activity。当 OpenType 取值为 ACTIVITY时有效.

com.alibaba.cloudpushdemo.bizactivity

OpenUrl

string

Android 收到推送后,点击通知打开对应的 url。当 OpenType 取值为 URL 时有效。

www.example.com

NotifyType

string

通知的提醒方式。可取值:

  • VIBRATE:振动(默认值)

  • SOUND:声音

  • BOTH:声音和振动

  • NONE:静音

NONE

Huawei

object

华为配置

ReceiptId

string

华为通道回执 ID,该回执 ID 可以在华为通道推送运营平台的回执参数配置中查看。

说明

如果在华为通道推送运营平台配置的默认回执配置是阿里云回执,则无需提供,如果不是,建议优先在阿里云 EMAS 移动推送控制台中配置华为通道默认回执 ID。

RCP4C123456

Category

string

作用一:完成自分类权益申请后,用于标识消息类型,确定消息提醒方式,对特定类型消息加快发送,取值请参考华为推送官方文档的消息分类标准,填写文档表格中的“云端通知 category 取值”或“本地通知 category 取值”。

作用二:申请特殊权限后,用于标识高优先级透传场景,取值如下:

  • VOIP:音视频通话

  • PLAY_VOICE:语音播报

说明
  • 对于“云端通知 category 取值”为“不涉及”的一概走阿里云自有通道

  • 对于“本地通知 category 取值”为“不涉及”的一概走华为通道

VOIP

Urgency

string

华为通道透传消息投递优先级,取值如下:

  • HIGH

  • NORMAL

需要申请权限,具体请参见:申请链接

NORMAL

Importance

integer

设置 Huawei 通知消息分类 importance 参数,决定用户设备消息通知行为,取值如下:

  • 0:资讯营销类消息

  • 1:服务与通讯类消息

说明

建议使用 Category 进行通知分类,需要在 Huawei 平台申请,申请链接

0

BusinessType

integer

设置华为快通知参数

  • 0:发送华为普通通知(默认)。

  • 1:发送华为快通知。

1

LiveNotificationPayload

string

华为安卓实况窗数据结构 LiveNotificationPayload 的 JSON 字符串,开发接入请参考文档华为实况窗推送指南

{ "activityId": 1, "operation": 1, "event": "TAXI", "activityData": { "notificationData": { "type": 3 } } }

Honor

object

荣耀配置

Importance

integer

设置荣耀通知消息分类 importance 参数,决定用户设备消息通知行为,取值如下:

  • 0:资讯营销类消息

  • 1:服务与通讯类消息

需要在荣耀平台申请,申请链接

0

Xiaomi

object

小米配置

Channel

string

设置小米通知类型的 channelId,需要在小米平台申请,详见:申请链接

说明

小米通道单个应用最多可申请 8 个 channel,请提前做好规划。

michannel

Vivo

object

VIVO 配置

Category

string

vivo 将消息分为:系统消息、运营消息两个类别进行管理。

系统消息:

  • IM:即时消息

  • ACCOUNT:账号与资产

  • TODO:日程待办

  • DEVICE_REMINDER:设备信息

  • ORDER:订单与物流

  • SUBSCRIPTION:订阅提醒

运营消息:

  • NEWS:新闻

  • CONTENT:内容推荐

  • MARKETING:运营活动

  • SOCIAL:社交动态

详细请参考 vivo 分类说明

MARKETING

ReceiptId

string

Vivo 厂商推送通道的消息回执标识符,用于接收推送结果回调通知。

说明
  • 查看位置:Vivo 开放平台→ 推送服务 → 应用信息 → 回执配置

  • 配置建议:优先在阿里云 EMAS 控制台配置默认回执 ID

  • 使用条件:仅当 Vivo 平台默认回执非阿里云回执时需要配置

1232221

Importance

integer

设置 vivo 通知消息分类,取值为:

  • 0:运营类消息(默认)

  • 1:系统类消息

说明

建议使用 Category 进行通知分类,需要在 vivo 平台申请,详见:申请链接

0

Oppo

object

OPPO 配置

Category

string

OPPO 将消息分类:通讯与服务、内容与营销两个类别进行管理。

通讯与服务(需申请权限):

  • IM:即时消息

  • ACCOUNT:账号与资产

  • TODO:日程待办

  • DEVICE_REMINDER:设备信息

  • ORDER:订单与物流

  • SUBSCRIPTION:订阅提醒

内容与营销:

  • NEWS:新闻

  • CONTENT:内容推荐

  • MARKETING:运营活动

  • SOCIAL:社交动态

详细请参考 vivo 分类说明

NEWS

NotifyLevel

integer

OPPO 通道通知栏消息提醒等级。可取值为:

  • 1:通知栏

  • 2:通知栏+锁屏(通讯与服务类消息默认通知级别)

  • 16:通知栏+锁屏+横幅+震动+铃声(需申请权限)

说明

使用 NotifyLevel 参数时,必须同时传 Category 参数。

1

PrivateMsgTemplateId

string

OPPO 私信模板 ID

687557242b1634hzefs3d5013

PrivateTitleParameters

string

OPPO 私信模版标题参数

{"name": "张三"}

PrivateContentParameters

string

OPPO 私信模版内容参数

{ "key1": "value1", "key2": "value2" }

IntelligentIntent

string

OPPO 流体云的意图共享数据结构 IntelligentIntent 的 JSON 字符串,开发接入请参考文档 OPPO 流体云推送指南

{ "intentName": "Example.Progress", "identifier": "d71ebd3119877b12ecdb6c4fe96b068e", "timestamp": 1729485000989, "serviceId": { "launcher": "999800001", "fluidCloud": "999900001" }, "intentAction": { "actionStatus": 0 }, "intentEntity": { "entityName": "TAXI" } }

DeleteIntentData

string

OPPO 流体云的意图删除数据结构 data 的 JSON 字符串,当 AndroidOppoIntelligentIntent 参数已填写时此参数无效,开发接入请参考文档 OPPO 流体云推送指南

{ "intentName": "Example.Progress", "entityIds": [ "A580202509130712" ], "serviceId": { "launcher": "999800001", "fluidCloud": "999900001" } }

Meizu

object

魅族配置

NoticeMsgType

integer

魅族消息类型

  • 0 公信消息(默认)

  • 1 私信消息

0

Options

object

推送选项

UseChannels

string

指定发送通道,取值如下:

  • accs 阿里云自有通道

  • huawei 华为通道

  • honor 荣耀通道

  • xiaomi 小米通道

  • oppo OPPO 通道

  • vivo vivo 通道

  • meizu 魅族通道

  • gcm 谷歌 GCM 通道(旧版 HTTP)

  • fcm 谷歌 Firebase 通道(HTTP v1 API)

  • apns APNs 通道

  • harmony 鸿蒙通道

说明
  • 如果未配置此参数,则代表所有通道均可使用。

  • 如果配置了此参数,则严格使用参数中的通道。

  • 如果配置的通道和发送策略冲突(如 iOS 通知仅走 APNs 通道,但本参数中不包含 apns),则不实施发送。

  • 若配置 gcm,则可以走谷歌 GCM 和 FCM 通道,若配置 fcm,则只能走谷歌 FCM 通道。

accs,apns

PushTime

string

指定消息的发送时间,最晚不超过 7 天。仅当 Action 参数为 SCHEDULED_PUSH 时有效。

说明

采用 ISO 8601 标准,使用 UTC 时间,格式为 yyyy-MM-ddTHH:mm:ssZ 。

2025-06-19T12:00:00Z

ExpireTime

string

设置消息的过期时间,过期后将不再发送,最长保存 72 小时。

说明
  • 采用 ISO 8601 标准,使用 UTC 时间,格式为 YYYY-MM-DDThh:mm:ssZ。

  • 过期时间需满足:ExpireTime > PushTime + 3 秒(3 秒为网络和系统延迟的冗余)。

  • 建议:单推过期时间不低于 1 分钟,全推或批量推送不低于 10 分钟。

重要 对于透传消息,不设置过期时间即代表只发在线,当设备不在线时,丢弃消息。

2025-06-21T12:00:00Z

JobKey

string

推送任务自定义标识,当 JobKey 不为空时,回执日志中会附带该字段。查看回执日志参见回执日志

jobkey1727749697913

Trim

boolean

是否自动对过长标题、内容进行截断。

说明

仅支持明确限制标题、内容的厂商通道,对 APNs、华为、荣耀通道等不限制标题、内容,只限制总请求体大小的不适用。

false

Sms

object

补发短信。

说明

当前仅支持 AndroidHarmonyOS 设备

TemplateName

string

短信模板名,可以在短信模板管理界面获取,是系统分配的名称,而非开发者设置的名称。

SMS_123456789

SignName

string

短信签名。

某某科技

Params

string

短信模板的变量名键值对。

key1=value1&key2=value2

DelaySecs

integer

触发短信的延迟时间,单位:秒。

若使用短信联动必须设置,推荐设置为 15 秒以上,最大不超过 3 天,避免短信和推送的重复。

说明

短信联动时,ExpireTime 参数失效,通知失效时间以 DelaySecs 参数计算,失效时间为当前时间加上 DelaySecs 时间。

150

SendPolicy

string

短信发送策略。

PUSH_NOT_RECEIVED

MessageId

integer

用于标识消息的唯一 ID。仅当 Action 参数为 CONTINUOUS_PUSH 时有效。

1174754033128****