페이로드 참조

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

페이로드(Payload)

preset (string): 이 메시지에 적용할 푸시 프리셋 코드(XXXXX-XXXXX 형식)입니다.
sms_preset (string): 저장된 SMS 프리셋의 코드(XXXXX-XXXXX 형식)입니다. 로캘별 텍스트는 각 로캘의 sms.body로 확인됩니다. 특정 로캘에 대한 인라인 sms.body는 해당 로캘의 프리셋을 재정의합니다. 프리셋은 메시지와 동일한 애플리케이션에 속해야 합니다.
content (LocalizedContent): 메시지 콘텐츠입니다. silent와 상호 배타적입니다.
silent (bool): 모든 플랫폼에 무음(데이터 전용) 푸시를 보냅니다. content와 상호 배타적입니다. 일부 플랫폼만 무음으로 만들려면 대신 iOS 또는 Android용 content 안에 silent를 설정하세요.
custom_data (object): 클라이언트 SDK에 u 매개변수로 전달되는 자유 형식 JSON입니다. 매우 큰 정수는 정밀도를 잃을 수 있습니다. 사용자 지정 데이터의 큰 정수를 참조하세요.
custom_data_raw (string): JSON 객체를 담은 문자열로, 클라이언트 SDK에 u 매개변수로 전달됩니다. 이 문자열의 숫자는 정확한 값을 유지합니다. 비어 있지 않은 custom_data와 상호 배타적입니다. 유효하지 않은 값은 400을 반환합니다.
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" } }
  }
}

사용자 지정 데이터의 큰 정수

9007199254740992보다 큰 정수는 custom_data에서 정밀도를 잃습니다. 정확한 값을 유지하려면 custom_data_raw를 사용하세요.

custom_data는 google.protobuf.Struct(범용 JSON 형태의 객체)입니다. 모든 숫자를 double로 저장하는데, double은 9007199254740992까지의 정수만 정확하게 표현하는 64비트 부동 소수점 숫자입니다. 그보다 큰 정수는 반올림됩니다. 5190090000030465245는 디바이스에 5190090000030465000으로 도달합니다. 문자열은 영향을 받지 않습니다.

이러한 정수를 정확하게 유지하려면 JSON 객체를 담은 문자열을 custom_data_raw로 보내세요.

{ "payload": { "silent": true, "custom_data_raw": "{\"pushUID\": 5190090000030465245}" } }

custom_data_raw 규칙:

문자열에는 JSON 객체가 있어야 합니다. 배열, 문자열, null 또는 유효하지 않은 JSON은 payload.custom_data_raw에 대한 필드 위반과 함께 400(INVALID_ARGUMENT)을 반환합니다.
custom_data에 키가 하나라도 있고 custom_data_raw가 설정되어 있으면 요청은 400을 반환합니다. 빈 custom_data 객체는 무시됩니다.
custom_data와 마찬가지로 푸시 preset에 저장된 사용자 지정 데이터를 대체합니다.
객체는 전달 전에 다시 JSON 텍스트로 변환됩니다. 키 순서는 유지되지 않고 공백은 제거됩니다. 숫자는 정확한 값을 유지하지만 원본 텍스트가 바이트 단위로 그대로 유지되지는 않습니다.
/messaging/v2/notify/batch에서 유효하지 않은 custom_data_raw는 해당 항목만 실패시킵니다. 다른 항목은 전송됩니다.

요청을 보내는 방식:

REST: /messaging/v2/notify 및 /messaging/v2/notify/batch에는 변경이 필요 없습니다. custom_data에 double로 정확히 표현할 수 없는 정수가 있으면 API가 자동으로 손실 없이 유지합니다. 여전히 custom_data_raw를 명시적으로 설정할 수도 있습니다.
gRPC: 클라이언트가 Struct를 직접 구성하므로 요청을 보내기 전에 정밀도가 손실됩니다. custom_data 대신 custom_data_raw를 채우세요.

알림이 전달되는 위치:

