Notify

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

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

요청 구조

요청 본문은 NotifyRequest이며, 다음 두 종류 중 하나만 포함합니다:

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

Shape

{
  "segment": { ... },      // 또는
  "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

오디언스 세그먼트 또는 필터 표현식과 일치하는 사용자를 대상으로 합니다. code, expression, filter_expression 중 하나만 정확히 설정해야 합니다. expression과 filter_expression의 경우, 사전에 세그먼트를 생성할 필요 없이 이 전송에 대해서만 표현식이 인라인으로 평가됩니다.

코드와 인라인 표현식 중 선택하기

code로 참조되는 저장된 세그먼트만 고속 전송 사전 컴파일을 사용할 수 있습니다. expression과 filter_expression은 전송 시에 평가되며 사전 컴파일되지 않습니다.

필드	유형	설명
schedule	Schedule	전송 시점과 방법. 필수입니다.
application	string	애플리케이션 코드.
platforms	Platform 배열	메시지가 타겟팅하는 플랫폼.
code	string	사전에 저장된 세그먼트의 세그먼트 코드. expression 및 filter_expression과 상호 배타적입니다.
expression	string	Seglang 표현식. 이 전송에 대해서만 평가되며 저장된 세그먼트가 필요하지 않습니다. code 및 filter_expression과 상호 배타적입니다.
filter_expression	FilterExpression	expression과 동일한 로직이지만, seglang 문자열 대신 구조화된 객체 형태입니다. code 및 expression과 상호 배타적입니다. FilterExpression 스키마는 공개적으로 문서화되어 있지 않습니다. 구조화된 형식이 필요한 경우 Pushwoosh 지원팀에 요청하세요.
payload	Payload	푸시 / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger 페이로드. email_payload와 상호 배타적입니다.
email_payload	EmailPayload	이메일 페이로드.
campaign	string	이 메시지를 귀속시킬 캠페인 코드.
campaign_name	string	이 메시지의 내부 이름으로, Message History의 행 제목과 내보내기에 표시됩니다. 위의 campaign과는 관련이 없습니다. 메시지를 그룹화하거나 전송에 영향을 주지 않습니다. 최대 255자이며 잘립니다. 필드를 생략하거나 비워두면 행 제목이 페이로드 자체의 콘텐츠에서 채워집니다.
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	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 / Facebook Messenger 페이로드.
email_payload	EmailPayload	이메일 페이로드.
return_unknown_identifiers	bool	true인 경우, 응답의 unknown_identifiers에 찾을 수 없는 식별자가 나열됩니다.
use_latest_user_device	bool	users를 타겟팅할 때만 적용됩니다. 위의 NotifySegment와 동일한 동작으로, 기기당 하나가 아닌 사용자당 하나의 메시지를 platforms에 한정하여 전달합니다. 기본값은 false입니다.
campaign, campaign_name, 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	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): 이미 한도에 도달한 사용자를 부드럽게 회피합니다(분석에는 계속 포함됨).

중요

days와 count를 0이 아닌 값과 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, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER, FB_MESSENGER.

MessageType 열거형

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

관련 항목

Notify 일괄 처리

취소

페이로드 참조

이메일 페이로드 참조

v1에서 마이그레이션