目录

请求体参数说明

pushOptions

参数 是否必选 参数类型 描述
testMessage 否 Boolean

测试消息标识：

- false：正式消息（默认值）

- true：测试消息

说明：

当testMessage为true时，单个项目每日最多可推送1000条测试消息，每次推送携带Token数不超过10个。1000条为REST API请求成功总数，非成功到达端侧的消息总数。

推送卡片刷新消息时，每次仅能携带一个Token。
ttl 否 Integer

消息缓存时间，单位：s。在用户设备离线时，消息在Push服务器进行缓存，在消息缓存时间内用户设备上线，消息会下发，超过缓存时间后消息会丢弃，默认值为86400秒（1天） ，最大值为1296000秒（15天）。

说明：

推送应用内通话消息场景、推送通知消息（VOIP消息类型）场景以及推送语音播报消息（VOIP消息类型）场景，ttl建议设置为30~60秒。
biTag 否 String 批量任务消息标识，消息回执时会返回给应用服务器，长度最大64字节。
receiptId 否 String 输入一个唯一的回执ID指定本次下行消息的回执地址及配置，该回执ID可以在配置回执参数中查看。
collapseKey 否 Integer

用户设备离线时，Push服务器对离线消息缓存机制的控制方式，用户设备上线后缓存消息会再次下发，取值如下：

-1：对该取值的所有离线消息都缓存（默认值）。

0~100：离线消息缓存分组标识，对离线消息进行分组缓存，每个应用每一组只缓存一条最新的离线消息。

如果您发送了10条消息，其中前5条的collapseKey为1，后5条的collapseKey为2，那么待用户上线后collapseKey为1和2的分别下发最新的一条消息给最终用户。

说明：

collapseKey字段只对push-type为0或2的消息生效。

0：通知消息

2：语音播报消息

target

参数 是否必选 参数类型 描述
token 是 Array [String]

按照Token向目标用户推送消息。

说明：

卡片刷新场景单次只允许携带1个Token，其他消息单次最多携带1000个Token。

AlertPayload 通知消息

请求体示例请参见通知消息。

参数 是否必选 参数类型 描述
notification 是 Notification Object 通知消息结构体，详情请参见Notification结构体。

[h2]Notification

参数 是否必选 参数类型 描述
category 是 String

通知消息类型。完成申请通知消息自分类权益后，用于标识消息类型，不同的通知消息类型影响消息展示和提醒方式。取值如下：

服务与通讯类

· IM：即时聊天

· VOIP：语音通话邀请、视频通话邀请

· MISS_CALL：未接通话消息提醒

· SUBSCRIPTION：订阅

· TRAVEL：出行

· HEALTH：健康

· WORK：工作事项提醒

· ACCOUNT：账号动态

· EXPRESS：订单&物流

· FINANCE：财务

· DEVICE_REMINDER：设备提醒

· MAIL：邮件

· PLAY_VOICE：语音播报

说明：

PLAY_VOICE（语音播报）消息仅可发送push-type为2的语音播报消息。

资讯营销类

· MARKETING：新闻、内容推荐、社交动态、产品促销、财经动态、生活资讯、调研、功能推荐、运营活动（仅对内容进行标识，不会加快消息发送），统称为资讯营销类消息。

说明：

若您仅需发送MARKETING（资讯营销类）消息，则无需申请通知消息自分类权益。MARKETING消息与其他分类的通知消息存在不同的频控策略，详情请参见通知消息推送数量管理规则。若消息被频控，请参考频控FAQ进行问题排查。
title 是 String 通知消息标题。（注意消息体大小限制，详情参见使用约束）
body 是 String 通知消息内容。（注意消息体大小限制，详情参见使用约束）
image 否 String

通知右侧大图标URL，URL使用的协议必须是HTTPS协议。（注意消息体大小限制，详情参见使用约束）

说明：

· Wearable不支持右侧大图标样式。

· 支持图片格式为PNG、JPG、JPEG、BMP，图片像素的总字节数不超过192KB，若超过则图片不展示。

· 6.1.0(23)版本新增支持WEBP格式图片。
overlayIcon 否 String

通知重叠图标URL，URL使用的协议必须是HTTPS协议。（注意消息体大小限制，详情参见使用约束）

说明：

· 支持图片格式为PNG、JPG、JPEG、BMP、WEBP，图片像素的总字节数不超过192KB，若超过则图片不展示。

· 仅当category为IM或VOIP或MISS_CALL时，消息生效。

起始版本： 6.1.0(23)
style 否 Integer

通知消息样式：

0：普通通知（默认值）

1：大文本样式

3：多行文本样式（使用场景请参见开发指南）

说明：

· style=1 大文本样式将要废弃，建议直接使用 style=0 普通通知。

· Wearable不支持大文本样式和多行文本样式。
bigTitle 否 String

大文本样式的标题，当style为1时必选。设置bigTitle后通知栏展示时，使用bigTitle而不用title。（注意消息体大小限制，详情参见使用约束）

说明：

· 此字段将要废弃，建议直接使用title字段。

· Wearable不支持大文本样式。
bigBody 否 String

大文本样式的内容，当style为1时必选。设置bigBody后通知栏展示时，使用bigBody而不用body。（注意消息体大小限制，详情参见使用约束）

说明：

· 此字段将要废弃，建议直接使用body字段。

· Wearable不支持大文本样式。
notifyId 否 Integer 每条消息在通知显示时的唯一标识。不携带或者设置-1时，Push Kit自动为每条消息生成一个唯一标识；不同的通知消息可以拥有相同的notifyId，实现新消息覆盖旧消息功能。若要用于消息撤回则必填，且范围为[0, 2147483647]，即非负值。详情请参见消息撤回。
appMessageId 否 String

应用消息的唯一标识，不携带时默认无appMessageId。长度范围为[1,64]，支持大小写字母、数字、+、/、=、-、_和空白字符。

说明：

· 当同一appMessageId的应用消息通过多个渠道（Push Kit、近场通讯、应用自己拉取或发送本地通知）触达时，目标终端只展示有效期内最早的一条，有效期默认为24小时。

