알림

POST https://api.pushwoosh.com/messaging/v2/notify

단일 메시지를 생성하고 예약합니다.

요청 구조

요청 본문은 다음 두 종류 중 하나를 정확히 포함하는 NotifyRequest입니다:

segment: 세그먼트 코드, seglang 표현식 또는 구조화된 필터 표현식으로 오디언스 세그먼트를 타겟팅합니다.
transactional: hwid, 사용자 ID, 푸시 토큰 또는 테스트 기기의 명시적 목록으로 보냅니다.

{
  "segment": { ... },      // OR
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}

필드	유형	설명
`transaction_id`	string	선택 사항. 요청에 대한 멱등성 키로, `segment`와 `transactional` 모두에서 작동합니다. 5분 이내에 동일한 `transaction_id`로 반복 호출하면 중복 메시지를 보내는 대신 원래의 `message_code`를 반환합니다. UUID나 논리적 전송마다 고유한 다른 값을 사용하세요.

NotifySegment

오디언스 세그먼트 또는 필터 표현식과 일치하는 사용자를 타겟팅합니다.

필드	유형	설명
`schedule`	`Schedule`	언제 어떻게 보낼지 지정합니다. 필수 항목입니다.
`application`	string	애플리케이션 코드.
`platforms`	array of `Platform`	메시지가 타겟팅하는 플랫폼입니다.
`code`	string	세그먼트 코드. `expression` 및 `filter_expression`과 상호 배타적입니다.
`expression`	string	Seglang 표현식.
`filter_expression`	`FilterExpression`	구조화된 필터 표현식 (고급).
`payload`	`Payload`	푸시 / SMS / 텔레그램 / 카카오 / 라인 / 왓츠앱 / 바이버 페이로드. `email_payload`와 상호 배타적입니다.
`email_payload`	`EmailPayload`	이메일 페이로드.
`campaign`	string	이 메시지를 귀속시킬 캠페인 코드.
`frequency_capping`	`FrequencyCapping`	사용자별 빈도 제한.
`send_rate`	`SendRate`	전송에 대한 스로틀링.
`message_type`	`MessageType`	`MESSAGE_TYPE_MARKETING` (기본값) 또는 `MESSAGE_TYPE_TRANSACTIONAL`. 컨트롤 그룹 필터링을 제어합니다.
`dynamic_content_placeholders`	map<string, string>	콘텐츠의 플레이스홀더를 대체합니다.
`meta_data`	object	다운스트림 분석으로 전달되는 자유 형식 메타데이터.
`use_latest_user_device`	bool	`true`인 경우, 세그먼트와 일치하는 모든 기기 대신 각 사용자의 가장 최근에 활성화된 기기(가장 최근의 ‘애플리케이션 마지막 열람’ 기록이 있는 기기)로 메시지를 전달합니다. `platforms`로 범위가 지정됩니다: 해당 플랫폼의 기기만 고려되며, ‘애플리케이션 마지막 열람’ 데이터가 없는 경우 전송을 중단하는 대신 첫 번째로 일치하는 기기가 사용됩니다. 기본값은 `false`(모든 기기로 전송)입니다.

예시: 세그먼트로 보내기

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`	필수.
`application`	string	애플리케이션 코드.
`platforms`	array of `Platform`	메시지가 타겟팅하는 플랫폼입니다.
`test_devices`	bool	`true`인 경우, 앱의 테스트 기기로만 보냅니다.
`hwids`	`{ "list": [string, ...] }`	이 hwid로만 보냅니다.
`users`	`{ "list": [string, ...] }`	이 사용자 ID로만 보냅니다.
`push_tokens`	`{ "list": [string, ...] }`	이 푸시 토큰으로만 보냅니다.
`payload`	`Payload`	푸시 / SMS / 텔레그램 / 카카오 / 라인 / 왓츠앱 / 바이버 페이로드.
`email_payload`	`EmailPayload`	이메일 페이로드.
`return_unknown_identifiers`	bool	`true`인 경우, 응답의 `unknown_identifiers`에 찾을 수 없는 식별자가 나열됩니다.
`use_latest_user_device`	bool	사용자를 타겟팅할 때만 적용됩니다. 위의 `NotifySegment`와 동일한 동작 — 플랫폼 범위 내에서 기기당 하나가 아닌 사용자당 하나의 메시지를 전달합니다. 기본값은 `false`입니다.
`campaign`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data`		위의 `NotifySegment`를 참조하세요.

test_devices, hwids, users, push_tokens는 상호 배타적입니다. 정확히 하나만 설정해야 합니다.

예시: 사용자 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": ["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
    }
  }'

응답

{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}

필드	유형	설명
`message_code`	string	고유한 메시지 코드. `/getMessageDetails` 및 메시지 통계 엔드포인트와 함께 사용하세요.
`unknown_identifiers`	array of string	계정에서 찾을 수 없는 식별자입니다. `transactional` 종류에서 `return_unknown_identifiers: true`가 설정된 경우에만 채워집니다.

공유 유형

Schedule

{
  "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을 함께 보내세요.

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

{ "value": 500, "bucket": "1s", "avoid": false }

전송을 조절합니다. value는 bucket당 메시지 수이며, 일반적인 bucket은 "1s"입니다.

Platform 열거형

IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER.

MessageType 열거형

MESSAGE_TYPE_UNSPECIFIED: MESSAGE_TYPE_MARKETING과 동일합니다.
MESSAGE_TYPE_MARKETING: 컨트롤 그룹 필터링 및 빈도 제한의 대상이 됩니다.
MESSAGE_TYPE_TRANSACTIONAL: 컨트롤 그룹 필터링 및 빈도 제한을 건너뜁니다. 주문 확인, OTP 및 유사한 중요한 흐름에 사용하세요.