v1에서 마이그레이션

이 가이드는 모든 레거시 /create*Message 필드를 Messaging API v2의 해당 필드에 매핑합니다. 기존 통합을 포팅할 때 참조로 사용하세요.

주요 차이점

측면	v1	v2
채널별 엔드포인트	채널별 별도 메서드 (`/createMessage`, `/createEmailMessage`, `/createSMSMessage`, `/createKakaoMessage` 등)	단일 엔드포인트 — `POST /messaging/v2/notify`
인증	요청 본문의 `auth` 필드	`Authorization: Token <API_TOKEN>` 헤더
타겟팅	혼합: 동일한 요청에 `filter` + `conditions` + `devices` + `users`	명시적 분리: `NotifySegment` vs `NotifyTransactional`
콘텐츠	플랫 `content` + 형제 플랫폼 블록	중첩된 `payload.content.localized_content.{locale}.{platform}`
응답	`MessageCode[]`	`message_code` + 선택적 `unknown_identifiers`

/createMessage에서 마이그레이션

v1 notifications[*] 항목은 개별 Notify 요청이 됩니다(각각 메시지 하나). v1 호출에 여러 항목이 있는 경우 항목당 하나의 Notify를 실행하세요.

타겟팅 결정. v1 항목이 devices 또는 users(명시적 목록)를 사용하는 경우 transactional에 매핑합니다. 그렇지 않으면 segment에 매핑합니다.

요청 수준 필드

application → segment.application 또는 transactional.application (동일한 앱 코드 형식).
applications_group: v2에서 지원되지 않습니다. 앱별로 여러 요청을 사용하세요.
auth: Authorization 헤더로 이동했으며, 더 이상 본문에 포함되지 않습니다.
transactionId → transaction_id, segment / transactional과 함께 요청 수준 필드입니다. v1과 동일한 중복 제거 동작: 5분 이내에 동일한 값으로 반복 호출하면 페이로드가 아닌 키만 일치시켜 재전송하는 대신 원래 message_code를 반환합니다. transaction_id를 참조하세요.

스케줄링

send_date ("YYYY-MM-DD HH:mm" 또는 "now") → schedule.at (RFC 3339 UTC 타임스탬프). v1의 "now"를 재현하려면 schedule.at을 현재 시간으로 설정하세요. 과거의 모든 타임스탬프는 즉시 전송됩니다.
ignore_user_timezone → schedule.follow_user_timezone. 반대: ignore_user_timezone: true는 follow_user_timezone: false가 됩니다.
timezone: 지원되지 않습니다. v2는 항상 at에 UTC를 사용합니다. 클라이언트 측에서 변환하세요.

타겟팅

filter (세그먼트 이름) → segment.code.
conditions ([[tag, op, value], ...]) → segment.expression. seglang 표현식으로 다시 작성하세요. seglang에서 *는 논리적 AND이며 앱별 태그는 Tag("<application-code>", "<tag>", <op>, <value>)로 참조됩니다. 예: conditions_operator: AND가 있는 [["Country","EQ","BR"],["Language","EQ","pt"]] → Tag("XXXXX-XXXXX", "Country", EQ, "br") * Tag("XXXXX-XXXXX", "Language", EQ, "pt").
conditions_operator (AND / OR): segment.expression에 포함됩니다.
devices (hwid 또는 푸시 토큰) → transactional.hwids.list 또는 transactional.push_tokens.list. v2는 이 둘을 분리합니다: hwid는 hwids로, 원시 푸시 토큰은 push_tokens로 들어갑니다.
users → transactional.users.list.
platforms (숫자 코드 [1, 3, …]) → segment.platforms 또는 transactional.platforms (문자열 열거형 ["IOS", "ANDROID", …]). 플랫폼 열거형을 참조하세요.

콘텐츠

