페이로드 참조

이메일이 아닌 채널(푸시, SMS, 텔레그램, 카카오, 라인, 바이버, 왓츠앱)을 통해 전송할 때 Notify에서 사용하는 Payload 메시지에 대한 참조입니다.

페이로드

preset (string): 이 메시지에 적용할 푸시 프리셋 코드(XXXXX-XXXXX 형식).
sms_preset (string): 저장된 SMS 프리셋의 코드(XXXXX-XXXXX 형식). 로캘별 텍스트는 각 로캘의 sms.body로 해석됩니다. 특정 로캘에 대한 인라인 sms.body는 해당 로캘의 프리셋을 재정의합니다. 프리셋은 메시지와 동일한 애플리케이션에 속해야 합니다.
content (LocalizedContent): 메시지 콘텐츠. silent와 상호 배타적입니다.
silent (bool): 자동(데이터 전용) 푸시를 보냅니다. content와 상호 배타적입니다.
custom_data (object): 클라이언트 SDK에 u 매개변수로 전달되는 자유 형식의 JSON.
open_action (OpenAction): 사용자가 알림을 열 때 트리거되는 작업.
open_actions (map<Platform, OpenAction>): open_action의 플랫폼별 재정의. 키는 숫자 Platform 열거형 값입니다.
voip_push (bool): iOS VoIP 알림.

{
  "payload": {
    "preset": "XXXXX-XXXXX",
    "content": { "localized_content": { "default": { "ios": { "title": "Hello", "body": "Tap to view" } } } },
    "custom_data": { "order_id": "42" },
    "open_action": { "link": { "url": "https://example.com/promo" } }
  }
}

LocalizedContent

로캘 코드를 플랫폼별 콘텐츠에 매핑합니다. 키는 ISO 639-1 두 글자 코드(예: "en", "es")와 모든 것을 포괄하는 번역을 위한 특수 키 "default"입니다. ISO 639-1의 예외는 번체 및 간체 중국어에 대한 "zh-Hant" 및 "zh-Hans"입니다.

{
  "localized_content": {
    "default": {
      "ios":     { "title": "Hello", "body": "Tap to view" },
      "android": { "title": "Hello", "body": "Tap to view" }
    },
    "es": {
      "ios":     { "title": "Hola",  "body": "Toca para ver" },
      "android": { "title": "Hola",  "body": "Toca para ver" }
    }
  }
}

기기의 로캘 선택

기기로 전달되는 콘텐츠는 다음 순서로 선택됩니다:

기기 언어와 정확히 일치하는 경우.
키 "default".
키 "en".
맵에 있는 다른 모든 로캘.

모든 기기가 결정적인 대체(fallback)를 가질 수 있도록 "default" 또는 "en" 중 하나 이상을 제공하세요. 로캘별 변형을 예상하지 않는 경우 "default"만 보내세요.

각 로캘 항목은 선택적 플랫폼별 블록이 있는 Content 객체입니다. 대상 플랫폼만 채우세요.

플랫폼 블록	채널
`ios`	iOS 푸시
`android`	Android (FCM) 푸시
`huawei_android`	Huawei Android 푸시
`mac_os`	macOS 푸시
`amazon`	Amazon (ADM) 푸시
`safari`	Safari 웹 푸시
`chrome`	Chrome 웹 푸시
`firefox`	Firefox 웹 푸시
`ie`	Internet Explorer 웹 푸시
`windows`	Windows 푸시 (타일 / 토스트 / 배지)
`telegram`	텔레그램 메시지
`kakao`	카카오 메시지
`line`	라인 메시지
`viber`	바이버 메시지
`whatsapp`	왓츠앱 메시지
`sms`	SMS 메시지

공통 푸시 필드

이 필드들은 ios, android, huawei_android, mac_os, amazon, safari, chrome, firefox 블록에서 공유됩니다(지원은 다를 수 있음. 사용되지 않는 필드는 관련 플랫폼에서 무시됨).

title (string): 알림 제목.
body (string): 알림 본문.
time_to_live (duration, 예: "3600s"): 오프라인 기기에 대해 푸시 서버가 알림을 보관해야 하는 시간.
sound (string): 사운드 파일 이름.
sound_enabled (bool): 사운드 활성화 또는 비활성화.
badges (string): 배지 수(iOS) 또는 유사 기능.
root_params (object): 원시 플랫폼별 페이로드 재정의.
inbox (Inbox): 메시지 인박스 항목.

