페이로드 참조

Notify가 이메일이 아닌 채널(푸시, SMS, Telegram, Kakao, LINE, WhatsApp)을 통해 전송할 때 사용하는 Payload 메시지에 대한 참조입니다.

페이로드

preset (string): 이 메시지에 적용할 프리셋 코드입니다.
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 알림입니다.

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".
맵에 있는 다른 모든 로케일.

모든 기기가 결정적인 폴백을 가질 수 있도록 "default" 또는 "en" 중 하나 이상을 제공하세요. 로케일별 변형을 예상하지 않는 경우 "default"만 보내세요.

각 로케일 항목은 선택적 플랫폼별 블록이 있는 Content 객체입니다. 타겟팅하는 플랫폼만 채우세요.

플랫폼 블록	채널
`ios`	iOS 푸시
`android`	Android (FCM) 푸시
`huawei_android`	Huawei Android 푸시
`baidu_android`	Baidu Android 푸시
`mac_os`	macOS 푸시
`amazon`	Amazon (ADM) 푸시
`safari`	Safari 웹 푸시
`chrome`	Chrome 웹 푸시
`firefox`	Firefox 웹 푸시
`ie`	Internet Explorer 웹 푸시
`windows`	Windows 푸시 (타일 / 토스트 / 배지)
`telegram`	Telegram 메시지
`kakao`	Kakao 메시지
`line`	LINE 메시지
`whatsapp`	WhatsApp 메시지

공통 푸시 필드

이 필드들은 ios, android, huawei_android, baidu_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): Message Inbox 항목입니다.

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를 가진 알림은 기기에서 서로를 대체합니다.

Android (`android`, `huawei_android`, `baidu_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를 가진 알림은 서로를 대체합니다.

macOS (`mac_os`)

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

Amazon (`amazon`)

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

Safari (`safari`)

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

Chrome (`chrome`)

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

Firefox (`firefox`)

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

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 (`telegram`)

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

Kakao (`kakao`)

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

LINE (`line`)

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

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

WhatsApp (`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 중 하나 이상을 설정해야 합니다.

SMS

SMS는 일반 메시지 흐름을 사용합니다. sms 플랫폼 블록은 예약되어 있습니다. 채워진 플랫폼 블록의 공통 body 필드를 통해 텍스트를 제공하세요. 발신자 ID 및 기타 제공업체 옵션은 앱의 SMS 구성에서 가져옵니다. SMS 구성을 참조하세요.

OpenAction

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

다음 중 정확히 하나:

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

RichMedia

{ "code": "XXXXX-XXXXX" }        // Rich Media 코드로
{ "url":  "https://..." }        // 원격 URL로

Link

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

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

Inbox

Message 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, baidu_android)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

Telegram (telegram)

Kakao (kakao)

LINE (line)

WhatsApp (whatsapp)

SMS