content (문자열) → payload.content.localized_content.default.{platform}.body. v2에서는 콘텐츠가 항상 로케일 및 플랫폼별로 지정됩니다. 일반 v1 문자열을 특수 "default" 키 아래에 넣으세요(모든 번역을 포괄, 디바이스에 대한 로케일 선택 참조).
content ({locale: text}) → payload.content.localized_content.{locale}.{platform}.body. 본문을 각 대상 플랫폼 블록에 복제하세요.
preset → payload.preset.
data → payload.custom_data.
rich_media → payload.open_action.rich_media.code.
link → payload.open_action.link.url.
minimize_link (0 또는 2) → payload.open_action.link.shortener (NONE 또는 BITLY).
inbox_image → payload.content.localized_content.{locale}.{platform}.inbox.image_url (각 플랫폼 블록에는 자체 inbox가 있습니다).
inbox_date → payload.content.localized_content.{locale}.{platform}.inbox.expiration_date.
inbox_days: 지원되지 않습니다. 클라이언트 측에서 절대적인 expiration_date로 변환하세요.

전송 제어

dynamic_content / dynamic_content_placeholders → segment 또는 transactional의 dynamic_content_placeholders.
campaign → segment 또는 transactional의 campaign.
capping_days → frequency_capping.days.
capping_count → frequency_capping.count.
send_rate (int) → send_rate.value와 send_rate.bucket: "1s".
message_type ("marketing" / "transactional") → message_type (MESSAGE_TYPE_MARKETING / MESSAGE_TYPE_TRANSACTIONAL).

v2에서 지원되지 않음

template_bindings: Liquid 템플릿 바인딩은 v2에서 사용할 수 없습니다. 이에 의존하는 경우 v1을 계속 사용하세요.

플랫폼별 블록

v1은 각 notifications[*] 항목(ios, android, safari, chrome 등)의 최상위 수준에서 플랫폼별 매개변수를 받습니다. v2에서는 이들이 로케일 내부로 이동합니다:

// v1
"notifications": [{
  "content": "Hello",
  "ios":     { "title": "Hi",    "sound": "default.caf" },
  "android": { "header": "Hi",   "led": "#ff0000" }
}]

// v2
"payload": {
  "content": {
    "localized_content": {
      "en": {
        "ios":     { "title": "Hi", "body": "Hello", "sound": "default.caf" },
        "android": { "title": "Hi", "body": "Hello", "led_color": "#ff0000" }
      }
    }
  }
}

플랫폼 블록 내의 필드 이름은 일부 다릅니다. 정확한 v2 이름은 페이로드 참조를 확인하세요.

예시: 이전과 이후

v1 /createMessage (세그먼트로 푸시):

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth":        "YOUR_API_TOKEN",
    "notifications": [{
      "send_date":  "2026-05-01 12:00",
      "content":    "Hello!",
      "platforms":  [1, 3],
      "filter":     "active_users",
      "campaign":   "YYYYY-YYYYY",
      "capping_days":  7,
      "capping_count": 3,
      "message_type":  "marketing"
    }]
  }
}

v2 /messaging/v2/notify:

{
  "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" },
    "frequency_capping": { "days": 7, "count": 3 },
    "campaign":          "YYYYY-YYYYY",
    "message_type":      "MESSAGE_TYPE_MARKETING"
  }
}

/createTargetedMessage에서 마이그레이션

/createTargetedMessage는 대부분의 경우 transactional에 매핑되거나, 명시적 식별자 없이 순수하게 앱 간 devices_filter로 사용하던 경우 segment에 매핑됩니다.

devices_filter → segment.expression (seglang) 또는 segment.filter_expression (구조화).
content → payload.content.localized_content.{locale}.{platform}.body.
다른 모든 필드는 위의 /createMessage와 동일합니다.

/createEmailMessage에서 마이그레이션

platforms: ["EMAIL"] 및 email_payload 블록과 함께 Notify로 이동하세요. 전체 참조: 이메일 페이로드 참조.

subject → email_payload.subject (로케일로 키가 지정된 맵. 단일 로케일 값을 {"en": "..."}으로 래핑).
content (HTML) → email_payload.body.
email_template → email_payload.email_template.
from / from_name → email_payload.from ({ "name": "...", "email": "..." }).
reply_to / reply_to_name → email_payload.reply_to.
list_unsubscribe → email_payload.list_unsubscribe.
attachments → email_payload.attachments ([{ "name": "...", "content": "<base64>" }]).
타겟팅, 스케줄, 캠페인 등은 /createMessage와 동일합니다.

