# 페이로드 참조

이메일이 아닌 채널(푸시, SMS, Telegram, Kakao, LINE, Viber, WhatsApp)을 통해 전송할 때 [`Notify`](/ko/developer/api-reference/messaging-api-v2/notify/)에서 사용하는 `Payload` 메시지에 대한 참조입니다.

<Aside type="note">
이메일의 경우, [이메일 페이로드 참조](/ko/developer/api-reference/messaging-api-v2/email-payload-reference/)를 참조하세요.
</Aside>

## 페이로드

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

```json
{
  "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](https://www.loc.gov/standards/iso639-2/php/code_list.php) 두 글자 코드(예: `"en"`, `"es"`)와 모든 경우에 대한 번역을 위한 특수 키 `"default"`입니다. ISO 639-1의 예외는 번체 및 간체 중국어에 대한 `"zh-Hant"`와 `"zh-Hans"`입니다.

```json
{
  "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" }
    }
  }
}
```

### 기기의 로케일 선택

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

1. 기기 언어와 정확히 일치하는 경우.
2. 키 `"default"`.
3. 키 `"en"`.
4. 맵에 있는 다른 모든 로케일.

모든 기기가 결정적인 대체(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`](#inbox)): [메시지 인박스](/ko/developer/guides/message-inbox/mobile-message-inbox/) 항목입니다.

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

```json
{
  "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`](#notificationpriority-enum)): 트레이 내 우선순위입니다.
- `group_id` (문자열): 알림 그룹 키입니다.
- `collapse_key` (문자열): FCM 축소 키입니다. 기기가 오프라인인 동안 동일한 `collapse_key`를 가진 알림은 서로를 대체합니다.

```json
{
  "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)을 사용합니다.

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

## Amazon (`amazon`)

공통 푸시 필드와 `custom_icon` 및 `priority` ([`NotificationPriority`](#notificationpriority-enum))를 사용합니다.

```json
{
  "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 인수입니다.

```json
{
  "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`: 최대 두 개의 액션 버튼입니다.

```json
{
  "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`만 사용합니다.

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

## Windows (`windows`)

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

```json
{
  "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 문자열화된 변수입니다.

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

## Kakao (`kakao`)

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

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

## LINE (`line`)

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

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

```json
{
  "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&lt;string, string&gt;): 템플릿에 대체되는 키/값 바인딩입니다. 예: `{ "name": "John", "code": "123456" }`.
- `all_devices` (bool): `false`(기본값)는 사용자의 주 기기에만 전달하고, `true`는 사용자의 모든 기기에 전달합니다.

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

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

일반 텍스트:

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

트랜잭션 템플릿:

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

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

## SMS (`sms`)

SMS는 각 로케일의 [`Content`](#localizedcontent) 내에 `ios`, `android` 및 기타 메시징 채널과 함께 자체 플랫폼 블록을 가집니다.

- `body` (문자열): 해당 로케일의 SMS 텍스트입니다. `sms` 블록이 있을 때 필수입니다.

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

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

```json
{
  "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`](#richmedia)): [리치 미디어](/ko/product/content/in-apps/) 페이지를 엽니다.
- `deep_link`: 딥 링크를 엽니다: `{ "code": "flow-code", "params": { "key": "value" } }`.
- `link` ([`Link`](#link)): URL을 엽니다.

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

딥링크 URL과 `params` 값은 [Liquid 개인화](/ko/developer/guides/personalization/liquid-templates/) 구문을 지원합니다 — 표현식은 딥 링크가 열리기 전에 해석됩니다.

### RichMedia


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

### Link


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

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

## 인박스

메시지 인박스에 메시지가 어떻게 표시될지 구성합니다.

```json
{
  "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`

<Aside type="caution">
항상 `priority`를 위의 문자열 값 중 하나로 보내세요. API는 열거형의 숫자 등가물(위 순서와 일치하는 1-5)도 허용하지만, 그 매핑은 내부 protobuf 세부 사항이며 지원되는 계약이 아니므로 의존하지 마세요.

인식할 수 없는 `priority` 값(오타가 있는 문자열 또는 범위를 벗어난 숫자)은 거부되지 않습니다. API는 조용히 이를 무시하고, 오류를 반환하는 대신 `priority` 필드 없이 알림을 보냅니다.
</Aside>

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

```bash
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로 트랜잭션 푸시 보내기

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