{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "time_to_live": "3600s",
    "sound": "default",
    "sound_enabled": true,
    "badges": "+1"
  }
}

iOS (`ios`)

subtitle (string): iOS 알림 부제목.
is_critical (bool): 긴급 알림(자격 필요).
attachment (string): 미디어 첨부 파일의 URL.
thread_id (string): 그룹화된 알림의 스레드 식별자.
trim_content (bool): 맞게 콘텐츠 자르기.
category_id (string): 상호 작용 작업을 위한 UNNotificationCategory 식별자.
interruption_level (string): passive, active, time-sensitive 또는 critical.
collapse_id (string): APNs 축소 식별자. 동일한 collapse_id를 가진 알림은 기기에서 서로를 대체합니다.

{
  "ios": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "attachment": "https://cdn.example.com/image.png",
    "interruption_level": "active",
    "thread_id": "promo"
  }
}

Android (`android`, `huawei_android`)

icon (string): 알림 작은 아이콘.
banner (string): 큰 사진 URL.
delivery_priority (NORMAL | HIGH): FCM 전송 우선순위.
vibration (bool): 수신 시 진동.
led_color (string, hex): 알림 LED 색상.
icon_background_color (string, hex): 아이콘 배경색.
show_on_lockscreen (bool): 잠금 화면에 표시.
custom_icon (string): 사용자 지정 아이콘의 URL.
priority (NotificationPriority): 트레이 내 우선순위.
group_id (string): 알림 그룹 키.
collapse_key (string): FCM 축소 키. 기기가 오프라인 상태일 때 동일한 collapse_key를 가진 알림은 서로를 대체합니다.

{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "ic_notification",
    "banner": "https://cdn.example.com/banner.png",
    "led_color": "#FF0000",
    "priority": "PRIORITY_HIGH",
    "delivery_priority": "HIGH"
  }
}

macOS (`mac_os`)

공통 푸시 필드와 subtitle 및 action(사용자가 알림을 클릭할 때 열리는 URL)을 사용합니다.

{
  "mac_os": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "action": "https://example.com/promo"
  }
}

Amazon (`amazon`)

공통 푸시 필드와 custom_icon 및 priority (NotificationPriority)를 사용합니다.

{
  "amazon": {
    "title": "Hello",
    "body": "Tap to view",
    "custom_icon": "https://cdn.example.com/icon.png",
    "priority": "PRIORITY_HIGH"
  }
}

Safari (`safari`)

action (string): 사용자가 알림을 클릭할 때 열리는 URL.
url_arguments (array of string): 웹 푸시 URL 템플릿에 대체되는 Safari URL 인수.

{
  "safari": {
    "title": "Hello",
    "body": "Tap to view",
    "action": "https://example.com/promo",
    "url_arguments": ["promo", "2026"]
  }
}

Chrome (`chrome`)

icon, image (string): 작은 아이콘 및 큰 이미지 URL.
duration (duration): 자동 닫기 타이머.
button_text1 / button_url1, button_text2 / button_url2: 최대 두 개의 작업 버튼.

{
  "chrome": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png",
    "image": "https://cdn.example.com/banner.png",
    "duration": "20s",
    "button_text1": "Open",
    "button_url1": "https://example.com/promo"
  }
}

Firefox (`firefox`)

title, body, icon, root_params, inbox만 사용합니다.

{
  "firefox": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png"
  }
}

Windows (`windows`)

Windows는 다른 형태를 사용합니다:

{
  "windows": {
    "type": "TOAST",
    "template": { "title": "Hello", "body": "Tap to view" },
    "tag": "promo",
    "cache": true,
    "time_to_live": "3600s"
  }
}

type은 TILE, TOAST 또는 BADGE입니다.
template (구조화됨) 또는 raw ({ "content": "<raw xml>" }) — 둘 중 하나만 사용합니다.

텔레그램 (`telegram`)

body (string): 메시지 텍스트.
content_variables (string): 봇 측 템플릿을 위한 JSON 문자열화된 변수.

{
  "telegram": {
    "body": "Hello from Pushwoosh",
    "content_variables": "{\"name\":\"John\"}"
  }
}

카카오 (`kakao`)

content (string): 메시지 콘텐츠.
template (string): 승인된 템플릿 코드.
content_variables (string): JSON 문자열화된 템플릿 변수 바인딩.

{
  "kakao": {
    "content": "Hello from Pushwoosh",
    "template": "welcome_v1",
    "content_variables": "{\"name\":\"John\"}"
  }
}

라인 (`line`)

