페이로드 참조

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

페이로드

preset (문자열): 이 메시지에 적용할 푸시 프리셋 코드(형식 XXXXX-XXXXX)입니다.
sms_preset (문자열): 저장된 SMS 프리셋의 코드(형식 XXXXX-XXXXX)입니다. 로캘별 텍스트는 각 로캘의 sms.body로 확인됩니다. 특정 로캘에 대한 인라인 sms.body는 해당 로캘의 프리셋을 재정의합니다. 프리셋은 메시지와 동일한 애플리케이션에 속해야 합니다.
content (LocalizedContent): 메시지 콘텐츠입니다. silent와 상호 배타적입니다.
silent (bool): 자동 (데이터 전용) 푸시를 보냅니다. content와 상호 배타적입니다.
custom_data (객체): u 매개변수로 클라이언트 SDK에 전달되는 자유 형식 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 푸시
`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 메시지
`viber`	Viber 메시지
`whatsapp`	WhatsApp 메시지
`sms`	SMS 메시지

공통 푸시 필드

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

title (문자열): 알림 제목입니다.
body (문자열): 알림 본문입니다.
time_to_live (기간, 예: "3600s"): 오프라인 기기에 대해 푸시 서버가 알림을 보관해야 하는 기간입니다.
sound (문자열): 사운드 파일 이름입니다.
sound_enabled (bool): 사운드를 활성화하거나 억제합니다.
badges (문자열): 배지 수(iOS) 또는 유사 기능입니다.
root_params (객체): 원시 플랫폼별 페이로드 재정의입니다.
inbox (Inbox): Message Inbox 항목입니다.

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

iOS (`ios`)

subtitle (문자열): iOS 알림 부제목입니다.
is_critical (bool): 중요 알림(자격 필요)입니다.
attachment (문자열): 미디어 첨부 파일의 URL입니다.
thread_id (문자열): 그룹화된 알림의 스레드 식별자입니다.
trim_content (bool): 콘텐츠를 맞게 자릅니다.
category_id (문자열): 대화형 작업을 위한 UNNotificationCategory 식별자입니다.
interruption_level (문자열): passive, active, time-sensitive 또는 critical입니다.
collapse_id (문자열): 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`, `baidu_android`)

icon (문자열): 알림 작은 아이콘입니다.
banner (문자열): 큰 그림 URL입니다.
delivery_priority (NORMAL | HIGH): FCM 전송 우선순위입니다.
vibration (bool): 수신 시 진동입니다.
led_color (문자열, 16진수): 알림 LED 색상입니다.
icon_background_color (문자열, 16진수): 아이콘 배경색입니다.
show_on_lockscreen (bool): 잠금 화면에 표시합니다.
custom_icon (문자열): 사용자 지정 아이콘의 URL입니다.
priority (NotificationPriority): 트레이 내 우선순위입니다.
group_id (문자열): 알림 그룹 키입니다.
collapse_key (문자열): 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 (문자열): 사용자가 알림을 클릭할 때 열리는 URL입니다.
url_arguments (문자열 배열): 웹 푸시 URL 템플릿에 대체되는 Safari URL 인수입니다.

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

Chrome (`chrome`)

icon, image (문자열): 작은 아이콘 및 큰 이미지 URL입니다.
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 (`telegram`)

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

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

Kakao (`kakao`)

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

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

LINE (`line`)

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

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

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

Viber (`viber`)

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

body (문자열): 일반 텍스트 메시지입니다. template_id가 설정되지 않은 경우 필수입니다.
template_id (문자열): 사전 승인된 트랜잭션 템플릿의 ID입니다. 설정되면 body보다 우선합니다.
template_lang (문자열): 템플릿 로캘입니다. 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`)

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

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

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" } }
  }
}

RichMedia

{ "code": "XXXXX-XXXXX" }        // 리치 미디어 코드로
{ "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 (문자열): 인박스 항목에 표시되는 이미지입니다.
expiration_date (타임스탬프): 항목이 인박스에서 제거되는 시간입니다.

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)

Viber (viber)

WhatsApp (whatsapp)

SMS (sms)