· 区别于notifyId，notifyId作用机制是新消息覆盖旧消息。特别地，notifyId和appMessageId均相同时，展示旧消息。
profileId 否 String 应用内账号id匿名标识，最大长度为64。
inboxContent 否 Array [String]

多行文本样式的内容，当style为3时，本字段必填，最多支持3条内容，每条最大长度1024且无法完全展示时以“...”截断。详情参见inboxContent 。

说明：

Wearable不支持多行文本样式。
clickAction 是 ClickAction Object 点击消息动作，详情请参见ClickAction结构体。
badge 否 AlertBadge Object

通知消息角标控制参数，详情请参见AlertBadge结构体，不设置时应用不显示角标数字，若当前已存在角标，则角标数字不变化。

说明：

Wearable、TV不支持通知角标样式。
sound 否 String

自定义消息通知铃声。此处设置的铃声文件必须放在应用的/resources/rawfile路径下。例如设置为alert.mp3，对应应用本地的​/resources/rawfile/alert.mp3 文件。支持的文件格式包括MP3、WAV、MPEG等，如果不设置，则用默认系统铃声。

当请求不携带soundDuration字段时，建议铃声时长不超过30秒，若超过30秒则截断处理；当请求携带soundDuration字段时，详情请参见soundDuration字段说明。

说明：

· Wearable、TV、PC/2in1不支持自定义铃声。

· 当category取值为MARKETING时，为静默通知，自定义铃声无效。
soundDuration 否 Integer

自定义消息通知铃声时长。需要配合sound字段使用，只有当请求同时携带sound字段，soundDuration字段才会生效。仅支持数字，单位：s，取值范围 [1, 60]。

sound字段传入的自定义消息通知铃声会播放至soundDuration字段值后停止，若自定义消息通知铃声对应的时长不足soundDuration字段值则会循环播放，在达到soundDuration字段值后停止。
foregroundShow 否 Boolean

应用在前台时是否展示通知消息。

true：默认值，应用在前后台都展示通知消息，此时receiveMessage不会被触发，无法获取消息数据。

false：应用只在后台展示通知消息；应用在前台时，通知消息将不会展示，但可以通过receiveMessage接收通知消息自行完成业务处理，详情请参见应用在前台时处理通知消息。

说明：

foregroundShow字段仅对push-type为0的通知消息生效。
priorityScene 否 String

消息的优先通知类型。取值如下：

· PRIMARY_CONTACT：重要联系人消息

· AT_ME：@我

· URGENT_MESSAGE：加急消息

· SCHEDULE_REMINDER：日程待办提醒

说明：

发送优先通知消息需要开通优先通知权益。

[h2]inboxContent示例

"inboxContent": [
  "1. 通知栏消息样式",
  "2. 通知栏消息提醒方式和展示方式",
  "3. 通知栏消息语言本地化"
]

[h2]ClickAction

参数 是否必选 参数类型 描述
actionType 是 Integer

消息点击后的行为。

0：打开应用首页

1：打开应用自定义页面

3：清除通知

5：打开拨号界面

在不同的场景下支持actionType不同，详情请参考点击行为类型。
action 否 String

应用内置页面ability对应的action。当actionType为1时，字段uri和action至少填写一个。当action对应的页面路径不存在时，会默认跳转应用首页。

action如何设置请参见点击消息进入应用内页。
uri 否 String

应用内置页面ability对应的uri，uri对象内部结构请参见skills标签。当actionType为1时，字段uri和action至少填写一个。当存在多个Ability时，分别填写不同Ability的action和uri，优先使用action查找对应的应用内置页面。

uri如何设置请参见点击消息进入应用内页。
data 否 Object

点击时传递给应用的数据，格式为JSON对象，数据获取请参见数据传递。（注意消息体大小限制，详情参见使用约束）

actionType为5时，data必填。固定携带{"tel": "xxx"} value为电话号码，长度最大为20，允许包含字符：

· +（只能在首位字符）

· -

· 空格

· 0-9

· #

说明：

当actionType为5时，首位字符必须为+或0-9。

[h2]点击行为类型

push-type 字段 actionType枚举值
0 Alert消息 notification.clickAction

0：打开应用首页

1：打开应用自定义页面
2 语音播报消息 notification.clickAction

0：打开应用首页

1：打开应用自定义页面
7 实况窗 notificationData.clickAction

0：打开应用首页

1：打开应用自定义页面
7 实况窗 notificationData.extend.clickAction

0：打开应用首页

1：打开应用自定义页面

3：清除通知

5：打开拨号界面

说明：

如果设备不支持拨号，当actionType取值5时则无法创建实况窗。

[h2]AlertBadge

参数 是否必选 参数类型 描述
addNum 否 Integer

应用角标累加数字（大于0小于100的整数），非应用角标实际显示数字。

说明：

· 某应用当前有N条未读消息，若addNum设置为3，则每发一次消息，应用角标显示的数字累加3，为N+3（若N+3 > 99，角标显示“99+”）。

· 当不传入addNum时默认值为0，角标不会增加。
setNum 否 Integer

角标设置数字（大于等于0小于100的整数），应用角标实际显示数字。

说明：

setNum优先级高于addNum：

· 若未传入setNum，说明未下发setNum，则本次以addNum为准。

· 若setNum>=0，说明下发了setNum，则本次以setNum为准。发布通知时不携带addNum字段。

BadgePayload 角标刷新消息

请求体示例请参见角标刷新消息。

参数 是否必选 参数类型 描述
notification 是 BadgeNotification Object 角标刷新消息结构体，详情参见BadgeNotification结构体。

[h2]BadgeNotification

参数 是否必选 参数类型 描述
badge 是 Badge Object 角标刷新消息结构体，详情参见Badge结构体。

[h2]Badge

参数 是否必选 参数类型 描述
setNum 是 Integer 角标设置数字（大于等于0小于100的整数），应用角标实际显示数字。

ExtensionPayload 语音播报消息

