알림

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

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

요청 구조

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

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

{
  "segment": { ... }       // OR
  "transactional": { ... }
}

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	다운스트림 분석으로 전달되는 자유 형식 메타데이터입니다.

예시: 세그먼트로 보내기

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`에 찾을 수 없는 식별자가 나열됩니다.
`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
    }
  }'

응답

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

마케팅 전송에 대한 사용자별 전송 빈도 제한입니다.

{ "days": 7, "count": 3, "exclude": false, "avoid": true }

days (정수, 1–30): 조회 기간.
count (정수): days 내에 허용되는 최대 메시지 수.
exclude (불리언): 이미 한도에 도달한 사용자를 완전히 제외합니다.
avoid (불리언): 이미 한도에 도달한 사용자를 부드럽게 회피합니다 (분석에는 계속 포함됨).

SendRate

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

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

Platform 열거형

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

MessageType 열거형

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

알림