Android: SDK가 PushMessage.getCustomData()를 통해 u를 문자열로 앱에 전달하므로 모든 자릿수가 유지됩니다.
Web push: Web SDK는 JSON.parse로 u를 파싱하며, JavaScript의 모든 숫자는 double입니다. 큰 정수는 API와 관계없이 브라우저에서 반올림되므로 문자열로 전달하세요.
Windows: 토스트는 다른 플랫폼과 동일한 u 데이터를 받으며, custom_data_raw로 보낸 정수는 정확하게 도착합니다.

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 푸시
`mac_os`	macOS 푸시
`amazon`	Amazon (ADM) 푸시
`safari`	Safari 웹 푸시
`chrome`	Chrome 웹 푸시
`firefox`	Firefox 웹 푸시
`ie`	Internet Explorer 웹 푸시
`windows`	Windows 푸시 (타일 / 토스트 / 배지)
`telegram`	텔레그램 메시지
`kakao`	카카오 메시지
`line`	라인 메시지
`viber`	바이버 메시지
`whatsapp`	왓츠앱 메시지
`fb_messenger`	페이스북 메신저 메시지
`sms`	SMS 메시지

버튼

각 로케일 항목에는 buttons도 포함할 수 있습니다. 이는 iOS, Android, Huawei에서 푸시 아래에 표시되는 최대 3개의 액션 버튼입니다. 다른 플랫폼은 이를 무시합니다. 버튼을 사용하려면 Notification Service Extension이 포함된 iOS SDK 7.2.10 이상과 Android SDK 6.17.0 이상이 필요합니다.

각 PushButton에는 다음 필드가 있습니다:

id (string): 탭 시 앱이 받는 버튼 ID입니다. 최대 64자, 공백 없음, 푸시 내에서 고유해야 합니다. ACTION_OPEN 및 ACTION_CUSTOM에는 필수입니다. 다른 액션에서 생략하면 Pushwoosh가 btn_1, btn_2 등으로 설정합니다.
label (string): 버튼 텍스트로, 1~64자입니다.
action (enum): ACTION_OPEN은 앱을 열고, ACTION_URL은 url을 열고, ACTION_DEEPLINK는 딥 링크를 열고, ACTION_CUSTOM은 id를 앱에 전달하여 앱이 처리합니다.
url (string): ACTION_URL용 절대 http 또는 https 주소, 또는 ACTION_DEEPLINK용 스킴이 포함된 딥 링크입니다.
platform_urls (map): ACTION_DEEPLINK용 플랫폼별 딥 링크로, 플랫폼 코드를 키로 사용합니다: 1 iOS, 3 Android, 17 Huawei.
style (enum): STYLE_DEFAULT 또는 STYLE_DESTRUCTIVE. 파괴적 스타일은 iOS에서 버튼을 빨간색으로 표시합니다.

{
  "localized_content": {
    "default": {
      "ios": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "android": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "buttons": [
        { "id": "track", "label": "Track order", "action": "ACTION_DEEPLINK", "url": "myapp://orders/42" },
        { "id": "cancel", "label": "Cancel order", "action": "ACTION_CUSTOM", "style": "STYLE_DESTRUCTIVE" }
      ]
    }
  }
}

공통 푸시 필드

이 필드들은 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를 가진 알림은 디바이스에서 서로를 대체합니다.
silent (bool): iOS 푸시를 무음(데이터 전용)으로 보내고, 같은 메시지의 다른 플랫폼은 일반 알림을 받습니다. content 안에 설정하므로 content와 함께 동작합니다. 모든 플랫폼을 무음으로 만들려면 대신 content를 대체하는 최상위 silent를 사용하세요. 아무 로캘에나 설정하면 모든 로캘에 적용됩니다.

{
  "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를 가진 알림은 디바이스가 오프라인일 때 서로를 대체합니다.
silent (bool): 이 플랫폼으로 가는 푸시를 무음(데이터 전용)으로 보내고, 같은 메시지의 다른 플랫폼은 일반 알림을 받습니다. content 안에 설정하므로 content와 함께 동작합니다. 모든 플랫폼을 무음으로 만들려면 대신 content를 대체하는 최상위 silent를 사용하세요. 아무 로캘에나 설정하면 모든 로캘에 적용됩니다. baidu_android 블록도 동일한 동작으로 silent를 허용합니다.

{
  "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 제어판에서 구성된 LINE 템플릿의 코드(이미지, 캐러셀 또는 플렉스 메시지를 보내는 데 사용됨)입니다. 리치 콘텐츠의 경우 제어판에서 템플릿을 미리 구성하고 여기에서 참조하세요.

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

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

바이버 (`viber`)

Viber 메시지는 자유 텍스트 본문(선택적으로 이미지와 버튼 또는 캐러셀 포함)이거나 ID와 언어로 참조되는 사전 승인된 트랜잭션 템플릿(Omni Messaging / MStat)입니다.

body (string): 일반 텍스트 메시지입니다. template_id가 설정되지 않은 경우 필수이지만, image가 설정된 경우는 예외입니다. 버튼이나 캐러셀을 사용할 때는 필수입니다.
image (string): 공개 이미지 URL입니다. template_id가 설정된 경우 무시됩니다.
button_caption (string): 버튼 텍스트로, 최대 30자입니다. button_action과 함께 설정합니다. body가 필요합니다. template_id가 설정된 경우 무시됩니다.
button_action (string): 버튼 링크로, http:// 또는 https:// URL, viber:// 딥 링크, 또는 {lp-100}과 같은 Omni 토큰(Omni Messaging이 발송 시점에 확인하는 추적 링크 플레이스홀더)입니다. button_caption과 함께 설정합니다.
carousel (object): body 아래에 표시되는 2–5개의 스와이프 가능한 카드입니다. image, button_caption, button_action, 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, image, 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
  }
}

