Migration von v1

Dieser Leitfaden bildet jedes veraltete /create*Message-Feld auf sein Äquivalent in der Messaging API v2 ab. Verwenden Sie ihn als Referenz beim Portieren bestehender Integrationen.

Hinweis

Die veralteten v1-Methoden sind deprecated, aber voll funktionsfähig. Es gibt kein festes Enddatum, sodass Sie in Ihrem eigenen Tempo migrieren können. Für neue Integrationen verwenden Sie die Messaging API v2.

Wesentliche Unterschiede

Aspekt	v1	v2
Endpunkt pro Kanal	separate Methode pro Kanal (/createMessage, /createEmailMessage, /createSMSMessage, /createKakaoMessage, …)	einzelner Endpunkt — POST /messaging/v2/notify
Authentifizierung	auth-Feld im Request-Body	Authorization: Token <API_TOKEN> Header
Targeting	gemischt: filter + conditions + devices + users in derselben Anfrage	explizite Trennung: NotifySegment vs. NotifyTransactional
Inhalt	flacher content + nebengeordnete Plattform-Blöcke	verschachteltes payload.content.localized_content.{locale}.{platform}
Antwort	MessageCode[]	message_code + optional unknown_identifiers

Von /createMessage

v1 notifications[*]-Einträge werden zu einzelnen Notify-Anfragen (eine Nachricht pro Anfrage). Wenn ein v1-Aufruf mehrere Einträge hat, führen Sie eine Notify-Anfrage pro Eintrag aus.

Targeting-Entscheidung. Wenn der v1-Eintrag devices oder users (explizite Listen) verwendet, bilden Sie ihn auf transactional ab. Andernfalls bilden Sie ihn auf segment ab.

Felder auf Anfrageebene

• application → segment.application oder transactional.application (gleiches App-Code-Format).
• applications_group: wird in v2 nicht unterstützt. Verwenden Sie mehrere Anfragen pro App.
• auth: wurde in den Authorization-Header verschoben, nicht mehr im Body.
• transactionId → transaction_id, ein Feld auf Anfrageebene neben segment / transactional. Gleiches Deduplizierungsverhalten wie in v1: Ein wiederholter Aufruf mit demselben Wert innerhalb von 5 Minuten gibt den ursprünglichen message_code zurück, anstatt erneut zu senden, wobei nur der Schlüssel und nicht der Payload abgeglichen wird. Siehe transaction_id.

Zeitplanung

• send_date ("JJJJ-MM-TT HH:mm" oder "now") → schedule.at (RFC 3339 UTC-Zeitstempel). Um v1 "now" zu reproduzieren, setzen Sie schedule.at auf die aktuelle Zeit. Jeder Zeitstempel in der Vergangenheit wird sofort gesendet.
• ignore_user_timezone → schedule.follow_user_timezone. Umgekehrt: ignore_user_timezone: true wird zu follow_user_timezone: false.
• timezone: nicht unterstützt. v2 verwendet immer UTC für at. Konvertieren Sie clientseitig.

Targeting

• filter (Segmentname) → segment.code.
• conditions ([[tag, op, value], ...]) → segment.expression. Schreiben Sie es in einen seglang-Ausdruck um. In seglang ist * das logische UND und app-spezifische Tags werden als Tag("<application-code>", "<tag>", <op>, <value>) referenziert. Beispiel: [["Country","EQ","BR"],["Language","EQ","pt"]] mit conditions_operator: AND → Tag("XXXXX-XXXXX", "Country", EQ, "br") * Tag("XXXXX-XXXXX", "Language", EQ, "pt").
• conditions_operator (AND / OR): in segment.expression integriert.
• devices (HWIDs oder Push-Token) → transactional.hwids.list oder transactional.push_tokens.list. v2 trennt die beiden: HWIDs gehen in hwids, rohe Push-Token in push_tokens.
• users → transactional.users.list.
• platforms (numerische Codes [1, 3, …]) → segment.platforms oder transactional.platforms (String-Enums ["IOS", "ANDROID", …]). Siehe Platform-Enum.

Inhalt

• content (String) → payload.content.localized_content.default.{platform}.body. In v2 ist der Inhalt immer pro Locale und pro Plattform. Setzen Sie einen einfachen v1-String unter den speziellen "default"-Schlüssel (Catch-all-Übersetzung, siehe Locale-Auswahl).
• content ({locale: text}) → payload.content.localized_content.{locale}.{platform}.body. Duplizieren Sie den Body in jeden anvisierten Plattform-Block.
• preset → payload.preset.
• data → payload.custom_data.
• rich_media → payload.open_action.rich_media.code.
• link → payload.open_action.link.url.
• minimize_link (0 oder 2) → payload.open_action.link.shortener (NONE oder BITLY).
• inbox_image → payload.content.localized_content.{locale}.{platform}.inbox.image_url (jeder Plattform-Block hat seine eigene inbox).
• inbox_date → payload.content.localized_content.{locale}.{platform}.inbox.expiration_date.
• inbox_days: nicht unterstützt. Konvertieren Sie clientseitig in ein absolutes expiration_date.

Zustellungssteuerung

• dynamic_content / dynamic_content_placeholders → dynamic_content_placeholders auf segment oder transactional.
• campaign → campaign auf segment oder transactional.
• capping_days → frequency_capping.days.
• capping_count → frequency_capping.count.
• send_rate (int) → send_rate.value mit send_rate.bucket: "1s".
• message_type ("marketing" / "transactional") → message_type (MESSAGE_TYPE_MARKETING / MESSAGE_TYPE_TRANSACTIONAL).