/createSMSMessage에서 마이그레이션

platforms: ["SMS"]와 함께 Notify로 이동하세요. SMS 본문은 앱에 구성된 SMS 제공업체를 통해 전달됩니다. 채워진 플랫폼 블록의 payload.content.localized_content.{locale}.{platform}.body에 콘텐츠를 넣으세요.

SMS 관련 제공업체 옵션(발신자 ID 등)은 요청 본문이 아닌 앱의 SMS 구성에서 계속 가져옵니다.

/createSMSMessage에는 MMS에 해당하는 기능이 없습니다. MMS(제목 + 이미지 첨부)를 보내려면 sms.subject와 sms.file_urls를 사용하세요 — MMS 참조.

/createKakaoMessage에서 마이그레이션

platforms: ["KAKAO"]와 함께 Notify로 이동하고, payload.content.localized_content.{locale}.kakao를 사용하세요:

template_id → kakao.template.
content → kakao.content.
variables → kakao.content_variables (JSON 문자열화).

/createWhatsAppMessage에서 마이그레이션

platforms: ["WHATS_APP"]와 함께 Notify로 이동하고, payload.content.localized_content.{locale}.whatsapp을 사용하세요:

content (자유 형식 텍스트) → whatsapp.content. 24시간 고객 서비스 창 내에서만 Meta에서 전달됩니다.
content_id → whatsapp.content_id. 사전 승인된 Meta 템플릿의 이름입니다.
language → whatsapp.language. Meta 템플릿 로케일(예: "en_US"). 외부 LocalizedContent 로케일 키와는 독립적입니다.
content_variables (v1의 객체) → whatsapp.content_variables (JSON 문자열화된 객체). 예시 v1 {"1": "John"}은 v2에서 "{\"1\":\"John\"}"이 됩니다.
button_url_variables (객체) → whatsapp.button_url_variables (JSON 문자열화).
header_variables (객체) → whatsapp.header_variables (JSON 문자열화).
preset → payload.preset (페이로드 수준의 일반 프리셋).
타겟팅: v1에서 devices로 들어갔던 WhatsApp 전화번호(예: "whatsapp:+1234567890")는 /registerDevice를 통해 사용자에 대해 등록해야 합니다. v2에서는 transactional.users.list (또는 transactional.hwids.list를 통한 hwid)로 결과 사용자를 타겟팅합니다.
use_auto_registration: 지원되지 않습니다. 보내기 전에 WhatsApp 번호를 등록하세요.

/createLineMessage에서 마이그레이션

platforms: ["LINE"]과 함께 Notify로 이동하고, payload.content.localized_content.{locale}.line을 사용하세요:

content (일반 텍스트) → line.content.
preset (LINE 프리셋 코드) → line.template. v2 필드는 Pushwoosh Control Panel에서 구성된 LINE 템플릿을 참조하는 코드를 저장합니다.
인라인 template (v1 이미지, 캐러셀 또는 플렉스 메시지 구조): v2에서 직접 지원되지 않습니다. 리치 메시지를 Control Panel에서 LINE 프리셋으로 사전 구성하고 line.template를 통해 참조하세요.
타겟팅: v1 devices 목록(SDK / /registerDevice를 통해 등록된 LINE 사용자 ID)은 v2에서 transactional.users.list (또는 transactional.hwids.list를 통한 hwid)가 됩니다.

응답 차이점

v1 /createMessage는 다음을 반환합니다:

{
  "status_code": 200,
  "status_message": "OK",
  "response": { "Messages": ["XXXXX-XXXXX-AAAAA"] }
}

v2 Notify는 다음을 반환합니다:

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

200이 아닌 응답은 v1의 status_code / status_message 쌍 대신 표준 gRPC-Gateway 오류 봉투({ "code": ..., "message": ..., "details": [...] })를 따릅니다.