请求体示例请参见语音播报消息。

参数 是否必选 参数类型 描述
notification 是 Notification Object

通知消息结构体，详情请参见Notification结构体。

说明：

notification.category必填，且取值为“PLAY_VOICE”，发送语音播报消息前请先申请推送语音播报消息权益，请参见申请推送语音播报消息权益。
extraData 是 String

语音播报消息的额外数据。（注意消息体大小限制，详情参见使用约束）

extraData数据获取请参见示例代码。

FormUpdatePayload 卡片刷新消息

请求体示例请参见卡片刷新消息。

参数 是否必选 参数类型 描述
formId 是 Long 服务卡片的实例ID，当卡片onAddForm（卡片使用方添加卡片至桌面）时获取。请注意，当前端侧生成formId最大值为231-1，formId字段支持输入的最大值为263-1。
version 是 Integer

卡片刷新消息的版本号，最小值为0，最大值为231-1。

· 新的卡片刷新消息的版本号需大于当前卡片刷新消息版本号，否则会刷新失败。

· 若新的卡片刷新消息版本号为0则表示卡片刷新版本号重置，本次卡片刷新仍然有效，下次卡片刷新消息版本号需大于0。
images 否 Array [FormImage Object] 服务卡片图片数据，结构为数组，数组每个元素为一个object，详情请参见FormImage结构体。当前仅允许携带一个数组元素。详情见示例代码。
moduleName 是 String

服务卡片模块名称。

项目模块级别下的src/main/module.json5中的module标签下的name值。
formName 是 String

服务卡片名称。

该数据来源于卡片配置文件中forms标签下的某个卡片配置信息的name值，卡片配置文件位于项目模块级别下的src/main/resources/base/profile，请参见指南。
abilityName 是 String

服务卡片Ability名称。

项目模块级别下的src/main/module.json5中的extensionAbilities标签下的服务卡片的ability名称。
formData 是 Object

待刷新服务卡片的业务数据，key-value格式。

该数据来源于卡片页面文件中的声明式范式组件名称，卡片页面文件位于项目模块级别下的src/main/ets/widgets，请参见指南。

说明：

· formData中的key不能以datashareproxy:// 开头。

· formData中的value如果是数值类型，不能超过253-1。

· formData中的value取值不允许为null。

[h2]FormImage

参数 是否必选 参数类型 描述
keyName 否 String

图片的对应的key，该值不能与formData中自定义的变量数据的key重复。

该数据来源于卡片页面文件中的图片组件名称，卡片页面文件位于项目模块级别下的src/main/ets/widgets，请参见指南。
url 否 String

图片下载地址，URL使用的协议必须是HTTPS协议。

说明：

支持图片的格式为PNG、JPG、JPEG、WEBP，图片文件最大为512KB，若超过则图片不展示。（注意消息体大小限制，详情参见使用约束）
require 否 Integer

图片刷新策略控制。

1：若图片下载失败，则不进行卡片刷新操作。（默认值）

0：若图片下载失败，仅刷新文字。

[h2]示例代码

{
  "images": [{
    "keyName": "icon",
    "url": "https://xxx.png",
    "require": 1
  }]
}

BackgroundPayload 后台消息

请求体示例请见后台消息。

参数 是否必选 参数类型 描述
extraData 是 String

传递给应用的数据。（注意消息体大小限制，详情参见使用约束）

Push检测应用是否在前台，应用如果在前台则传递到目标应用，如果不在前台，则缓存或静默写入应用自身缓存。

extraData数据获取请参考示例代码。
proxyData 否 String 应用进程不在前台时是否走数据代理静默写入到应用自身缓存，当前只能传全大写"ENABLE"。若您不希望开启代理写入，请不要在消息体中填写此字段。

LiveViewPayload 实况窗消息

实况窗请求示例请见创建实况窗消息和更新实况窗消息。端云API参数关联关系参考端云API关系说明。

为了确保用户看到内容的时效性，请您确保对实况窗内容进行及时更新。系统将在实况窗超过2小时未更新时，隐藏实况窗在状态栏胶囊和锁屏的展示，保留通知中心展示；超过4小时未更新，系统会认为实况窗结束，并从各个展示入口清除该实况窗。

参数 是否必选 参数类型 描述
activityId 是 Integer

实况窗唯一标识，取值范围为[-2147483648, 2147483647]，由开发者自行生成。对应Live View Kit中的id字段。

说明：

若发送的activityId对应的实况窗不存在（更新或结束实况窗的场景中），将限制使用该activityId发送实况窗消息24小时。
operation 是 Integer

实况窗消息操作类型：

0：表示创建实况窗消息（请参考创建实况窗约束进行创建）

1：表示更新实况窗消息（确保activityId对应的实况窗存在）

2：表示结束实况窗消息（确保activityId对应的实况窗存在）

4：表示增加延迟触发创建实况窗消息（仅每个实况活动1个围栏）

6：表示增加延迟触发结束实况窗消息（仅每个实况活动1个围栏）

更新和结束实况窗时，对于非必选字段，若无特殊说明和默认值，则不携带时默认继承上一次的状态。
event 是 String

业务场景取值，取值必须为实况窗支持对接的场景中的内容。

使用对应场景需要申请权益，详情请参见开通实况窗权益，完成权益的申请。

说明：

当通过Push Kit创建实况窗消息（operation取值为0）时，event取值仅支持部分业务场景，详情请参考通过Push Kit创建和更新实况窗的约束限制。
status 否 String

表示实况窗消息当前的业务阶段或状态。

当operation为0，或operation为1且更新的实况窗为通过REST API创建的实况窗时必填。

status的取值范围根据场景类型而定，详情见Status取值范围。

消息体中占位符{{status}}的使用，参见支持携带占位符的字段，满足要求时将替换字段中的占位符为目标值。
title 否 String 可选，当系统不支持实况窗通知时，展示在通知栏的标题。（注意消息体大小限制，详情参见使用约束）
content 否 String 可选，当系统不支持实况窗通知时，展示在通知栏的内容。（注意消息体大小限制，详情参见使用约束）
mute 否 Boolean