content (string): 일반 텍스트 본문.
template (string): Pushwoosh 제어판에 구성된 라인 템플릿 코드(이미지, 캐러셀 또는 플렉스 메시지를 보내는 데 사용됨). 리치 콘텐츠의 경우 제어판에서 템플릿을 미리 구성하고 여기에서 참조하세요.

content 또는 template 중 하나 이상을 설정해야 합니다.

{
  "line": {
    "content": "Hello from Pushwoosh",
    "template": "promo_carousel"
  }
}

바이버 (`viber`)

Viber 메시지는 자유 텍스트 본문이거나 ID와 언어로 참조되는 사전 승인된 트랜잭션 템플릿(Omni Messaging / MStat)입니다.

body (string): 일반 텍스트 메시지. template_id가 설정되지 않은 경우 필수입니다.
template_id (string): 사전 승인된 트랜잭션 템플릿의 ID. 설정되면 body보다 우선합니다.
template_lang (string): 템플릿 로캘. template_id가 설정된 경우 필수입니다.
template_params (map<string, string>): 템플릿에 대체되는 키/값 바인딩, 예: { "name": "John", "code": "123456" }.
all_devices (bool): false(기본값)는 사용자의 주 기기에만 전달하고, true는 사용자의 모든 기기에 전달합니다.

body 또는 template_id 중 하나 이상을 설정해야 합니다. template_id가 설정된 경우 template_lang이 필요합니다.

Viber 수신자는 viber:<phone>(E.164) 형식의 hwid로 주소를 지정하세요. 예: viber:+1234567890.

일반 텍스트:

{
  "viber": {
    "body": "Hello from Pushwoosh"
  }
}

트랜잭션 템플릿:

{
  "viber": {
    "template_id": "e3dec4a0-c063-4b0f-96d5-cf9d629a7abe",
    "template_lang": "en",
    "template_params": {
      "name": "John",
      "code": "123456",
      "expires_in": "5 minutes"
    },
    "all_devices": false
  }
}

왓츠앱 (`whatsapp`)

WhatsApp 메시지는 Meta를 통해 전달되며 Meta의 메시징 규칙이 적용됩니다. 주요 구분은 자유 형식 텍스트(사용자로부터의 인바운드 메시지로 열린 24시간 고객 서비스 창 내에서만 전달됨)와 승인된 템플릿(아웃바운드 시작 및 24시간 창 외부의 모든 메시지에 필요함) 사이입니다.

content (string): 자유 형식 메시지 텍스트. 24시간 창 내에서만 Meta에 의해 전달됩니다.
content_id (string): 사전 승인된 Meta 템플릿의 이름(예: "hello_world"). 아웃바운드 시작 또는 24시간 창 외부의 모든 메시지에 필요합니다.
language (string): Meta에서 승인된 로캘과 정확히 일치해야 하는 템플릿 로캘(예: "en_US", "en_GB"). content_id와 함께만 의미가 있습니다. 이것은 외부 LocalizedContent 키와는 독립적입니다. 외부 키는 기기의 콘텐츠를 선택하고, language는 해당 콘텐츠의 Meta 템플릿 로캘을 선택합니다.
content_variables (string): 본문 자리 표시자를 매핑하는 JSON 객체, 예: "{\"1\":\"John\"}".
button_url_variables (string): 버튼 인덱스로 키가 지정된 버튼 URL 자리 표시자를 매핑하는 JSON 객체, 예: "{\"0\":\"https://...\"}".
header_variables (string): 유형으로 키가 지정된 헤더 자리 표시자를 매핑하는 JSON 객체, 예: "{\"image\":\"https://...\"}".

content 또는 content_id 중 하나 이상을 설정해야 합니다.

{
  "whatsapp": {
    "content_id": "hello_world",
    "language": "en_US",
    "content_variables": "{\"1\":\"John\"}"
  }
}

SMS (`sms`)

SMS는 각 로캘의 Content 내에 ios, android 및 기타 메시징 채널과 함께 자체 플랫폼 블록을 가집니다.

body (string): 로캘에 대한 SMS 텍스트. sms 블록이 있을 때 필수입니다.

텍스트를 제공하는 두 가지 방법이 있습니다:

인라인 — localized_content에서 로캘별로 sms.body를 설정합니다.
프리셋에서 — 페이로드 수준의 sms_preset을 저장된 SMS 프리셋의 코드(XXXXX-XXXXX 형식)로 설정합니다. 로캘별 콘텐츠는 프리셋이 정의하는 각 로캘에 대해 sms.body로 해석됩니다. 로캘에 대한 인라인 sms.body는 해당 로캘의 프리셋을 재정의하므로 프리셋을 재사용하면서 개별 언어를 조정할 수 있습니다.

