프리셋 API

푸시 프리셋은 재사용 가능한 푸시 알림 템플릿으로, 제어판의 푸시 편집기에서 만드는 것과 동일한 객체입니다. 이 API는 푸시 프리셋만 관리합니다. SMS, WhatsApp, Kakao, LINE, Viber 프리셋은 각각 전용 프리셋 서비스를 가지고 있으며, 여기서는 다루지 않습니다.

프리셋의 code를 사용하여 Notify(페이로드 preset)를 통해 보내거나 Customer Journey의 Send push point를 통해 보낼 수 있습니다.

기본 URL

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

모든 엔드포인트는 HTTPS를 통해 제공됩니다. 요청과 응답은 별도의 언급이 없는 한 application/json을 사용합니다.

인증

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

Authorization: Api YOUR_API_TOKEN

규칙

• 필드 이름 지정: 요청 본문과 쿼리/경로 파라미터는 lowerCamelCase(예: sendType, localizedProperties, searchByName)를 허용합니다. 서버는 두 케이스 모두를 언마샬링합니다. 응답은 항상 프로토 필드 이름을 사용하여 snake_case(localized_properties, platform_properties, per_page 등)로 마샬링됩니다. 아래의 응답 예시와 프리셋 객체 참조는 해당 케이스를 사용합니다.
• code: 모든 프리셋 응답은 Create 시 생성된 고유한 코드를 가집니다. 이 코드를 Get, Update, UpdatePartial, Delete, Clone 및 위의 메시징/Journey API에 전달하십시오.
• 플랫폼 키: platforms 및 open_actions 맵은 숫자 장치 유형 코드(iOS의 경우 1, Android의 경우 3 등)로 키가 지정됩니다. platform_properties는 대신 플랫폼의 열거형 이름(IOS, ANDROID, HUAWEI_ANDROID, OSX — 이 네 가지 플랫폼만 해당)으로 키가 지정됩니다.
• 채워지지 않은 필드: Get, Create, Clone 응답은 비어 있거나 0 값인 경우에도 프리셋 객체의 모든 필드를 포함합니다. List는 축소된 필드 세트를 반환합니다. 아래 List를 참조하십시오. Update 및 UpdatePartial은 프리셋 필드를 전혀 반환하지 않습니다. 해당 섹션의 주의사항을 참조하십시오.

오류 응답

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

실행 중이거나 일시 중지된 Journey의 Send push point에서 여전히 사용 중인 프리셋에 대해 Delete를 실행하면 409가 아닌 400 Bad Request(실제로는 FailedPrecondition)가 반환됩니다. 먼저 Journey에서 프리셋을 제거하십시오.

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는 예외입니다. 이들은 동일한 호출에 포함될 때만 확인됩니다.

허용되는 수정자

제어판의 개인화 선택기는 이미 아래의 모든 수정자를 INTEGER/PRICE 태그(날짜 형식 포함)와 문자열 태그에 제공합니다. 단, base64는 예외로 API를 통해서만 접근할 수 있습니다. gitlab.corp.pushwoosh.com/channels/sdk/pkg/dynamiccontent는 제어판과 이 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	아니요	0부터 시작하는 페이지 인덱스.
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는 예외입니다. 각 필드는 보낼 때만 수정되고 생략하면 변경되지 않은 상태로 유지됩니다.

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

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

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}

주의

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

경로 파라미터

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

응답

성공 시 빈 객체: {}.

객체 참조

아래 필드 이름은 Get, Create, Update, Clone이 실제로 반환하는 것과 일치합니다 — snake_case 프로토 필드 이름(규칙 참조). 위의 요청 예시에서 사용된 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	Journey의 Send push point에서 생성된 경우, 이 프리셋을 소유한 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의 프리셋 수준에 해당합니다.

웹훅

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

레거시 필드

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

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

관련 자료

Notify

페이로드 참조

Customer Journey 포인트 참조