캐러셀

carousel.items에는 2~5개의 카드가 들어갑니다. 대신 journey에서 캐러셀을 설정하려면 캐러셀 보내기를 참조하세요. 각 카드에는 다음 필드가 있습니다.

title (string): 카드 제목으로, 2–38자입니다. 필수입니다.
image (string): 공개 http:// 또는 https:// 이미지 URL입니다. 필수입니다.
primary_button (object): 기본 버튼입니다. 필수입니다.
secondary_button (object): 두 번째 버튼입니다. 선택 사항입니다.

각 버튼에는 두 개의 필드가 있으며, 버튼이 있는 경우 두 필드 모두 필수입니다.

caption (string): 버튼 텍스트로, primary_button은 최대 10자, secondary_button은 최대 12자입니다.
action (string): 버튼 링크로, 스킴이 있는 URL(http://, https://, viber://) 또는 {lp-100}과 같은 Omni 토큰이며, button_action과 같은 값을 사용합니다.

이 규칙 중 하나라도 위반하는 요청은 INVALID_ARGUMENT로 거부됩니다. google.rpc.BadRequest 세부 정보에 필드 이름이 표시됩니다(예: viber.carousel.items[0].title).

예시:

{
  "viber": {
    "body": "New arrivals are in. Swipe to see them.",
    "carousel": {
      "items": [
        {
          "title": "Running shoes",
          "image": "https://example.com/img/shoes.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/shoes" },
          "secondary_button": { "caption": "Details", "action": "{lp-100}" }
        },
        {
          "title": "Sports backpack",
          "image": "https://example.com/img/backpack.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/backpack" }
        }
      ]
    }
  }
}

