预设 API

推送预设是一个可重用的推送通知模板——与您在控制面板的推送编辑器中构建的对象相同。此 API 仅管理推送预设；SMS、WhatsApp、Kakao、LINE 和 Viber 预设各有其专用的预设服务，此处不作介绍。

使用预设的 code 通过 Notify（有效负载 preset）或 Customer Journey 发送推送点来发送它。

基本 URL

https://rpc-api.svc-nue.pushwoosh.com

所有端点都通过 HTTPS 提供服务。除非另有说明，否则请求和响应使用 application/json。

身份验证

每个请求都必须包含一个 Authorization 标头，其中包含您的服务器 API 令牌：

Authorization: Api YOUR_API_TOKEN

约定

• 字段命名： 请求正文和查询/路径参数接受 lowerCamelCase（例如，sendType、localizedProperties、searchByName）——服务器会解组任何一种大小写。响应总是使用 proto 字段名进行编组，格式为 snake_case（localized_properties、platform_properties、per_page 等）。下面的响应示例和预设对象参考使用了这种大小写。
• code： 每个预设响应都带有自己的代码，在 Create 时生成。将此代码传递给 Get、Update、UpdatePartial、Delete、Clone 以及上面的消息/旅程 API。
• 平台键： platforms 和 open_actions 映射以数字设备类型代码（例如，iOS 为 1，Android 为 3 等）为键。platform_properties 则以平台的枚举名称为键（IOS、ANDROID、BAIDU_ANDROID、HUAWEI_ANDROID、OSX——仅涵盖这五个平台）。
• 未填充字段： Get、Create 和 Clone 响应包含预设对象的每个字段，即使为空或零值。List 返回一个简化的字段集——请参阅下面的列出。Update 和 UpdatePartial 完全不返回任何预设字段——请参阅它们部分中的警告。

错误响应

HTTP 状态	含义
400 Bad Request	参数无效——缺少必需字段或格式错误，或前置条件失败（例如，克隆时没有 name）。
401 Unauthorized	缺少或无效的 Authorization 标头。
403 Forbidden	应用程序或预设不属于调用者的帐户。
404 Not Found	未找到预设或应用程序。
500 Internal Server Error	意外的服务器端故障。

对仍在运行或暂停的旅程的发送推送点使用的预设执行 Delete 操作也会返回 400 Bad Request（在线路上是 FailedPrecondition）——而不是 409。请先从旅程中删除该预设。

端点

方法	路径	描述
POST	/api/presets	创建一个新的推送预设
GET	/api/presets	列出应用程序的推送预设
GET	/api/presets/{code}	获取单个推送预设
PUT	/api/presets/{code}	更新推送预设（完全覆盖）
PUT	/api/presets/{code}:partial	更新推送预设（部分）
POST	/api/presets/{code}:clone	克隆推送预设
DELETE	/api/presets/{code}	删除推送预设

创建

在应用程序中创建一个新的推送预设，并返回其生成的代码。

POST /api/presets

请求正文

参数	类型	必需	描述
application	string	是	要在其中创建预设的应用程序代码。
name	string	是	预设名称。
sendType	string	否	预设的渠道（例如 push）。
isV2	boolean	否	固定预设的来源标志。省略则默认为 true (v2)；仅在重现旧版 v1 预设时设置为 false。

所有其他字段——本地化内容、平台、深层链接、收件箱、类别等——都与 Update 共享，并在下面的预设对象参考中统一记录。

请求示例

{
  "application": "XXXXX-XXXXX",
  "name": "20% discount",
  "platforms": { "1": true, "3": true },
  "localizedContent": {
    "default": "Get your 20% discount right now",
    "es": "Consigue tu 20% de descuento ahora mismo"
  },
  "localizedTitle": { "default": "Hi there" },
  "openAction": { "link": { "url": "https://example.com" } },
  "categories": ["promo"]
}

响应

返回 { "preset": { ... } }，即创建的预设对象。

列出

列出应用程序的推送预设——一个简化的字段集，而不是完整的对象——支持分页、排序以及按名称或类别筛选。

GET /api/presets

查询参数

参数	类型	必需	描述
application	string	是	要列出预设的应用程序代码。
orderBy	string	否	NAME（默认）、CREATED 或 UPDATED。
orderDirection	string	否	ASC（默认）或 DESC。
page	integer	否	从零开始的页面索引。
perPage	integer	否	页面大小。省略或为 0 时默认为 100。
searchByName	string	否	对预设名称或代码进行不区分大小写的子字符串匹配（ILIKE %value%）。
searchByCategory	array of strings	否	重复该参数以按多个类别进行筛选，例如 ?searchByCategory=promo&searchByCategory=lifecycle。
showHidden	boolean	否	包括标记为 hidden 的预设。

