프리셋 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을 사용합니다.

인증

모든 요청에는 서버 API 토큰이 포함된 Authorization 헤더가 있어야 합니다:

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 및 위의 메시징/Journey API에 전달합니다.
• 플랫폼 키: platforms 및 open_actions 맵은 숫자 기기 유형 코드로 키가 지정됩니다(1은 iOS, 3은 Android 등). platform_properties는 대신 플랫폼의 enum 이름으로 키가 지정됩니다(IOS, ANDROID, BAIDU_ANDROID, HUAWEI_ANDROID, OSX — 이 다섯 가지 플랫폼만 해당됩니다).
• 채워지지 않은 필드: Get, Create, Clone 응답은 비어 있거나 0 값인 경우에도 프리셋 객체의 모든 필드를 포함합니다. List는 축소된 필드 세트를 반환합니다. 아래 목록을 참조하세요. Update 및 UpdatePartial은 프리셋 필드를 전혀 반환하지 않습니다. 해당 섹션의 주의사항을 참조하세요.

오류 응답

HTTP 상태	의미
400 Bad Request	잘못된 인수 — 필수 필드가 누락되었거나 형식이 잘못되었거나 사전 조건이 실패했습니다(예: name 없이 복제).
401 Unauthorized	누락되었거나 잘못된 Authorization 헤더입니다.
403 Forbidden	애플리케이션 또는 프리셋이 호출자의 계정에 속하지 않습니다.
404 Not Found	프리셋 또는 애플리케이션을 찾을 수 없습니다.
500 Internal Server Error	예상치 못한 서버 측 오류입니다.

실행 중이거나 일시 중지된 Journey의 푸시 전송 지점에서 여전히 사용 중인 프리셋에 대한 Delete 요청도 400 Bad Request(FailedPrecondition 오류)를 반환하며, 409가 아닙니다. 먼저 Journey에서 프리셋을 제거해야 합니다.

엔드포인트

메서드	경로	설명
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	아니요	0부터 시작하는 페이지 인덱스입니다.
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는 예외입니다. 이 필드들은 전송할 때만 변경되고 생략하면 변경되지 않은 상태로 유지됩니다.

첫 번째 그룹도 생략 시 변경되지 않도록 하려면 UpdatePartial을 사용하세요.

응답에 프리셋 필드가 없습니다

Update는 빈 객체인 {}를 반환합니다. 응답 메시지는 기술적으로 preset 필드를 정의하지만 서버는 이 필드를 채우지 않습니다. 업데이트된 객체를 다시 받아야 하는 경우 나중에 Get을 호출하세요.

응답

성공 시 빈 객체: {}.

부분 업데이트

코드로 기존 푸시 프리셋의 제공된 필드만 업데이트하고 설정되지 않은 필드는 변경하지 않은 상태로 둡니다.

PUT /api/presets/{code}:partial

경로 파라미터

파라미터	유형	설명
code	string	패치할 프리셋의 코드입니다.

요청 본문

Update와 동일한 필드(application 제외)입니다. Update와 달리, 여기의 모든 필드(localizedProperties, platformProperties, categories 및 Update의 주의사항에 나열된 나머지 콘텐츠 속성 그룹 포함)는 생략 시 변경되지 않고 전송할 때만 변경됩니다(전송하는 맵/배열 필드는 해당 필드의 기존 값을 완전히 대체하지만, 포함하지 않은 다른 필드에는 영향을 주지 않습니다). 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}

주의

실행 중이거나 일시 중지된 Journey의 send_push 지점에서 프리셋이 여전히 사용 중인 경우 실패합니다. 먼저 Journey에서 제거해야 합니다. 이 작업은 되돌릴 수 없습니다.

경로 파라미터

파라미터	유형	설명
code	string	삭제할 프리셋의 코드입니다.

응답

성공 시 빈 객체: {}.

객체 참조

아래 필드 이름은 Get, Create, Update, Clone이 실제로 반환하는 값과 일치합니다. 즉, snake_case proto 필드 이름입니다(규칙 참조). 위의 요청 예시에 사용된 lowerCamelCase 형식은 입력 시 동일하게 작동합니다.

프리셋 객체

ID

필드	유형	설명
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>	레거시 플랫폼별 재정의이며, 플랫폼 enum 이름(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	Journey의 푸시 전송 지점에서 생성된 경우, 이 프리셋을 소유한 Customer Journey의 UUID입니다.
custom_data	object	클라이언트 SDK에 u 파라미터로 전달되는 자유 형식의 JSON입니다.
banner	string	큰 그림 / 첨부 이미지 URL입니다.
icon	string	사용자 지정 알림 아이콘 URL입니다.

전송 제한

필드	유형	설명
send_rate	integer	이 프리셋을 사용하는 전송에 대한 스로틀링(초당 메시지 수)입니다. Notify의 SendRate와 프리셋 수준에서 동일합니다.
capping_count / capping_days	integer	이 프리셋에 대한 사용자별 빈도 제한입니다. Notify의 FrequencyCapping count / days와 프리셋 수준에서 동일합니다.

웹훅

필드	유형	설명
notification_sent_url	string	이 프리셋을 사용하는 알림이 전송될 때 요청되는 콜백 URL입니다.
notification_delivered_url	string	이 프리셋을 사용하는 알림이 전달될 때 요청되는 콜백 URL입니다.
notification_click_url	string	이 프리셋을 사용하는 알림이 클릭될 때 요청되는 콜백 URL입니다.

레거시 필드

이 필드들은 v1 프리셋 모델에서 가져온 것입니다. 새로운 통합보다는 Control Panel 호환성을 위해 채워집니다.

필드	유형	설명
remote_page	string	레거시 원격 페이지 참조입니다.
wns_content	string	v1 createPreset/getPreset 메서드에서 허용되는 레거시 Windows 토스트 템플릿 JSON입니다.
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만 해당).

관련 항목

Notify

페이로드 참조

Customer Journey 지점 참조