标识消息更新是否需要提醒。

true：静默提醒 （默认值）

false：铃声震动提醒
version 否 Integer 更新实况窗通知的版本号，大于等于0，新的实况窗通知版本号需大于当前实况窗通知版本号，否则会刷新失败。
activityData 是 ActivityData Object 实况窗通知详细数据，具体字段请参见ActivityData结构体。
subEvent 否 String

业务子场景取值，内容只允许包含英文、数字及下划线。主要用于子业务场景的运营统计，使用对应子场景无需额外申请权益。

相关场景的取值请参考实况窗服务subEvent。

起始版本： 26.0.0
trigger 否 Trigger Object

延迟触发实况的围栏信息。

说明：

Wearable设备不支持该特性，携带该字段的消息将作为普通实况窗消息展示。
shareUrl 否 String

实况分享H5页面url链接。url必须以"https://"协议开头，长度范围[1, 127]。当url不满足字段要求，shareUrl字段不生效。

起始版本： 26.0.0

[h2]创建实况窗约束

创建实况窗的消息示例请参见创建实况窗消息。

  1. 允许通过REST API创建实况窗的event取值范围见通过Push Kit创建和更新实况窗的约束限制。

  2. 12小时内不允许通过REST API创建同一个activityId的实况窗。

  3. 对于不同的event类型，创建实况窗时，对布局类型（activityData.notificationData.type）和必填字段，有以下场景约束（表格中未提及的场景，在创建时支持所有布局类型，在创建或更新时无必填字段限制。）：

    event 创建时允许的布局类型 创建时必填字段 REST API创建的消息，更新时必填字段
    FLIGHT 左右文本模板类型

    status

    activityData.notificationData.keywords

    		 status
    TAXI

    进度可视化类型

    强调文本模板类型

    左右文本模板类型

    赛事类型

    		 status status
    TRAIN 左右文本模板类型

    status

    activityData.notificationData.keywords

    		 status
    SUBSCRIBE_TIMER

    强调文本模板类型

    左右文本模板类型

    		 无 无

  4. 对于不同的布局类型（activityData.notificationData.type），需要在支持携带占位符的字段中填入至少一次status的占位符{{status}} ；如果该event下keywords字段也必填，则也需要在支持携带占位符的字段中填入至少一次相应的占位符，占位符具体请参见keywords字段描述。

  5. 通过REST API创建的实况窗，在更新时必须同时满足status和keywords要求。通过Live View Kit（实况窗服务）创建的实况窗，在REST API更新时可以不填写status和keywords字段，若开发者选择填写则需满足status和keywords要求。

[h2]支持携带占位符的字段

布局类型 字段

进度可视化类型

赛事类型

activityData.notificationData.contentTitle

activityData.notificationData.contentText.text

activityData.notificationData.extend.text
强调文本模板类型

activityData.notificationData.contentTitle

activityData.notificationData.contentText.text

activityData.notificationData.extend.text

activityData.notificationData.singleTextBlock.firstLine

activityData.notificationData.singleTextBlock.secondLine
左右文本模板类型

activityData.notificationData.contentTitle

activityData.notificationData.contentText.text

activityData.notificationData.extend.text

activityData.notificationData.firstTextBlock.firstLine

activityData.notificationData.firstTextBlock.secondLine

activityData.notificationData.lastTextBlock.firstLine

activityData.notificationData.lastTextBlock.secondLine

[h2]Status取值范围

event status取值 消息体中{{status}}占位符将替换的词 场景说明
FLIGHT DEPART 计划 计划出发。航班计划起飞前一段时间，提醒用户准备出发。
FLIGHT WAITING_FOR_CHECK_IN 未值机 未值机。
FLIGHT CHECKED_IN 已值机 已值机。
FLIGHT PASSED_SECURITY_CHECK 已安检 已安检。
FLIGHT START_BOARDING 开始登机 开始登机。
FLIGHT URGE_BOARDING 催促登机 催促登机。
FLIGHT BOARDED 已登机 已登机。
FLIGHT END_BOARDING 结束登机 结束登机。
FLIGHT ABOUT_TO_TAKE_OFF 即将起飞 即将起飞。
FLIGHT TAKEN_OFF 起飞 航班起飞。用户关注了某个航班后，向用户提醒航班已经起飞。
FLIGHT ARRIVED 到达 航班到达。
FLIGHT TRANSFER 中转提醒

中转提醒。用户有多趟航班中转，在到达后提醒用户下一趟航班的信息。

若是新航班信息，建议新建一张实况窗卡片承载。
FLIGHT NEW_ITINERARY 新行程开启 中转航班新行程提醒
FLIGHT GATE_CHANGE 登机口变更 登机口变更。
FLIGHT FLIGHT_DELAY 延误 航班延误。
FLIGHT FLIGHT_CANCEL 取消 航班取消。
FLIGHT FLIGHT_DIVERSION 备降 航班备降。
FLIGHT FLIGHT_RETURN 返航 航班返航。
TAXI CALLING 呼叫车辆中 呼叫车辆中。
TAXI ABOUT_TO_BEGIN 行程即将开始 行程即将开始。预约订单、顺风车订单的场景，在行程即将开始时，提醒用户出发。
TAXI DRIVER_ON_THE_WAY 司机正在赶来 司机正在赶来。
TAXI DRIVER_ARRIVE 司机已到达上车点 司机已到达上车点。
TAXI HEADING_TO_DESTINATION 正在去往目的地 正在去往目的地。订单有多个目的地时，可持续使用本状态直到行程结束。
TAXI COMPLETED 行程结束 行程结束。
TAXI RE_CALLING 重新呼叫车辆中 重新呼叫车辆中。订单改派、司机取消订单等导致的车辆重新呼叫。
TAXI CANCELED 订单已取消 订单已取消。用户取消订单、因周边运力不足无法成单的订单，均属于订单已取消。
TRAIN DEPART 计划出发 列车计划出发前一段时间，提醒用户准备出发。
TRAIN PASSED_SECURITY_CHECK 已安检 用户已完成安检。
TRAIN TICKET_CHECK 检票提醒 列车开始检票。
TRAIN CHECKED 已检票 用户已完成检票。
TRAIN CHECK_IN_CLOSED 停止检票 检票口截止检票进站。
TRAIN SET_OFF 已出发 列车驶离出发点。
TRAIN HEADING_TO_DESTINATION 列车运行中 列车运行过程中，可以同步向用户展示途径站点、预计剩余时间。
TRAIN ARRIVED 已到达 列车到达目的地。
TRAIN GATE_CHANGE 检票口变更 检票口变更。
TRAIN TRAIN_DELAY 列车晚点 列车晚点。
TRAIN TRAIN_CANCEL 列车停运 列车停运。

