Journey-Objekt

Die Methoden lifecycle, create und update geben alle ein Journey-Objekt mit der gleichen Top-Level-Struktur zurück:

Struktur

{
  "info": { ... },        // schreibgeschützte Metadaten (nur Antworten)
  "params": { ... },      // Journey-weite Konfiguration (erstellen / aktualisieren)
  "points": [ ... ],      // Canvas-Knoten und ihre Verbindungen
  "comments": [ ... ]     // Canvas-Kommentare
}

Wenn Sie eine Journey erstellen oder aktualisieren, senden Sie title, params, points und comments. Antworten geben info (welches params enthält) sowie points und comments zurück.

Info

Schreibgeschützte Journey-Metadaten. Wird von jeder v3-Methode zurückgegeben. Nicht Teil des Anfragekörpers.

Feld	Typ	Beschreibung
uuid	string	Journey-ID.
title	string	Journey-Name.
status	JourneyStatus	Aktueller Zustand.
created_at	string	Erstellungszeitstempel (ISO 8601).
updated_at	string	Letzter Aktualisierungszeitstempel (ISO 8601).
is_first_activated	bool	Gibt an, ob die Journey mindestens einmal gestartet wurde.
params	JourneyParams	Journey-weite Konfiguration.
category_uuid	string	UUID der Kategorie oder leer, wenn nicht kategorisiert.
pointCounts	map<string, uint32>	Anzahl der Points nach Typ.
campaign_type	CampaignType	Wie Benutzer in die Journey eintreten.
stop_reason	string	Grund für den Stopp der Journey, falls zutreffend.
last_edited_by	User	Benutzer, der die Journey zuletzt bearbeitet hat.
dynamic_entry	bool	Gibt an, ob der dynamische Eintritt aktiviert ist.

JourneyParams

Journey-weite Konfiguration. Wird beim Erstellen/Aktualisieren gesendet und innerhalb von info.params zurückgegeben.

Feld	Typ	Beschreibung
application_code	string	Application Code, zu dem die Journey gehört. Erforderlich bei der Erstellung.
silent_hours	SilentHours	Stunden, in denen Nachrichten unterdrückt werden, pro Kanal.
capping	EntryCapping	Begrenzungen, wie oft ein Benutzer erneut in die Journey eintreten kann.
conversion_window	ConversionWindow	Zeitfenster für die Zuordnung von Ziel-Conversions.
user_id_track_change_policy	UserIDTrackChangePolicy	Wie mit der ID eines Benutzers umgegangen wird, die sich mitten in der Journey ändert.

SilentHours

Unterdrückt das Senden während der Ruhezeiten. Konfiguriert pro Kanal: Jeder Kanal verwendet seine eigenen SilentHoursParams:

Feld	Typ	Beschreibung
push_params	SilentHoursParams	Ruhezeiten für Push-Benachrichtigungen.
inapp_params	SilentHoursParams	Ruhezeiten für In-App-Nachrichten.
email_params	SilentHoursParams	Ruhezeiten für E-Mails.
sms_params	SilentHoursParams	Ruhezeiten für SMS.
whatsapp_params	SilentHoursParams	Ruhezeiten für WhatsApp.
line_params	SilentHoursParams	Ruhezeiten für LINE.

Jeder SilentHoursParams ist:

Feld	Typ	Beschreibung
enabled	bool	Gibt an, ob Ruhezeiten für diesen Kanal gelten.
from_time	Time	Beginn des Ruhefensters: { "hour": 0–23, "minute": 0–59 }.
to_time	Time	Ende des Ruhefensters.
week_days	bool[]	Sieben boolesche Werte für die Tage, an denen das Fenster gilt (Montag = Index 0).
behavior	enum	Was zu tun ist, wenn eine Nachricht in die Ruhezeiten fällt: WaitAndSend (zurückhalten, dann senden, wenn das Fenster endet), DropAndGo (die Nachricht überspringen, die Journey sofort fortsetzen) oder WaitAndDrop (das Fenster abwarten, dann fortfahren, ohne zu senden).

EntryCapping

Begrenzt, wie oft derselbe Benutzer in die Journey eintreten kann.

Feld	Typ	Beschreibung
is_enabled	bool	Gibt an, ob das Entry Capping aktiviert ist.
period	uint64	Mindestanzahl an Minuten zwischen den Eintritten eines Benutzers. 0 bedeutet, dass der Benutzer nur einmal im Leben eintreten kann.

Das Limit wird ab dem Moment gezählt, in dem der Benutzer die Journey betreten hat, und es wird pro User ID verfolgt, sodass alle Geräte eines Benutzers einen einzigen Eintritt teilen. Während der Periode andauert, lehnt der Eintrittspunkt weitere Eintrittsversuche ab und zählt sie als Fehler, anstatt einen Traveler zu erstellen.

Drei Verhaltensweisen, die Sie bei der Änderung dieser Einstellungen berücksichtigen sollten:

• Das vorzeitige Verlassen der Journey hebt das Limit nicht auf. Der Benutzer wartet die volle Periode ab, auch nachdem er einen Austrittspunkt erreicht hat.
• Eine geänderte period gilt für Eintritte, die nach der Aktualisierung erfolgen. Benutzer, die früher eingetreten sind, behalten die Periode, die bei ihrem Eintritt in Kraft war.
• Das Setzen von is_enabled auf false hebt das Limit für jeden Benutzer sofort auf.

Hinweis

Das Control Panel schreibt dasselbe Feld aus dem Kampagnen-Eintrittslimit, das 0 (einmal im Leben), 1440 (einmal pro Tag), 10080 (einmal pro Woche), 43800 (einmal pro Monat) und 131500 (einmal alle drei Monate) anbietet.

ConversionWindow

Feld	Typ	Beschreibung
seconds	uint64	Wie lange nach dem Eintritt in eine Journey der Abschluss eines Ziels durch einen Benutzer noch als Conversion zählt.

Point

Ein Point ist ein Knoten auf dem Journey-Canvas: ein Eintrittspunkt, eine Nachricht, eine Verzögerung, ein Splitter und so weiter.

Feld	Typ	Beschreibung
uuid	string	Eindeutige ID des Points innerhalb der Journey. Muss eine kanonische RFC 4122 UUID sein: 32 Hex-Ziffern in 8-4-4-4-12 Gruppen.
title	string	Anzeigename des Points.
point_type	PointType	Die Art des Knotens.
outputs	array of PointOutput	Verbindungen zu nachgelagerten Points.
position	Position	Canvas-Koordinaten.
point_data	object	Genau ein verschachtelter Schlüssel, der mit point_type übereinstimmt (siehe die Tabelle Point-Typen und point_data).

Hinweis

Alle UUIDs (info.uuid, jede Point-uuid und die next_point_uuid jeder Ausgabe) müssen kanonische RFC 4122 UUIDs sein (8-4-4-4-12 Hex-Gruppen).

PointOutput

Die Ausgaben eines Points sind seine ausgehenden Zweige. Ihre Schlüssel sind nicht frei wählbar. Der Validator erwartet für jeden Point-Typ einen exakten Satz von Schlüsseln und lehnt eine Journey ab, deren Point die falsche Anzahl von Ausgaben oder einen nicht erkannten Schlüssel hat.

Feld	Typ	Beschreibung
identity.key	string	Zweig-Schlüssel. Muss den unten stehenden Regeln für Ausgabeschlüssel folgen.
identity.order	int	Anzeigereihenfolge des Zweigs.
info.title	string	Optionales Zweig-Label.
info.next_point_uuid	string	UUID des nächsten Points, mit dem dieser Zweig verbunden ist. Optional — das Weglassen beendet die Journey für den Benutzer, genauso wie ein expliziter Terminator-Point.

Ausgabeschlüssel

Der Standardzweig (der erste) heißt immer "default". Zusätzliche Zweige heißen "output1", "output2", … (das Präfix output gefolgt von einem 1-basierten Index). Zwei Point-Typen brechen diese Regel, wie unten vermerkt.

Point-Typ	Erwartete Ausgabeschlüssel
Eintrittspunkte (START_BY_SEGMENT, START_BY_API, EVENT), INAPP, SET_TAGS, WEBHOOK, AUDIENCE_SYNC und Nachrichtenpunkte ohne Splitter (SEND_PUSH, SEND_EMAIL, SEND_SMS, SEND_WHATSAPP, SEND_LINE, SEND_KAKAO, SEND_TELEGRAM, SEND_DATA)	default
GOAL_EVENT, EXIT	keine (keine Ausgaben)
FILTER	default, output1
BOOLEAN_SPLITTER	default, dann output1 … outputN (ein zusätzlicher Zweig pro Bedingung. Eine einfache Ja/Nein-Aufteilung ist default + output1)
WAIT (Verzögerung)	default. Eine dynamische Verzögerung mit Zweigaufteilung fügt output1 hinzu
WAIT_EVENT	default ist der Zweig für nicht ausgelöste Ereignisse. output1 (oder, mit einem Bedingungsskript, ein Zweig pro Bedingung) ist der ausgelöste Pfad
SEND_PUSH mit einem Splitter	default, output1 (und output2, wenn sowohl der Nachrichten- als auch der Zustellungs-Splitter aktiviert sind)
SEND_EMAIL / SEND_SMS / SEND_LINE / SEND_WHATSAPP mit einem Splitter	default, output1
SEND_WHATSAPP mit einer Schnellantwort-Voreinstellung	default, plus ein Zweig pro Schnellantwort. Der Schlüssel ist der Wert der Schnellantwort selbst
AB_SPLITTER	output0, output1, output2, … (einer pro Variante. Es gibt keinen default-Zweig)

Position

Feld	Typ	Beschreibung
x	float	Horizontale Koordinate auf dem Canvas.
y	float	Vertikale Koordinate auf dem Canvas.

Point-Typen und point_data

point_data ist ein One-of: Es enthält genau ein verschachteltes Objekt, dessen Schlüssel durch den point_type des Points bestimmt wird.

