Notify

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

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

요청 구조

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

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

Shape

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

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

팁

생성된 메시지를 요청과 상호 연관시켜 엔드투엔드 추적을 하려면 X-Request-ID 헤더를 전달하세요 — 요청 ID를 참조하세요.

페이로드가 아닌 키만 확인됩니다

중복 제거는 transaction_id 만을 기준으로 일치 여부를 확인합니다. 재시도 시 동일한 transaction_id 를 재사용하지만 다른 segment / transactional 본문을 보내는 경우, 원래의 message_code 가 반환되고 새 본문은 조용히 폐기됩니다 — 첫 번째 요청과 비교되지 않습니다. 논리적으로 다른 메시지 간에 transaction_id 를 재사용하지 마세요.

팁

이것은 레거시 Messages API의 transactionId 와 동일한 중복 제거 메커니즘으로, 동일한 5분 저장 기간을 공유하므로 재시도된 요청은 /createMessage 와 Notify 모두에서 중복 제거됩니다. 이는 Pushwoosh가 그대로 저장하고 중복 제거에 사용하지 않는 PW_Conversion 수익 이벤트의 transaction_id 속성과는 관련이 없습니다.

NotifySegment

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

필드	유형	설명
schedule	Schedule	전송 시기 및 방법. 필수.
application	string	애플리케이션 코드.
platforms	array of Platform	메시지가 타겟팅하는 플랫폼.
code	string	세그먼트 코드. expression 및 filter_expression 과 상호 배타적입니다.
expression	string	Seglang 표현식.
filter_expression	FilterExpression	구조화된 필터 표현식 (고급).
payload	Payload	푸시 / SMS / Telegram / Kakao / LINE / WhatsApp / Viber 페이로드. 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 / Telegram / Kakao / LINE / WhatsApp / Viber 페이로드.
email_payload	EmailPayload	이메일 페이로드.
return_unknown_identifiers	bool	true 인 경우, 응답의 unknown_identifiers 에 찾을 수 없는 식별자가 나열됩니다.
use_latest_user_device	bool	users 를 타겟팅할 때만 적용됩니다. true 인 경우, 해당 사용자 ID에 연결된 모든 기기 대신 각 사용자의 가장 최근에 활성화된 기기(가장 최근의 Last Application Open을 가진 기기)로 메시지가 전달됩니다. 기본값은 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): 이미 상한에 도달한 사용자를 부드럽게 회피합니다 (분석에는 계속 포함됨).

Important

days 와 count 를 0 값 불일치 상태로 보내면 (예: {"days": 0, "count": 5}) 400 이 반환됩니다. 이 유효성 검사는 Notify 에 대한 브레이킹 체인지입니다 — 이전에 단독 0 이 조용히 무시되던 것에 의존했던 클라이언트는 이제 대신 오류를 받게 됩니다.

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, VIBER.

MessageType 열거형

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

관련 항목

취소

페이로드 참조

이메일 페이로드 참조

v1에서 마이그레이션