[h2]ActivityData

参数 是否必选 参数类型 描述
notificationData 是 NotificationData Object 消息通知布局数据，具体字段请参见NotificationData结构体。
capsuleData 否 CapsuleData Object 胶囊通知布局数据，具体字段请参见CapsuleData结构体。
externalData 否 ExternalData Object 小折叠外屏展示数据，具体字段请参见ExternalData结构体。

[h2]Trigger

参数 是否必选 参数类型 描述
type 是 Integer

地理围栏触发类型。

1：地理围栏（默认值）
condition 是 Geofence Object 地理围栏结构或者其他触发条件结构。
displayTime 否 Long 条件触发实况的展示持续时间，取值范围为[15，1800]，默认值为900，单位：s。

[h2]Geofence

参数 是否必选 参数类型 描述
longitude 是 Long 地理围栏中心点经度，取值范围为[-180，180]。
latitude 是 Long 地理围栏中心点纬度，取值范围为[-90，90]。
coordinateSystemType 是 Integer

地理围栏中心点的坐标系类型。

1：WGS84（默认值）

2：GCJ02
monitorEvent 是 Integer

触发地理围栏的事件类型。

1：进入围栏

2：退出围栏
radius 是 Long 地理围栏半径，取值范围为[200，2000] ，单位：m。
delayTime 否 Integer 延迟触发时间，即：进入/离开围栏后持续多长时间触发围栏，取值范围为[0，300]，默认值为0，单位：s。

[h2]NotificationData

参数 是否必选 参数类型 描述
type 是 Integer

布局类型：

3：进度可视化类型，适用于外卖配送、生鲜配送、车辆接驾进展等涉及进度节点显示的活动。

4：强调文本模板类型，适用于展示取餐码、取件码、车牌号等关键信息的活动。

5：左右文本模板类型，适用于高铁、火车、航班等涉及展示起点、终点的活动。

7：赛事类型，适用于体育赛事比分场景、游戏赛事比分场景等。

100：自定义实况卡片类型。起始版本： 26.0.0

-1：基础模板，只展示固定区和辅助区。起始版本： 6.1.0(23) （Wearable设备不支持本模板布局类型，设备收到该类型的消息后将不会展示）

说明：

· 当更新实况窗时，type传入非法值，终端设备会使用基础模板进行展示。

· 当创建实况窗时，每种event仅可使用特定的布局类型，详情请参见创建实况窗约束（基础模板不受限制，即每种event都可以使用基础模板创建）；当更新实况窗时，每种event可以使用任何布局类型。
keywords 否 Map<String, String>

实况窗关键词，operation为0且event为如下场景时，必填。

· event为FLIGHT时，仅有flightNo一个keyword，表示航班号，占位符格式：{{flightNo}}。

· event为TRAIN时，仅有trainNo一个keyword，表示火车车次，占位符格式：{{trainNo}}。

消息体中占位符的使用，参见支持携带占位符的字段。
additionalText 否 String 提示信息/免责声明。仅在NotificationData.type=5时可用。（注意消息体大小限制，详情参见使用约束）
keepTime 否 Long

实况窗通知存档期，在结束实况窗通知后，通知仍保留在通知中心的时长，默认0不保留，最多设置1小时，单位：s。

存档期时间以结束实况窗消息中携带的此字段数据为准，存档期期间不支持再次更新或结束通知。
CustomLayout 否 CustomLayout Object

实况窗卡片自定义扩展区，type为100时必填，具体字段请参见CustomLayout结构体。

起始版本： 26.0.0
contentTitle 否 String

通知标题，长度最大1024字符。

operation为0时必填，且不能为空字符串。
contentText 否 Array [RichText Object]

通知内容，由多段富文本RichText组成，文本长度总和不超过1024字符，若设置文本颜色，只允许设置为同一种颜色。

operation为0时必填，且不能为空Array。
richProgress 否 RichProgress Object 丰富进度信息，type为3时必填，具体字段请参见RichProgress结构体。
singleTextBlock 否 SingleTextBlock Object 强调文本模板样式中，强调的文本块，type为4时必填，默认占据左侧扩展区，具体字段请参见SingleTextBlock结构体。
firstTextBlock 否 FirstTextBlock Object 多文本块布局中的左侧文本块，type为5时必填，详情可参见FirstTextBlock结构体。
lastTextBlock 否 LastTextBlock Object 多文本块布局中的右侧文本块，type为5时必填，详情可参见LastTextBlock结构体。
displayHorizontalLine 否 Boolean

是否显示扩展区域的分割线，不设置默认显示分割线。

true：显示。

false：不显示。

说明：

当type为5或7时才会显示分割线。
spaceIcon 否 String

间隔图标的文件名，type为5时占据扩展区中间。

当operation为0，type为5，spaceType未传或者spaceType为0时必填，且不能为空字符串。

取值为在指定路径下的文件名。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。
spaceIconUrl 否 String

间隔图标的URL链接，type为5时占据扩展区中间，URL使用的协议必须是HTTPS协议，图片链接不能为空字符串。（注意消息体大小限制，详情参见使用约束）

说明：

优先显示spaceIconUrl链接中的图片，如果图片无法显示，则展示spaceIcon中的图片。