{
  "payload": {
    "sms_preset": "XXXXX-XXXXX",
    "content": {
      "localized_content": {
        "default": { "sms": { "body": "Your order has shipped." } },
        "es":      { "sms": { "body": "Tu pedido ha sido enviado." } }
      }
    }
  }
}

MMS

sms 블록에 subject와 file_urls를 추가하면 메시지가 MMS로 바뀝니다. AbleMobile만이 MMS 엔드포인트를 가지고 있으며, 다른 SMS 제공업체는 두 필드를 모두 무시하고 일반 텍스트 body만 전달합니다.

subject (string): MMS 제목. file_urls에 하나 이상의 항목이 필요합니다 — 첨부 파일 없는 제목은 거부됩니다. 최대 40개의 ASCII 문자 또는 제목에 비ASCII 문자가 포함된 경우 13자입니다.
file_urls (array of string): 최대 3개의 첨부 파일 URL. 각각은 .jpg 또는 .gif로 끝나는 절대 https URL이어야 합니다 — .jpeg 및 .png는 제공업체가 디코딩할 수 없기 때문에 실제 JPEG 또는 PNG 파일이라도 유효성 검사에서 거부됩니다. 각 파일은 200KB 이하여야 합니다. AbleMobile은 첨부 파일 중 하나라도 더 무거우면 전체 전송을 거부합니다.
message_at (int): SMS 본문 텍스트가 표시되는 file_urls의 인덱스(0부터 시작).

subject와 file_urls는 body와 마찬가지로 Liquid 개인화를 지원합니다.

{
  "sms": {
    "body": "Your order has shipped.",
    "subject": "Order update",
    "file_urls": [
      "https://cdn.example.com/shipping-label.jpg",
      "https://cdn.example.com/tracking-map.gif"
    ],
    "message_at": 1
  }
}

OpenAction

사용자가 메시지를 열 때 수행되는 작업을 정의합니다.

다음 중 하나만 해당됩니다:

rich_media (RichMedia): 리치 미디어 페이지를 엽니다.
deep_link: 딥 링크를 엽니다: { "code": "flow-code", "params": { "key": "value" } }.
link (Link): URL을 엽니다.

{
  "open_action": {
    "deep_link": { "code": "flow-code", "params": { "promo": "summer" } }
  }
}

딥링크 URL과 params 값은 Liquid 개인화 구문을 지원합니다 — 표현식은 딥 링크가 열리기 전에 해석됩니다.

RichMedia

{ "code": "XXXXX-XXXXX" }        // 리치 미디어 코드로
{ "url":  "https://..." }        // 원격 URL로

Link

{
  "url": "https://example.com/promo",
  "shortener": "BITLY"
}

shortener는 NONE(기본값) 또는 BITLY입니다.

Inbox

메시지 인박스에 메시지가 표시되는 방식을 구성합니다.

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expiration_date": "2026-05-15T00:00:00Z"
}

image_url (string): 인박스 항목에 표시되는 이미지.
expiration_date (timestamp): 항목이 인박스에서 제거되는 시간.

NotificationPriority 열거형

대상 기기에서 알림 우선순위를 제어합니다. PRIORITY_MIN(가장 낮음)부터 PRIORITY_MAX(가장 높음)까지입니다.

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

예시: 세그먼트에 푸시 보내기

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "title": "Hello",   "body": "Hello, world!" },
              "android": { "title": "Hello",   "body": "Hello, world!" }
            },
            "es": {
              "ios":     { "title": "¡Hola!",  "body": "¡Hola, mundo!" },
              "android": { "title": "¡Hola!",  "body": "¡Hola, mundo!" }
            }
          }
        },
        "open_action": { "link": { "url": "https://example.com/promo" } }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

예시: 사용자 ID로 트랜잭션 푸시 보내기

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "ios":     { "title": "Your order", "body": "Order #42 has shipped." },
              "android": { "title": "Your order", "body": "Order #42 has shipped." }
            }
          }
        },
        "custom_data": { "order_id": "42" }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

페이로드 참조

페이로드

LocalizedContent

기기의 로캘 선택

공통 푸시 필드

iOS (ios)

Android (android, huawei_android)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

텔레그램 (telegram)

카카오 (kakao)

라인 (line)

바이버 (viber)

왓츠앱 (whatsapp)

SMS (sms)

MMS