# Notify
`POST` `https://api.pushwoosh.com/messaging/v2/notify`
단일 메시지를 생성하고 예약합니다.
## 요청 구조
요청 본문은 다음 두 종류 중 하나를 정확히 포함하는 `NotifyRequest` 입니다:
- [`segment`](#notifysegment): 세그먼트 코드, [seglang](/ko/developer/api-reference/segmentation-filters-api/segmentation-language/) 표현식 또는 구조화된 필터 표현식으로 오디언스 세그먼트를 타겟팅합니다.
- [`transactional`](#notifytransactional): hwid, user ID, 푸시 토큰 또는 테스트 기기의 명시적 목록으로 보냅니다.
```json title="Shape"
{
"segment": { ... } // 또는
"transactional": { ... }
}
```
## NotifySegment
오디언스 세그먼트 또는 필터 표현식과 일치하는 사용자를 타겟팅합니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | 언제 어떻게 보낼지. 필수. |
| `application` | string | [애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array of [`Platform`](#platform-enum) | 메시지가 타겟팅하는 플랫폼. |
| `code` | string | [세그먼트 코드](/ko/developer/api-reference/api-identifiers/#segment--filter-code). `expression` 및 `filter_expression` 과 상호 배타적입니다. |
| `expression` | string | [Seglang](/ko/developer/api-reference/segmentation-filters-api/segmentation-language/) 표현식. |
| `filter_expression` | `FilterExpression` | 구조화된 필터 표현식 (고급). |
| `payload` | [`Payload`](/ko/developer/api-reference/messaging-api-v2/payload-reference/) | 푸시 / SMS / Telegram / Kakao / LINE / WhatsApp / Viber 페이로드. `email_payload` 와 상호 배타적입니다. |
| `email_payload` | [`EmailPayload`](/ko/developer/api-reference/messaging-api-v2/email-payload-reference/) | 이메일 페이로드. |
| `campaign` | string | 이 메시지를 귀속시킬 [캠페인 코드](/ko/developer/api-reference/api-identifiers/#campaign-code). |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | 사용자별 빈도 제한. |
| `send_rate` | [`SendRate`](#sendrate) | 전송에 대한 스로틀링. |
| `message_type` | [`MessageType`](#messagetype-enum) | `MESSAGE_TYPE_MARKETING` (기본값) 또는 `MESSAGE_TYPE_TRANSACTIONAL`. 컨트롤 그룹 필터링을 제어합니다. |
| `dynamic_content_placeholders` | map<string, string> | 콘텐츠의 플레이스홀더를 대체합니다. |
| `meta_data` | object | 다운스트림 분석으로 전달되는 자유 형식 메타데이터. |
### 예시: 세그먼트로 보내기
```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": { "body": "Hello!" },
"android": { "body": "Hello!" }
}
}
}
},
"schedule": { "at": "2026-05-01T12:00:00Z" },
"message_type": "MESSAGE_TYPE_MARKETING"
}
}'
```
## NotifyTransactional
명시적인 수신자 목록으로 보냅니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | 필수. |
| `application` | string | [애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array of [`Platform`](#platform-enum) | 메시지가 타겟팅하는 플랫폼. |
| `test_devices` | bool | `true` 인 경우, 앱의 테스트 기기로만 보냅니다. |
| `hwids` | `{ "list": [string, ...] }` | 이 [hwid](/ko/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) 로만 보냅니다. |
| `users` | `{ "list": [string, ...] }` | 이 [user ID](/ko/developer/pushwoosh-knowledge-hub/users-userids/) 로만 보냅니다. |
| `push_tokens` | `{ "list": [string, ...] }` | 이 [푸시 토큰](/ko/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token) 으로만 보냅니다. |
| `payload` | [`Payload`](/ko/developer/api-reference/messaging-api-v2/payload-reference/) | 푸시 / SMS / Telegram / Kakao / LINE / WhatsApp / Viber 페이로드. |
| `email_payload` | [`EmailPayload`](/ko/developer/api-reference/messaging-api-v2/email-payload-reference/) | 이메일 페이로드. |
| `return_unknown_identifiers` | bool | `true` 인 경우, 응답의 `unknown_identifiers` 에 찾을 수 없는 식별자가 나열됩니다. |
| `use_latest_user_device` | bool | `users` 를 타겟팅할 때만 적용됩니다. `true` 인 경우, 메시지는 해당 user ID 에 연결된 모든 기기 대신 각 사용자의 가장 최근에 활성화된 기기(가장 최근의 Last Application Open 이 있는 기기)로 전달됩니다. 기본값은 `false` (모든 기기로 보내기)입니다. |
| `campaign`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data` | | 위의 `NotifySegment` 를 참조하십시오. |
`test_devices`, `hwids`, `users`, `push_tokens` 는 상호 배타적입니다. 정확히 하나만 설정해야 합니다.
### 예시: user 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": ["user-123", "user-456"] },
"payload": {
"content": {
"localized_content": {
"en": { "ios": { "body": "Your order has shipped." } }
}
}
},
"schedule": { "at": "2026-05-01T12:00:00Z" },
"message_type": "MESSAGE_TYPE_TRANSACTIONAL",
"return_unknown_identifiers": true,
"use_latest_user_device": true
}
}'
```
## 응답
```json
{
"result": {
"message_code": "XXXXX-XXXXX-XXXXX",
"unknown_identifiers": []
}
}
```
| 필드 | 타입 | 설명 |
|---|---|---|
| `message_code` | string | 고유한 [메시지 코드](/ko/developer/api-reference/api-identifiers/#message-code). [`/getMessageDetails`](/ko/developer/api-reference/messages-api/#getmessagedetails) 및 메시지 통계 엔드포인트와 함께 사용하십시오. |
| `unknown_identifiers` | array of string | 계정에서 찾을 수 없는 식별자. `transactional` 종류에 `return_unknown_identifiers: true` 가 설정된 경우에만 채워집니다. |
## 공유 타입
### Schedule
```json
{
"at": "2026-05-01T12:00:00Z",
"follow_user_timezone": true,
"past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}
```
| 필드 | 타입 | 설명 |
|---|---|---|
| `at` | timestamp | 절대 전송 시간 (RFC 3339). 과거인 경우 메시지는 즉시 전송됩니다. 미래 최대 14일. |
| `after` | duration | `at` 의 대안. "지금"으로부터 이 오프셋 후에 보냅니다 (예: `"3600s"`). |
| `follow_user_timezone` | bool | `true` 인 경우, 각 기기는 현지 시간대의 `at` 에 메시지를 받습니다. |
| `past_timezones_behaviour` | enum | `PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY` (기본값), `PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND`, 또는 `PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY`. `follow_user_timezone` 이 `true` 일 때만 의미가 있습니다. |
### FrequencyCapping
마케팅 전송에 대한 사용자별 빈도 제한. 제한을 비활성화하려면 `frequency_capping` 을 완전히 생략하거나 `days: 0` 을 `count: 0` 과 함께 보내십시오.
```json
{ "days": 7, "count": 3, "exclude": false, "avoid": true }
```
- `days` (int, 1–30, 또는 `0` 으로 제한 비활성화): 조회 기간. `count` 와 함께 보내야 합니다 — 하나가 `0` 이면 다른 하나도 `0` 이어야 합니다; 하나를 `0` 으로 보내고 다른 하나가 0 이 아니면 `400` 을 반환합니다.
- `count` (int, 1 이상, 또는 `0` 으로 제한 비활성화): `days` 내에 허용되는 최대 메시지 수. 위의 `days` 와 동일한 페어링 규칙.
- `exclude` (bool): 이미 제한에 도달한 사용자를 하드 제외합니다.
- `avoid` (bool): 이미 제한에 도달한 사용자를 소프트 회피합니다 (여전히 분석에 포함됨).
### SendRate
```json
{ "value": 500, "bucket": "1s", "avoid": false }
```
전송을 스로틀합니다. `value` 는 `bucket` 당 메시지 수이며, 일반적인 `bucket` 은 `"1s"` 입니다.
### Platform enum
`IOS`, `ANDROID`, `OSX`, `WINDOWS`, `AMAZON`, `SAFARI`, `CHROME`, `FIREFOX`, `IE`, `EMAIL`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `SMS`, `WEB`, `KAKAO`, `TELEGRAM`, `LINE`, `WHATS_APP`, `VIBER`.
### MessageType enum
- `MESSAGE_TYPE_UNSPECIFIED`: `MESSAGE_TYPE_MARKETING` 과 동일합니다.
- `MESSAGE_TYPE_MARKETING`: 컨트롤 그룹 필터링 및 빈도 제한의 대상이 됩니다.
- `MESSAGE_TYPE_TRANSACTIONAL`: 컨트롤 그룹 필터링 및 빈도 제한을 건너뜁니다. 주문 확인, OTP 및 유사한 중요한 흐름에 사용하십시오.
## 관련 항목