支持图片的格式为PNG、JPG、JPEG、BMP、WEBP，传入图片的大小不超过512KB，若超过则图片不展示。

起始版本： 26.0.0
spaceText 否 String

间隔文本，type为5时占据扩展区中间。

operation为0，type为5，spaceType为1时必填，且不能为空字符串。（注意消息体大小限制，详情参见使用约束）
style 否 Integer

左右文本样式类型。

0：强调型。

1：均衡型。

说明：

创建时未传style字段将使用强调型展示。
spaceType 否 Integer

间隔类型。

0：使用图标。

1：使用文本。

说明：

创建时未传spaceType字段将使用图标展示。
extend 否 Extend Object

辅助区样式，无更新时可不携带。具体字段请参见Extend结构体。

说明：

更新type类型为新布局时，需重新携带本字段。

刷新实况窗通知内容时，辅助区显示类型为图片且图片路径填写错误会导致刷新内容失败。
game 否 Game Object 赛事信息扩展区，type为7时必填，具体字段请参见Game结构体。
descPic 否 String

扩展区域描述图片文件名。扩展区域描述图片默认存放在应用的“/resources/rawfile”路径下。

当operation为0且type为4时，此字段必填，并且不可为空字符串。

当type为4且descPic不为空时，图片会占据右侧扩展区。不携带该值且系统显示时采用上次刷新的图像。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。
descPicUrl 否 String

扩展区域描述图片的URL链接，默认不显示。

当type为4时且descPic不为空时，图片会占据右侧扩展区，URL使用的协议必须是HTTPS协议，图片链接不能为空字符串。不携带该值且系统显示时采用上次刷新的图像。（注意消息体大小限制，详情参见使用约束）

说明：

优先显示descPicUrl链接中的图片，如果图片无法显示，则展示descPic中的图片。

支持图片的格式为PNG、JPG、JPEG、BMP、WEBP，传入图片的大小不超过512KB，若超过则图片不展示。

起始版本： 26.0.0
clickAction 是 ClickAction Object 消息点击行为，具体字段请参见ClickAction结构体。
lockScreen 否 LiveViewLockScreen Object

锁屏沉浸实况窗相关字段，具体字段请参见LiveViewLockScreen结构体。

说明：

Wearable设备不支持该特性，携带该字段的消息将不会展示。
weather 否 Weather Object

传入天气信息结构体。需要同时传入天气类型、天气位置类型与最高最低温度参数，才会在卡片上展示天气。仅支持左右文本模板（即type为5）。

当传入天气类型为雨、雪特殊天气，且同时传入实况窗卡片的背景氛围类型参数backgroundType（合法值参见Live View Kit BackgroundType枚举值）为赏月航班或夕阳航班对应的值时，卡片上优先展示天气背景，其余非特殊天气在卡片上优先展示赏月航班或夕阳航班背景氛围。

说明：

Wearable设备不支持该特性，携带该字段的消息将不会展示。
backgroundType 否 Integer

表示实况窗卡片的背景氛围类型，仅支持左右文本模板（即type为5），合法值参见Live View Kit BackgroundType枚举值。

当传入实况窗卡片的背景氛围类型参数为赏月航班或夕阳航班对应的值时，且同时传入天气类型（Weather）为雨、雪特殊天气，卡片上优先展示天气背景，其余非特殊天气在卡片上优先展示赏月航班或夕阳航班背景氛围。

说明：

Wearable设备不支持该特性，携带该字段的消息将不会展示。

[h2]CustomLayout

参数 是否必选 参数类型 描述
abilityName 是 String

LiveViewCardExtensionAbility（实况窗卡片自定义扩展区的扩展Ability）的名称。字符串长度需小于128。值不能为以下内容：null/undefined/空字符串。

起始版本： 26.0.0
abilityParameters 否 Map<String, String>

LiveViewCardExtensionAbility（实况窗卡片自定义扩展区的扩展Ability）传入的自定义参数。填值时可以为空，key-value键值对最多50个，传入后可在LiveViewCardExtensionAbility的onRender()中，通过param获取。

起始版本： 26.0.0

[h2]Extend

参数 是否必选 参数类型 描述
type 否 Integer

辅助区显示类型：

0：不显示（默认值）

1：显示普通文本

2：显示胶囊文本

3：显示图片（辅助区区域大小44*44vp，设置的图片会保持宽高比进行缩小或者放大，使得完全显示在辅助区区域的边界内）

4：显示Icon（辅助区区域大小44*44vp，设置的图片会保持宽高比显示，在辅助区区域内缩小或者保持不变）
text 否 String 辅助区文本信息，当type为1或2时必填，且不能为空字符串。（注意消息体大小限制，详情参见使用约束）
pic 否 String

辅助区图片信息，当type为3或4时必填，且不能为空字符串。

取值为在指定路径下的文件名。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。

说明：

本字段即将停止维护，请及时切换使用image字段。
image 否 String

辅助区图片文件名，辅助区图片默认存放在应用的“/resources/rawfile”路径下。

当type为3或4时必填，且不能为空字符串。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。
imageUrl 否 String

辅助区图片的URL链接，URL使用的协议必须是HTTPS协议，图片链接不能为空字符串。（注意消息体大小限制，详情参见使用约束）

说明：

优先显示imageUrl链接中的图片，如果图片无法显示，则展示image中的图片。

支持图片的格式为PNG、JPG、JPEG、BMP、WEBP，传入图片的大小不超过512KB，若超过则图片不展示。

起始版本： 26.0.0
clickAction 否 ClickAction Object

辅助区的点击行为，具体字段请参见ClickAction结构体的定义。

若不携带该字段，则辅助区不支持点击跳转。

[h2]Game

参数 是否必选 参数类型 描述
host 是 Team Object 扩展区左侧样式，具体字段请参见Team结构体。
guest 是 Team Object 扩展区右侧样式，具体字段请参见Team结构体。
competition 是 Competition Object 扩展区中部样式，具体字段请参见Competition结构体。

[h2]Team