왓츠앱 (`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\"}"
  }
}

페이스북 메신저 (`fb_messenger`)

Facebook Messenger 메시지는 Meta를 통해 전달되며 Meta의 메시징 규칙을 따릅니다. 자유 형식 콘텐츠는 사용자로부터의 인바운드 메시지로 열리는 24시간 고객 서비스 창 내에서만 전달됩니다. 이 창 밖에서는 message_tag를 Meta의 승인된 사용 사례 중 하나로 설정해야 하며, 그렇지 않으면 Meta가 전송을 거부합니다.

body (string): 일반 텍스트 메시지입니다. message를 설정하지 않은 경우 필수입니다.
message (string): 텍스트, 첨부 파일, 템플릿 또는 빠른 답장을 포함하는 완전한 Meta Send API message 객체를 JSON 문자열로 지정합니다. 설정하면 Pushwoosh는 body 대신 이 객체를 전송합니다.
message_tag (string): 24시간 창 밖에서 필요합니다. CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE, HUMAN_AGENT 중 하나입니다.

{
  "fb_messenger": {
    "body": "Hello from Pushwoosh",
    "message_tag": "ACCOUNT_UPDATE"
  }
}

이 채널에는 별도의 디바이스 식별자가 없습니다. hwid, push_token, user_id는 모두 수신자의 Meta 페이지 범위 ID(PSID)인 동일한 값으로 확인됩니다. NotifyTransactional에서 이들 중 하나로 특정 대화를 타겟팅하세요.

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": ["FB_MESSENGER"],
      "hwids": { "list": ["<recipient-psid>"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "fb_messenger": { "body": "Hello from Pushwoosh" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" }
    }
  }'

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입니다. 각 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
  }
}

RCS

sms 블록에 rcs를 추가하면 body 대신 Twilio 콘텐츠 템플릿을 RCS(Rich Communication Services)로 보냅니다. Twilio는 템플릿을 RCS 메시지로 전달하고, 대체 수단으로 body가 아닌 템플릿의 twilio/text 유형으로 만든 SMS를 보냅니다. twilio/text 유형이 없는 템플릿은 RCS를 지원하는 휴대폰에만 도달합니다.

rcs.content_sid (string): Twilio 콘텐츠 템플릿의 SID로, HX 뒤에 16진수 문자 32개가 붙습니다. ListRcsTemplates 또는 Twilio Console에서 확인하세요.
rcs.content_variables (string): 템플릿 변수의 JSON 객체를 문자열로 직렬화한 값입니다. 예: "{\"1\": \"{FirstName|CapitalizeFirst|there}\"}". 값은 태그와 Liquid 개인화를 지원합니다. 생략한 변수는 템플릿의 기본값을 사용합니다.

rcs가 있는 sms 블록에서도 body는 여전히 필수입니다.

애플리케이션이 SMS 플랫폼 구성에 설정된 자체 Account SID, Auth token, Messaging Service SID로 Twilio를 통해 SMS를 보내지 않으면 요청이 거부됩니다. Pushwoosh가 제공하는 Twilio 자격 증명을 사용하는 애플리케이션은 RCS를 보낼 수 없습니다.

SMS 프리셋은 로캘별로 템플릿을 가질 수 있습니다. 페이로드에 sms_preset이 있으면, 요청이 자체 rcs.content_sid를 제공하지 않는 모든 로캘에 프리셋의 템플릿이 사용됩니다.

{
  "sms": {
    "body": "Your order has shipped.",
    "rcs": {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "content_variables": "{\"1\": \"{FirstName|CapitalizeFirst|there}\", \"2\": \"A-1042\"}"
    }
  }
}

RCS 템플릿 목록 조회

ListRcsTemplates는 RCS로 보낼 수 있는 애플리케이션의 Twilio 콘텐츠 템플릿을 애플리케이션 자체의 Twilio 자격 증명으로 읽어 반환합니다.

GET https://rpc-api.svc-nue.pushwoosh.com/api/sms_presets:rcs_templates?application=XXXXX-XXXXX
Authorization: Api YOUR_API_TOKEN

application (string, query): 애플리케이션 코드, XXXXX-XXXXX 형식입니다.

응답에는 templates 배열이 포함됩니다. RCS 콘텐츠 유형(twilio/card, twilio/carousel, twilio/quick-reply, twilio/call-to-action, twilio/media)이 하나 이상 있는 템플릿만 표시됩니다.

필드	유형	설명
`content_sid`	string	템플릿 SID로, `rcs.content_sid`에 넣는 값입니다.
`friendly_name`	string	Twilio의 템플릿 이름입니다.
`language`	string	템플릿 언어 코드입니다.
`types`	array of string	템플릿이 정의하는 Twilio 콘텐츠 유형입니다. 예: `twilio/card`, `twilio/text`.
`variables`	object	기본값이 포함된 템플릿 변수입니다.
`has_sms_fallback`	boolean	템플릿에 `twilio/text` 유형, 즉 RCS를 지원하지 않는 휴대폰이 받는 SMS가 있으면 `true`입니다.

{
  "templates": [
    {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "friendly_name": "order_shipped_card",
      "language": "en",
      "types": ["twilio/card", "twilio/text"],
      "variables": { "1": "there", "2": "your order" },
      "has_sms_fallback": true
    }
  ]
}

ListRcsTemplates는 다음 오류를 반환합니다.

HTTP 상태	원인
`400 Bad Request`	애플리케이션에 자체 Twilio Account SID 및 Auth token이 없습니다(`FailedPrecondition`).
`401 Unauthorized`	Twilio가 애플리케이션의 자격 증명을 거부했습니다(`Unauthenticated`).
`503 Service Unavailable`	Twilio Content API가 다른 오류를 반환했습니다(`Unavailable`).

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): 항목이 인박스에서 제거되는 시점입니다.
expires_in (duration, 예: "604800s"): 항목이 인박스에 유지되는 기간으로, 발송일(예약된 send_date 또는 즉시 발송의 경우 요청 시점)부터 계산됩니다. 양수여야 합니다. expiration_date가 설정되어 있으면 무시됩니다.

고정 날짜 대신 상대적인 유지 기간을 설정하려면 expires_in만 전송하세요:

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expires_in": "604800s"
}

계정에 최대 인박스 유지 기간이 설정되어 있으면 이를 초과하는 expiration_date 또는 expires_in은 거부됩니다.

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

페이로드 참조

페이로드(Payload)

사용자 지정 데이터의 큰 정수

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)

페이스북 메신저 (fb_messenger)

SMS (sms)

MMS

RCS