point_type	point_data-Schlüssel	Zweck
POINT_TYPE_START_BY_SEGMENT	start_by_segment	Eintritt: Benutzer, die einem Segment entsprechen.
POINT_TYPE_EVENT	message_bus	Eintritt: Benutzer, die ein Ereignis auslösen.
POINT_TYPE_START_BY_API	start_by_api	Eintritt: Benutzer, die über den Start by API-Aufruf injiziert werden.
POINT_TYPE_WAIT	delay	Warten für ein festes oder dynamisches Intervall.
POINT_TYPE_WAIT_EVENT	wait_event	Warten, bis ein Ereignis eintritt.
POINT_TYPE_SEND_PUSH	send_push	Eine Push-Benachrichtigung senden.
POINT_TYPE_SEND_EMAIL	send_email	Eine E-Mail senden.
POINT_TYPE_SEND_SMS	send_sms	Eine SMS senden.
POINT_TYPE_SEND_WHATSAPP	send_whatsapp	Eine WhatsApp-Nachricht senden.
POINT_TYPE_SEND_TELEGRAM	send_telegram	Eine Telegram-Nachricht senden.
POINT_TYPE_SEND_KAKAO	send_kakao	Eine Kakao-Nachricht senden.
POINT_TYPE_SEND_LINE	send_line	Eine LINE-Nachricht senden.
POINT_TYPE_SEND_DATA	send_data	Eine stille Datennachricht senden.
POINT_TYPE_INAPP	inapp	Eine In-App-Nachricht anzeigen.
POINT_TYPE_BOOLEAN_SPLITTER	boolean_splitter	Benutzer nach einer Bedingung aufteilen (Segment, Tags oder Ereignis).
POINT_TYPE_AB_SPLITTER	ab_splitter	Benutzer in A/B-Gruppen aufteilen.
POINT_TYPE_FILTER	filter	Nur Benutzern, die einem Filter entsprechen, das Fortfahren erlauben.
POINT_TYPE_SET_TAGS	set_tags	Benutzer-Tags aktualisieren.
POINT_TYPE_WEBHOOK	web_hook	Eine ausgehende HTTP-Anfrage senden.
POINT_TYPE_GOAL_EVENT	goal_event	Ein Conversion-Ziel verfolgen.
POINT_TYPE_AUDIENCE_SYNC	audience_sync	Benutzer mit einer externen Audience synchronisieren.
POINT_TYPE_EXIT	terminator	Die Journey verlassen.

Hinweis

Die typspezifischen point_data-Payloads sind in der Point-Referenz dokumentiert. Eintritts-, Timing-, Aufteilungs- und Aktionspunkte werden dort vollständig behandelt. Nachrichtenpunkte werden auf der Hüllenebene mit Links zu den relevanten Kanaldokumenten behandelt.

Beispiel-Point

Ein “Tags setzen”-Point mit einer einzigen nachgelagerten Verbindung:

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "Tag as engaged",
  "point_type": "POINT_TYPE_SET_TAGS",
  "position": { "x": 480, "y": 120 },
  "outputs": [
    {
      "identity": { "key": "default", "order": 0 },
      "info": { "title": "", "next_point_uuid": "ffffffff-1111-2222-3333-444444444444" }
    }
  ],
  "point_data": {
    "set_tags": {
      "application_code": "XXXXX-XXXXX",
      "tags": [ { "name": "engaged", "value": "true" } ]
    }
  }
}

JourneyComment

Feld	Typ	Beschreibung
id	string	Kommentar-UUID.
message	string	Kommentartext.
position	Position	Canvas-Koordinaten.
index	int	Anzeigereihenfolge.
created_at	string	Erstellungszeitstempel (ISO 8601).
deleted	bool	Gibt an, ob der Kommentar gelöscht ist.

Enums

JourneyStatus-Enum

STATUS_DRAFT, STATUS_RUNNING, STATUS_FINISHED, STATUS_ARCHIVED, STATUS_PAUSED, STATUS_UNKNOWN.

CampaignType-Enum

• TriggerBased: Benutzer treten bei einem Ereignis ein.
• AudienceBased: Benutzer treten aus einem Segment ein.
• APIBased: Benutzer treten über den Start by API-Aufruf ein.
• Mixed: mehr als ein Eintrittstyp.
• Unknown: Eintrittstyp nicht bestimmt.

PointType-Enum

Siehe die Tabelle Point-Typen oben für die vollständige Liste und den point_data-Schlüssel, dem jeder zugeordnet ist.

UserIDTrackChangePolicy-Enum

Steuert, was mit einem Benutzer geschieht, der sich mitten in einer Journey befindet, wenn sich seine User ID ändert:

• DEFAULT: Standardverhalten.
• TRACK: den Benutzer unter der neuen ID weiterverfolgen.
• DROP: den Benutzer aus der Journey entfernen, wenn sich seine ID ändert.

Verwandte Themen

Point-Referenz

Erstellen und Aktualisieren

Lebenszyklus