预设 API

一个推送预设是一个可重复使用的推送通知模板——与您在 Control Panel 的推送编辑器中构建的对象相同。此 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、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。请先从旅程中移除该预设。

Create、Update 和 UpdatePartial 对于无法解析的个性化令牌也会返回 400 Bad Request——见下文。

个性化令牌

Create、Update 和 UpdatePartial 会验证 localizedTitle、localizedSubtitle 和 localizedContent（针对请求中的每种语言）以及发送方替换的每个平台的富内容字段（标题、内容、横幅、图标、URL、深层链接参数等）中的每个个性化令牌 ({name|modifier|default})。在此集合之外的字段，如 richmedia、campaignCode、deeplink 或 filterCode，会完全按原样保留令牌——Pushwoosh 不会在此处解析个性化语法。

令牌需要一个 Pushwoosh 识别的修饰符，因为未经修改或拼写错误的令牌无法格式化，否则会以字面大括号的形式到达用户。缺少或未知修饰符的令牌（{Tag|}、{Tag|typo}）会导致调用失败，并返回 InvalidArgument：

{
  "code": 3,
  "message": "personalization token {Tag|} has no known modifier, so it would be delivered as text; expected one of [capitalizefirst capitalizeallfirst uppercase lowercase regular base64 cent dollar comma euro jpy lira M-d-y m-d-y M d y M d Y l M d H:i m-d-y H:i]"
}

警告

UpdatePartial 时，此检查会针对预设已保存的整个替换内容字段集运行，而不仅仅是当前请求中的字段——如果一个预设在未触及的字段中已存在损坏的令牌，那么在修复该令牌之前，后续的每个 UpdatePartial 调用都会失败。localizedTitle、localizedSubtitle 和 localizedContent 是例外：它们仅在同一调用包含它们时才被检查。

接受的修饰符

Control Panel 的个性化选择器已经为 INTEGER/PRICE 标签（包括日期格式）和字符串标签提供了以下所有修饰符，除了 base64——该修饰符只能通过 API 访问。gitlab.corp.pushwoosh.com/channels/sdk/pkg/dynamiccontent 是 Control Panel 和此 API 进行验证的真实来源。

修饰符	标签类型	注意事项
capitalizefirst	string	不区分大小写
capitalizeallfirst	string	不区分大小写
uppercase	string	不区分大小写
lowercase	string	不区分大小写
regular	string or integer	不区分大小写，不应用格式化
base64	string	不区分大小写，仅限 API——CP 选择器不提供
cent / dollar / comma / euro / jpy / lira	integer	不区分大小写
M-d-y, m-d-y, M d y, M d Y, l, M d, H:i, m-d-y H:i	integer	日期格式修饰符，完全按书写匹配，包括大小写

端点

方法	路径	描述
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 是一个已弃用的过滤器，仅为 Control Panel 中的旧版发送推送表单保留——不要依赖它。

响应

每个项目仅包含：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

注意

与 Email Templates 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、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 预设模型继承而来的。它们的填充是为了与 Control Panel 兼容，而不是为了新的集成。

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

PlatformProperties 对象

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

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

相关

通知

负载参考

Customer Journey 点参考