In v2 nicht unterstützt

• template_bindings: Liquid-Template-Bindungen sind in v2 nicht verfügbar. Verwenden Sie weiterhin v1, wenn Sie darauf angewiesen sind.

Plattformspezifische Blöcke

v1 akzeptiert plattformspezifische Parameter auf der obersten Ebene jedes notifications[*]-Eintrags (ios, android, safari, chrome, …). In v2 werden sie in die Locale verschoben:

// 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" }
      }
    }
  }
}

Die Feldnamen innerhalb der Plattform-Blöcke unterscheiden sich an einigen Stellen. Die genauen v2-Namen finden Sie in der Payload-Referenz.

Beispiel: Vorher und nachher

v1 /createMessage (Push an ein 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"
  }
}

Von /createTargetedMessage

/createTargetedMessage wird in den meisten Fällen auf transactional abgebildet oder auf segment, wenn Sie es ausschließlich als app-übergreifenden devices_filter ohne explizite Identifikatoren verwendet haben.

• devices_filter → segment.expression (seglang) oder segment.filter_expression (strukturiert).
• content → payload.content.localized_content.{locale}.{platform}.body.
• Alle anderen Felder, wie bei /createMessage oben.

Von /createEmailMessage

Wechseln Sie zu Notify mit platforms: ["EMAIL"] und einem email_payload-Block. Vollständige Referenz: E-Mail-Payload-Referenz.

• subject → email_payload.subject (Map, deren Schlüssel die Locale ist. Umschließen Sie ein-locale-Werte mit {"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>" }]).
• Targeting, Zeitplan, Kampagne usw., wie bei /createMessage.

Von /createSMSMessage

Wechseln Sie zu Notify mit platforms: ["SMS"]. Der SMS-Body wird über den konfigurierten SMS-Anbieter der App zugestellt. Fügen Sie den Inhalt in payload.content.localized_content.{locale}.{platform}.body in einem beliebigen ausgefüllten Plattform-Block ein.

SMS-spezifische Anbieteroptionen (Absender-ID usw.) stammen weiterhin aus der SMS-Konfiguration der App und nicht aus dem Request-Body.

/createSMSMessage hat kein MMS-Äquivalent. Um MMS (Betreff + Bildanhänge) zu senden, verwenden Sie sms.subject und sms.file_urls – siehe MMS.

Von /createKakaoMessage

Wechseln Sie zu Notify mit platforms: ["KAKAO"] und verwenden Sie payload.content.localized_content.{locale}.kakao:

• template_id → kakao.template.
• content → kakao.content.
• variables → kakao.content_variables (als JSON-String).

Von /createWhatsAppMessage

Wechseln Sie zu Notify mit platforms: ["WHATS_APP"] und verwenden Sie payload.content.localized_content.{locale}.whatsapp:

• content (Freitext) → whatsapp.content. Wird von Meta nur innerhalb des 24-Stunden-Kundenservice-Fensters zugestellt.
• content_id → whatsapp.content_id. Name einer vorab genehmigten Meta-Vorlage.
• language → whatsapp.language. Meta-Vorlagen-Locale (z. B. "en_US"). Unabhängig vom äußeren LocalizedContent-Locale-Schlüssel.
• content_variables (Objekt in v1) → whatsapp.content_variables (als JSON-String dargestelltes Objekt). Beispiel v1 {"1": "John"} wird zu v2 "{\"1\":\"John\"}".
• button_url_variables (Objekt) → whatsapp.button_url_variables (als JSON-String).
• header_variables (Objekt) → whatsapp.header_variables (als JSON-String).
• preset → payload.preset (generisches Preset auf Payload-Ebene).
• Targeting: Die WhatsApp-Telefonnummer, die in v1 in devices eingetragen wurde (z. B. "whatsapp:+1234567890"), muss über /registerDevice für einen Benutzer registriert werden. In v2 zielen Sie auf den resultierenden Benutzer mit transactional.users.list (oder die HWID über transactional.hwids.list).
• use_auto_registration: nicht unterstützt. Registrieren Sie die WhatsApp-Nummer vor dem Senden.

Von /createLineMessage

Wechseln Sie zu Notify mit platforms: ["LINE"] und verwenden Sie payload.content.localized_content.{locale}.line:

• content (Klartext) → line.content.
• preset (LINE-Preset-Code) → line.template. Das v2-Feld speichert einen Code, der auf eine im Pushwoosh Control Panel konfigurierte LINE-Vorlage verweist.
• Inline-template (v1-Bild-, Karussell- oder Flex-Nachrichtenstrukturen): wird in v2 nicht direkt unterstützt. Konfigurieren Sie die Rich Message als LINE-Preset im Control Panel vor und verweisen Sie darauf über line.template.
• Targeting: Die v1-devices-Liste (LINE-Benutzer-IDs, die über das SDK / /registerDevice registriert wurden) wird in v2 zu transactional.users.list (oder die HWID über transactional.hwids.list).

Unterschiede bei der Antwort

v1 /createMessage gibt zurück:

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

v2 Notify gibt zurück:

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

Nicht-200-Antworten folgen dem Standard-gRPC-Gateway-Fehlerformat ({ "code": ..., "message": ..., "details": [...] }) anstelle des v1-Paares status_code / status_message.