从 v1 迁移

本指南将每个旧版 /create*Message 字段映射到其 Messaging API v2 中的对应字段。在移植现有集成时，请以此为参考。

注意

旧版 v1 方法已弃用，但仍可完全运行。没有硬性的停用日期，因此您可以按照自己的节奏进行迁移。对于新的集成，请使用 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 名称) → segment.code。
• conditions ([[tag, op, value], ...]) → segment.expression。重写为 seglang 表达式。在 seglang 中，* 是逻辑与 (AND)，特定于应用的标签引用为 Tag("<application-code>", "<tag>", <op>, <value>)。例如：[["Country","EQ","BR"],["Language","EQ","pt"]] 加上 conditions_operator: AND → Tag("XXXXX-XXXXX", "Country", EQ, "br") * Tag("XXXXX-XXXXX", "Language", EQ, "pt")。
• conditions_operator (AND / OR)：已并入 segment.expression。
• devices (hwids 或 push tokens) → transactional.hwids.list 或 transactional.push_tokens.list。v2 将两者分开：hwids 放入 hwids，原始 push tokens 放入 push_tokens。
• users → transactional.users.list。
• platforms (数字代码 [1, 3, …]) → segment.platforms 或 transactional.platforms (字符串枚举 ["IOS", "ANDROID", …])。请参阅 Platform enum。

内容

• 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 → dynamic_content_placeholders on segment or transactional。
• campaign → campaign on segment or transactional。
• capping_days → frequency_capping.days。
• capping_count → frequency_capping.count。
• send_rate (int) → send_rate.value with send_rate.bucket: "1s"。
• message_type ("marketing" / "transactional") → message_type (MESSAGE_TYPE_MARKETING / MESSAGE_TYPE_TRANSACTIONAL)。

v2 不支持的功能

• template_bindings：v2 中不提供 Liquid 模板绑定。如果您依赖此功能，请继续使用 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 (向一个 segment 推送)：

{
  "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。短信正文通过应用配置的短信提供商发送。将内容放在任何已填充的平台块的 payload.content.localized_content.{locale}.{platform}.body 中。

特定于短信提供商的选项（发件人 ID 等）继续来自应用的短信配置，而不是请求体。

/createSMSMessage 没有对应的彩信 (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 控制面板中配置的 LINE 模板。
• 内联 template (v1 的图片、轮播或 flex 消息结构)：v2 不直接支持。请在控制面板中将富媒体消息预先配置为 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 响应遵循标准的 gRPC-Gateway 错误封装格式（{ "code": ..., "message": ..., "details": [...] }），而非 v1 的 status_code / status_message 对。