注意

isDefault 是一个已弃用的筛选器，仅为控制面板中的旧版发送推送表单保留——不要依赖它。

响应

每个项目仅包含：name、code、platforms、localized_content（每个区域的纯文本——不是 localized_properties）、localized_title、localized_subtitle、banner、icon、categories、journey_uuid、custom_data、is_v2、created、updated。预设对象的所有其他字段——localized_properties、platform_properties、deeplink、richmedia、url 等——都会被省略，即使在预设上已设置。

字段	类型	描述
presets	array of objects	当前页的预设，采用上述简化形式。
page	integer	返回的页面索引。
per_page	integer	此响应使用的页面大小。
total	integer	匹配筛选器的预设总数，跨所有页面。

响应示例

{
  "presets": [
    { "name": "20% discount", "code": "AAAAA-BBBBB", "platforms": { "1": true, "3": true }, "categories": ["promo"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

获取

按代码返回单个推送预设，并填充预设对象的所有字段。

GET /api/presets/{code}

路径参数

参数	类型	描述
code	string	预设的代码。

响应

返回 { "preset": { ... } }，即完整的预设对象。

更新

按代码用提供的字段覆盖现有推送预设。

PUT /api/presets/{code}

路径参数

参数	类型	描述
code	string	要覆盖的预设代码。

请求正文

与创建（减去 application）相同的字段，外加预设对象的其余字段。sendType 被接受但被忽略——预设的渠道在创建后无法更改。

省略字段并不总是意味着“保持不变”

Update 在每次调用时都会从头开始重建预设的内容属性：localizedProperties、platformProperties、openAction/openActions、deeplink、deeplinkParams、richmedia、url、campaignCode、filterCode、geoZones、sendRate、cappingCount/cappingDays、三个 notification*Url 字段、remotePage、wnsContent、originalUrl、四个 *Silent 标志、inboxImage/inboxIcon/inboxDays/inboxDate、banner、icon、customData 和 isV2——省略其中任何一个都会被清除（或者，对于 isV2，重置为 true）。

name、platforms、categories、localizedTitle、localizedSubtitle 和 localizedContent 是例外：只有在发送时才会触及它们，省略时保持不变。

如果您希望第一组在省略时也保持不变，请使用部分更新。

响应中没有预设字段

Update 返回 {}——一个空对象。响应消息在技术上定义了一个 preset 字段，但服务器从不填充它。如果需要取回更新后的对象，请在之后调用 Get。

响应

成功时返回一个空对象：{}。

部分更新

按代码仅更新现有推送预设的指定字段，未设置的字段保持不变。

PUT /api/presets/{code}:partial

路径参数

参数	类型	描述
code	string	要修补的预设代码。

请求正文

与更新相同的字段，减去 application。与 Update 不同，此处的每个字段——包括 localizedProperties、platformProperties、categories 以及更新警告中列出的其余内容属性组——在省略时保持不变，只有在发送时才会被触及（您发送的映射/数组字段仍会完全替换该字段的现有值，只是不影响您未包含的任何内容）。sendType 同样被接受但被忽略。

注意

即使在这里，isV2 也是唯一的例外：它在每次 UpdatePartial 调用时都会被重写，省略时默认为 true。如果预设必须保持为 v1 风格的预设，请明确发送 isV2: false。

请求示例

{
  "sendRate": 500,
  "cappingCount": 3,
  "cappingDays": 7
}

响应

同样是一个空对象——请参阅上面的警告。

克隆

将现有推送预设复制到同一个应用程序中，并使用新名称。

POST /api/presets/{code}:clone

注意

与电子邮件模板 API 的 Clone 不同，此端点没有 application 参数——它总是在源预设自己的应用程序内克隆。无论源如何，克隆总是以 hidden: false 创建。

请求正文

参数	类型	必需	描述
code	string	是	要复制的源预设代码。
name	string	是	新预设的名称。

请求示例

{ "code": "AAAAA-BBBBB", "name": "20% discount (copy)" }

响应

返回 { "preset": { ... } }，即新的预设对象。

删除

按代码永久删除推送预设。

DELETE /api/presets/{code}

警告

如果预设仍被运行中或暂停的旅程中的 send_push 点使用，则会失败——请先从旅程中删除它。此操作无法撤销。

路径参数

参数	类型	描述
code	string	要删除的预设代码。

响应

成功时返回一个空对象：{}。

对象参考

下面的字段名称与 Get、Create、Update 和 Clone 实际返回的名称相匹配——snake_case proto 字段名（请参阅约定）。上面请求示例中使用的 lowerCamelCase 形式在输入时同样有效。

预设对象

身份

字段	类型	描述
code	string	在 Create 时生成。在 API 的其他任何地方都用它来标识此预设。
name	string	预设名称。
send_type	string	预设的渠道（例如 push）。
is_v2	boolean	对于创建或迁移到 v2 内容模型的预设为 true。
system	boolean	将预设标记为系统/内部预设。
hidden	boolean	从 List 结果中隐藏预设（发送 showHidden: true 以包含它）。
created	string (RFC 3339)	创建时间戳。
updated	string (RFC 3339)	最后更新时间戳。

定位与内容

字段	类型	描述
platforms	map<string, boolean>	预设所针对的平台，以设备类型代码为键（例如，iOS 为 "1"）。
localized_properties	map<string, object>	区域设置 → 丰富的各平台内容。与 Notify 有效负载上的 LocalizedContent 形状相同——每个平台块（ios、android 等）一个条目。这是设置特定平台推送内容的主要方式。
localized_title / localized_subtitle / localized_content	map<string, string>	区域设置 → 纯文本。当您不需要各平台覆盖时，这是 localized_properties 的一个更简单的替代方案，用于标题、副标题和正文。
platform_properties	map<string, object>	旧版的各平台覆盖，以平台枚举名称（IOS、ANDROID、BAIDU_ANDROID、HUAWEI_ANDROID、OSX）为键。请参阅下面的PlatformProperties 对象。
open_action	OpenAction	用户打开通知时触发的操作，适用于所有平台。与 open_actions 互斥——响应中只设置其中一个。
open_actions	map<string, OpenAction>	open_action 的各平台覆盖，以设备类型代码为键。
deeplink	string	深层链接代码。
deeplink_params	map<string, string>	传递给深层链接的参数。
richmedia	string	通知打开的富媒体代码。
url	string	通知打开的 URL，如果未使用深层链接或富媒体。

收件箱

字段	类型	描述
inbox_image	string	消息收件箱条目中显示的图片 URL。
inbox_icon	string	消息收件箱条目中显示的图标 URL。
inbox_days	integer	条目在消息收件箱中保留的天数。
inbox_date	string (RFC 3339)	消息收件箱条目的明确到期日期，作为 inbox_days 的替代方案。

组织与元数据

字段	类型	描述
categories	array of strings	预设所标记的类别名称。
campaign_code	string	此预设归属的活动代码。
filter_code	string	此预设默认定位的细分/筛选器代码。
geo_zones	string	地理区域定位，如果预设是地理触发的。
journey_uuid	string	拥有此预设的 Customer Journey 的 UUID，如果它是从旅程的发送推送点创建的。
custom_data	object	以 u 参数形式转发到客户端 SDK 的自由格式 JSON。
banner	string	大图/附件图片 URL。
icon	string	自定义通知图标 URL。

交付限制

字段	类型	描述
send_rate	integer	使用此预设的发送节流，单位为消息/秒——预设级别的等效于 Notify 的 SendRate。
capping_count / capping_days	integer	此预设的每用户频率限制——预设级别的等效于 Notify 的 FrequencyCapping count / days。

Webhooks

字段	类型	描述
notification_sent_url	string	发送使用此预设的通知时请求的回调 URL。
notification_delivered_url	string	送达使用此预设的通知时请求的回调 URL。
notification_click_url	string	点击使用此预设的通知时请求的回调 URL。

旧版字段

这些字段从 v1 预设模型继承而来。它们是为了与控制面板兼容而填充的，而不是为新的集成而设。

字段	类型	描述
remote_page	string	旧版远程页面引用。
wns_content	string	旧版 Windows toast 模板 JSON，与 v1 createPreset/getPreset 方法接受的格式相同。
original_url	string	url 的缩短前值，当 url 被缩短链接替换时。
ios_silent / android_silent / baidu_android_silent / huawei_android_silent	boolean	各平台的静默（仅数据）推送标志。

PlatformProperties 对象

每个 platform_properties 条目（IOS、ANDROID、BAIDU_ANDROID、HUAWEI_ANDROID、OSX）中可用的字段：

字段	类型	描述
badge	string	角标数量覆盖。
sound	string	声音文件名。
sound_off	boolean	静音通知声音。
priority	string	托盘内优先级（仅限 Android/Baidu/Huawei）。
delivery_priority	string	NORMAL 或 HIGH 交付优先级（仅限 Android/Baidu/Huawei）。
ios_interruption_level	string	passive、active、time-sensitive 或 critical（仅限 iOS）。

相关

通知

有效负载参考

Customer Journey 点参考