参数 是否必选 参数类型 描述
icon 否 String

展示区队伍图标文件名，默认存放在应用的“/resources/rawfile”路径下。

当operation为0时必填，且不可为空字符串。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。
iconUrl 否 String

展示区队伍图标的URL链接，URL使用的协议必须是HTTPS协议，图片链接不能为空字符串。（注意消息体大小限制，详情参见使用约束）

说明：

优先显示iconUrl链接中的图片，如果图片无法显示，则展示icon的图片。

支持图片的格式为PNG、JPG、JPEG、BMP、WEBP，传入图片的大小不超过512KB，若超过则图片不展示。

起始版本： 26.0.0
name 否 String 队伍名称，当operation为0时必填，且不可为空字符串。（注意消息体大小限制，详情参见使用约束）
score 否 String 赛事比分，当operation为0时必填，且不可为空字符串。（注意消息体大小限制，详情参见使用约束）

[h2]Competition

参数 是否必选 参数类型 描述
desc 否 String 扩展区中间上方描述文本，当operation为0时，和richDesc至少有一个，且不可为空字符串。（注意消息体大小限制，详情参见使用约束）
richDesc 否 Array [RichText Object] 扩展区中间上方描述富文本，当operation为0时，和desc至少有一个，且不可为空Array，且Array中的text拼接完后，不能为空串。（注意消息体大小限制，详情参见使用约束）
time 否 String 扩展区中间下方比赛时间，当operation为0时必填，且不可为空字符串。（注意消息体大小限制，详情参见使用约束）

[h2]LiveViewLockScreen

参数 是否必选 参数类型 描述
picture 否 String

锁屏沉浸实况窗展示的图片。

取值为在指定路径下的文件名。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。

[h2]CapsuleData

以下展示胶囊的三种场景模板以及相对应的参数。

图示 说明

定义实况胶囊基本属性的基类：

· 1 胶囊布局类型，对应type字段。

· 2 实况胶囊的图标，对应icon和iconUrl字段。

· 3 实况胶囊的尾部图标，对应tailIcon和tailIconUrl字段。

· 4 实况胶囊副文本是否展示，对应isContentDisplayed字段。

· 5 实况胶囊尾部图标是否展示，对应isTailIconDisplayed字段。

type为1时展示该内容：

· 1 胶囊状态主文本，对应title字段。

· 2 胶囊内容，对应content字段。

type为2时展示该内容：

· 1 胶囊内容，对应content字段。

· 2 胶囊计时器初始值，对应capsuleTimer中的time字段。

· 3 是否倒计时显示计时器，对应capsuleTimer中的countDown字段。

· 4 胶囊计时器是否暂停，对应capsuleTimer中的pause字段。

type为3时展示该内容：

· 1 进度最大值，对应progress中的max字段。

· 2 进度当前值，对应progress中的progress字段。

· 3 进度显示类型，对应progress中的indeterminate字段。

· 4 胶囊内容，对应content字段。
参数 是否必选 参数类型 描述
type 是 Integer

胶囊布局类型：

1：图标+文本类型，胶囊显示：左侧图标，右侧文本。

2：计时器类型，胶囊显示：左侧图标，右侧计时文本。

3：进度类型，胶囊显示：整体进度，左侧图标，右侧百分比/数值占比。
status 是 Integer

在状态栏上以实况窗胶囊的形式呈现应用实况业务时：

1：胶囊显示。

-1：胶囊不显示。
icon 是 String

实况胶囊的图标文件名。推荐使用18*18vp的纯色矢量图标。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。
iconUrl 否 String

实况胶囊的图标的URL链接，URL使用的协议必须是HTTPS协议，图片链接不能为空字符串。（注意消息体大小限制，详情参见使用约束）

说明：

优先显示iconUrl链接中的图片，如果图片无法显示，则展示icon中的图片。

支持图片的格式为PNG、JPG、JPEG、BMP、WEBP，传入图片的大小不超过512KB，若超过则图片不展示。

起始版本： 26.0.0
tailIcon 否 String

实况胶囊的尾部图标文件名。推荐使用18*18vp的纯色矢量图标。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。

起始版本： 26.0.0
tailIconUrl 否 String

实况胶囊的尾部图标的URL链接，URL使用的协议必须是HTTPS协议，图片链接不能为空字符串。（注意消息体大小限制，详情参见使用约束）

说明：

优先显示tailIconUrl链接中的图片，如果图片无法显示，则展示tailIcon的图片。

支持图片的格式为PNG、JPG、JPEG、BMP、WEBP，传入图片的大小不超过512KB，若超过则图片不展示。

起始版本： 26.0.0
isTailIconDisplayed 否 Boolean

实况胶囊的尾部图标是否展示。

该参数未填时，继承上一次创建或更新实况窗时传入的值。其他情况不传值时默认不展示。

· true：展示。

· false：不展示。

起始版本： 26.0.0
bgColor 是 String

胶囊背景色"#ARGB"16进制格式，长度为9。

避免与实况胶囊的底色冲突，确保显示效果，以下颜色不能使用：

#FF000000

#FFFFFFFF

#FFF1F3F5
remind 否 String

胶囊在状态栏的动态效果，不携带时默认无特殊效果。

· DEFAULT：无特殊效果。

· FLIP：抢占胶囊位置动态，最高支持5次/活动。

· EXPAND：胶囊自动展开成悬浮卡片动态，最高支持2次/活动。
title 否 String

胶囊状态主文本，长度不超过128字符。

当operation为0且type为1时必填。

当type为1时，该字段用于设置胶囊标题。
content 否 String

胶囊内容，长度不超过128字符；当设备为宽屏或设备横屏时，显示该扩展文本。

当operation为0且type为1或2时必填。
isContentDisplayed 否 Boolean

实况胶囊副文本是否展示。

该参数未填时，继承上一次创建或更新实况窗时传入的值。其他情况不传值时默认为展示。

· true：展示。

· false：不展示。

起始版本： 26.0.0
capsuleTimer 否 CapsuleTimer Object

胶囊计时器，具体字段请参见CapsuleTimer结构体。

当type为2时必选，该字段用于设置胶囊计时器信息。
progress 否 Progress Object

胶囊进度信息，具体字段请参见Progress结构体。

当type为3时必选，该字段用于设置胶囊进度信息。

[h2]Progress

参数 是否必选 参数类型 描述
max 否 Integer 进度最大值，默认为1，范围为[1, 2147483647]。
progress 是 Integer 进度当前值，范围为[0, 2147483647]，小于等于进度最大值。
indeterminate 否 Boolean

进度显示类型，默认显示为数值占比。

true：百分比。

false：数值占比。

[h2]SingleTextBlock

参数 是否必选 参数类型 描述
firstLine 是 String 首行文本，长度不超过128字符，且不能为空字符串。
secondLine 是 String 次行文本内容，长度不超过128字符，且不能为空字符串。
underlineColor 否 String 次行文本内容下划线颜色，"#ARGB"16进制格式，长度为9，不设置则不显示下划线。

[h2]FirstTextBlock

参数 是否必选 参数类型 描述
firstLine 是 String 首行文本，长度不超过128字符，且不能为空字符串。
secondLine 是 String 次行文本内容，长度不超过128字符，且不能为空字符串。

[h2]LastTextBlock

参数 是否必选 参数类型 描述
firstLine 是 String 首行文本，长度不超过128字符，且不能为空字符串。
secondLine 是 String 次行文本内容，长度不超过128字符，且不能为空字符串。
firstLineSuperscript 否 String 首行文本右上角的上标字段，固定格式"+x"，x取值范围为1-9，否则不展示。
secondLineSuperscript 否 String 次行文本右上角的上标字段，固定格式"+x"，x取值范围为1-9，否则不展示。

[h2]RichProgress

参数 是否必选 参数类型 描述
indicatorIcon 否 String

进度条指示器图标，本地资源，不携带时系统显示时采用上次刷新的图像。

当operation为0且indicatorType为1或2时，必填，且不能为空字符串。

取值为在指定路径下的文件名。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。
progress 是 Integer 进度百分比，进度值0-100，决定指示器在进度条中的位置。
color 否 String 进度指示器左侧的进度点及节点图标的颜色，"#ARGB"16进制格式，长度为9，默认值为#FF317AF7，表示蓝色。
bgColor 否 String 进度指示器右侧的进度点及节点图标的颜色，"#ARGB"16进制格式，长度为9，默认值为#19000000，表示灰色。深色模式默认值为#19FFFFFF，表示白色。
nodeIcons 否 Array [String]

进度条每个节点的图标，数组长度范围为[2, 5]，本地资源，不携带时系统显示时采用上次刷新的图像。

当operation为0时必填，且不能为空Array。

取值为在指定路径下的文件名。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。
type 否 Integer

扩展区进度显示类型：

0：虚线进度（默认值）。

1：普通实线进度。

2：粗实线进度。
indicatorType 否 Integer

扩展区指示器小图标显示类型：

0：不显示指示器小图标 （默认值） 。

1：显示在进度线上方。

2：显示覆盖在进度线上。

[h2]CapsuleTimer

参数 是否必选 参数类型 描述
time 否 Long 胶囊计时器初始值，每秒刷新一次。单位：ms，默认为0。
countDown 否 Boolean

是否倒计时显示计时器，默认正计时。

false：正计时显示。

true：倒计时显示。
pause 否 Boolean

胶囊计时器是否暂停，默认不暂停。

false：不暂停。

true：暂停，计时器暂停时，胶囊会显示暂停的那一秒。

[h2]ExternalData

参数 是否必选 参数类型 描述
type 否 Integer

外屏模板类型：

0：背景色类型 （默认值）

1：背景图片类型
bgColor 否 String 外屏背景颜色，"#RGB"16进制格式，长度为7，不设置时使用系统默认颜色。
bgImage 否 String

外屏背景图片，本地资源，当type为1时，第一次创建实况窗时必须设置，后续不更新时可不设置。

当operation为0且type为1时必填，且不为空字符串。

取值为在指定路径下的文件名。

示例：图标文件“icon.png”存放在应用的“/resources/rawfile”路径下，则取值为“icon.png”。
title 否 String

自定义的外屏通知标题，总长度不超过128字符。

当operation为0时必填，且不为空字符串。
body 否 Array [RichText Object]

自定义的外屏通知内容，由多段富文本RichText组成，文本长度总和不超过128字符，若设置文本颜色，只允许设置为同一种颜色。

当operation为0时必填，且不为空Array。

[h2]RichText

参数 是否必选 参数类型 描述
text 是 String 文本。（注意消息体大小限制，详情参见使用约束）
foregroundColor 否 String 文字颜色，"#ARGB"16进制格式，长度为9。不设置foregroundColor时，文本颜色默认为#FF000000；设置foregroundColor时，数组中的所有对象仅能设置一种颜色。

[h2]Weather

参数 是否必选 参数类型 描述
weatherType 否 Integer 天气类型，weatherType不传入或传入非法值，则不展示天气。合法值参见Live View Kit WeatherType枚举值。
locationType 否 Integer 天气位置类型，locationType不传入或传入非法值，则不展示天气。合法值参见Live View Kit WeatherLocationType枚举值。
highTemperature 否 Integer 天气最高温度，当前仅支持摄氏度，需小于等于58℃且大于传入的最低温度值（lowTemperature）。不传入或传入非法值，则不展示天气。
lowTemperature 否 Integer 天气最低温度，当前仅支持摄氏度，需大于等于-95℃且小于传入的最高温度值（highTemperature）。不传入或传入非法值，则不展示天气。

VoIPCallPayload 应用内通话消息

请求体示例请见应用内通话消息。

参数 是否必选 参数类型 描述
extraData 是 String

传递给应用的数据，应用根据数据自行处理相关逻辑，展示应用内通话消息相关信息。（注意消息体大小限制，详情参见使用约束）

extraData数据获取请参考示例代码。