Variablen in Nachrichten

Eine Variable ist ein Platzhalter im Text einer Nachricht. An ihrer Stelle erhält jeder Empfänger seinen eigenen Wert — einen Namen, einen Firmennamen, eine Bestellnummer. So senden Sie einen einzigen Text an Tausende von Menschen, und jeder von ihnen liest eine Nachricht, die für ihn geschrieben ist. Variablen werden in einer Kampagne und in der API gleich geschrieben.

So schreiben Sie eine Variable

Eine Variable ist ein Name in spitzen Klammern, zum Beispiel <first_name>. Beim Versand wird sie durch den Wert ersetzt, den Sie für den jeweiligen Empfänger haben:

• Der Name muss genau übereinstimmen. Groß- und Kleinschreibung sowie Leerzeichen spielen eine Rolle — weder <First_Name> noch < first_name > wird durch den Wert von first_name ersetzt.
• Ein leerer Wert gilt als fehlender Wert. Leerer Text oder Text, der nur aus Leerzeichen besteht, zählt als fehlender Wert — was dann passiert, beschreibt Wenn der Wert fehlt.

Wenn der Wert fehlt

Wenn Sie für einen Empfänger keinen Wert haben, bleibt die Variable wörtlich in der Nachricht stehen — der Empfänger erhält Hallo <first_name>, …. Das verhindern Sie mit einem Standardwert, den Sie nach einem Doppelpunkt schreiben:

Ein Empfänger, für den Sie einen Wert haben, erhält in allen drei Fällen seinen eigenen Wert.

Filter

Ein Filter passt den eingesetzten Wert an — er wandelt ihn in Großbuchstaben um, entfernt Leerzeichen, macht aus einem Namen eine Anrede oder achtet auf seine Länge. Sie schreiben ihn nach einem senkrechten Strich direkt hinter den Variablennamen: <first_name|upper>. Sie können mehrere Filter hintereinander schreiben; sie werden von links nach rechts angewendet: <city|trim|capitalize> — mehr dazu unter Filter verketten.

Groß- und Kleinschreibung

Textanpassungen

Name und Anrede

Zwei Filter arbeiten mit tschechischen Namen: vocative bildet die Anrede im tschechischen Vokativ, und gender wählt anhand des Namens einen Text für einen Mann oder für eine Frau. Sie folgen denselben Regeln wie die Variablen <first_name_vokativ> und <last_name_vokativ> — wie der Vokativ gebildet wird, beschreibt Tschechische Anrede.

• Vokativ aus jeder Variablen. Anders als <first_name_vokativ> lässt sich der Filter vocative auf jede Variable anwenden — zum Beispiel auf einen vollständigen Namen, der in einem einzigen Feld gespeichert ist, oder auf einen Wert, den Sie in der API senden.
• Geschlecht und Art des Namens erkennt der Filter vocative selbst anhand der Endung. Liegt er falsch, legen Sie beides mit Parametern fest: Der erste ist man oder woman, der zweite first (Vorname) oder last (Nachname), zum Beispiel <last_name|vocative:woman,last>. Der Standardwert beider Parameter, auto, überlässt die Entscheidung dem Filter.
• Groß- und Kleinschreibung. Jedes Wort im Vokativ beginnt mit einem Großbuchstaben, die übrigen Buchstaben sind klein: NOVÁK → Nováku.
• Auch der Standardwert wird dekliniert, schreiben Sie ihn daher im Nominativ: Ein Empfänger ohne Namen erhält aus <first_name:zákazník|vocative> den Text Zákazníku.
• Der Text für das Geschlecht ersetzt den Wert, schreiben Sie die Variable daher zweimal in den Text: <first_name|gender:Milý,Milá> <first_name|vocative> ergibt Milý Petře oder Milá Jano. Der Text kann auch nur ein Wortende sein: Vážen<first_name|gender:ý pane,á paní> ergibt Vážený pane oder Vážená paní. Beide Texte sind Pflicht, dürfen aber leer sein; sie dürfen weder <, >, | noch ein Komma enthalten.
• Ohne Namen wird das Geschlecht anhand des Standardwerts bestimmt — <first_name:zákazníku|gender:Milý,Milá> ergibt für einen Empfänger ohne Namen Milý. Ein leerer Standardwert ergibt immer den Text für einen Mann.

Längenbegrenzung

Filter mit einer Zahl achten auf die maximale Anzahl von Zeichen, die der Wert haben darf. Sie sind nützlich bei langen Werten wie einem Firmennamen oder einer Adresse, die die Nachricht sonst auf einen weiteren SMS-Teil verlängern würden. Der Filter bestimmt, was mit einem längeren Wert geschieht:

Ein Wert, der in das Limit passt, wird vollständig eingesetzt.

Bei truncate, ellipsis und fallback können Sie nach einem Komma einen eigenen Text schreiben, der anstelle des Standardtexts verwendet wird:

Ihr eigener Text darf weder <, >, | noch ein Komma enthalten. Ein leerer Text (truncate:8,) kürzt den Wert ohne Zusatz.

Filter verketten

Sie können Filter frei kombinieren — schreiben Sie sie einfach hintereinander, jeden nach seinem eigenen senkrechten Strich. Sie werden der Reihe nach von links nach rechts angewendet, und jeder Filter erhält das Ergebnis des vorherigen. So können Sie eine Längenbegrenzung mit einer Änderung der Groß- und Kleinschreibung und dem Entfernen von Leerzeichen kombinieren.

Im dritten Beispiel entfernt trim zuerst die Leerzeichen, truncate:8,… kürzt den Wert auf Kytary… und upper wandelt ihn schließlich in Großbuchstaben um.

• Die Reihenfolge ist wichtig. Dieselben Filter in anderer Reihenfolge ergeben ein anderes Ergebnis. Für den Wert " Ústí nad Labem " ergibt <city|trim|cut:4> den Text Ústí, während <city|cut:4|trim> den Wert zuerst auf die führenden Leerzeichen kürzt und diese dann entfernt — es bleibt nichts übrig.
• Der Standardwert steht vor den Filtern, und die ganze Kette passt auch ihn an: Ein Empfänger ohne Vornamen erhält aus <first_name:zusammen|trim|upper> den Text ZUSAMMEN.
• Jedes Vorkommen einer Variablen hat eigene Filter. Sie können eine Variable mehrmals im Text verwenden, jedes Mal anders: Aus Hallo <first_name|first_upper>, <first_name|upper> erhält ein Empfänger mit dem Wert john den Text Hallo John, JOHN.
• Im Kampagneneditor entspricht die Kette der Reihenfolge der Filter im Dialog der Variablen, und Sie ändern sie per Drag-and-drop. Jeder Filter kann dort einmal verwendet werden.

Worauf Sie achten sollten

Schreiben Sie den Filternamen in Kleinbuchstaben und ohne Leerzeichen und die Zahl nur in Ziffern.

Veraltete Schreibweise mit Gleichheitszeichen

Früher wurde die Länge mit einer Kurzschreibweise begrenzt: Das Limit stand nach einem Gleichheitszeichen, gefolgt von einem Buchstaben, der festlegte, was mit einem längeren Wert geschieht. Diese Schreibweise ist veraltet — verwenden Sie in neuen Nachrichten Filter. Nachrichten, die sie enthalten, funktionieren weiterhin, und der Kampagneneditor schreibt sie in einen Filter um.

Die Kurzschreibweise wird als erster Filter angewendet, auch wenn weitere Filter folgen: <company_name=8|upper> entspricht <company_name|cut:8|upper>.

Variablen in einer Kampagne

Eine Kampagne übernimmt die Werte aus den Kontakten, die Sie ihr hinzufügen — aus dem Adressbuch, aus einem Dateiimport und aus manuell eingegebenen Nummern.

1. Fügen Sie zuerst die Empfänger hinzu. Das Variablenmenü zeigt nur Felder an, die mindestens ein Empfänger der Kampagne ausgefüllt hat. Ohne Empfänger ist es leer.
2. Klicken Sie im Texteditor auf das Symbol Variable hinzufügen oder tippen Sie einfach @. Wenn Sie einen Namen eingeben, wird das Menü eingegrenzt.
3. Wählen Sie die Variable aus. Bei jeder sehen Sie, wie viel Prozent der Empfänger Daten dafür haben.

Die Variable erscheint im Text als Tag mit dem Feldnamen, und seine Farbe zeigt Ihnen, wie es um die Daten steht:

• keine Hervorhebung — alle Empfänger haben die Daten, oder ein Standardwert ist gesetzt,
• Warnung — 30 bis 99 % der Empfänger haben die Daten,
• Fehler — weniger als 30 % der Empfänger haben die Daten, oder es gibt kein solches Feld.

Klicken Sie auf das Tag, um eine Übersicht der Variablen zu sehen, einschließlich ihrer aktiven Filter in der Reihenfolge, in der sie angewendet werden, und bearbeiten Sie die Variable von dort aus:

• Wenn der Wert fehlt — einen Ersatztext ergänzen, die Variable weglassen lassen oder sie im Text belassen.
• Filter — fügen Sie sie einzeln aus einem Menü hinzu, das in Groß- und Kleinschreibung, Textanpassungen, Name und Anrede sowie Länge unterteilt ist. Bei Filtern mit einem Parameter geben Sie eine Zahl oder einen Text ein oder wählen eine Option aus. Die Reihenfolge ändern Sie, indem Sie den Griff ziehen — Filter werden von oben nach unten angewendet —, und einen Filter, den Sie nicht brauchen, löschen Sie. Ein Beispielwert zeigt, was der Filter bewirkt.

Der Editor speichert die Variable in derselben Schreibweise, die unter Wenn der Wert fehlt und Filter beschrieben ist, zum Beispiel <company_name:Ihre Firma|trim|cut:8>. Eine ältere Kurzschreibweise mit Gleichheitszeichen wird dabei in einen Filter umgeschrieben.

Welche Felder Sie verwenden können

Wenn Sie aus einer Datei importieren, ordnen Sie jede Spalte einem dieser Felder zu. Eine Spalte, zu der keines davon passt — eine Bestellnummer, ein Rabattbetrag —, kommt in ein benutzerdefiniertes Feld, und im Text verwenden Sie dann zum Beispiel <custom_field_0>.

Kanäle, Länge und Vorschau

• Kanäle. Variablen funktionieren im Nachrichtentext von SMS, Viber und RCS, bei RCS auch im Titel.
• Länge und Preis. Der Zeichenzähler im Editor rechnet mit den Werten des in der Vorschau ausgewählten Kontakts. Jeder Empfänger kann jedoch unterschiedlich lange Werte haben — deshalb werden die Anzahl der SMS-Teile und der Preis für jeden Empfänger einzeln berechnet, nachdem die Werte eingesetzt wurden.
• Unicode. Diakritische Zeichen aus einem eingesetzten Wert schalten die SMS nur dann auf Unicode um, wenn Sie es in den Texteinstellungen aktiviert haben.
• Vorschau. Sowohl die Nachrichtenvorschau als auch Testnachricht senden setzen die Werte des in der Vorschau ausgewählten Kontakts ein — so sehen Sie vor dem Versand, wie der Text aussehen wird. Ausnahme sind die Filter vocative und gender: Die Vorschau im Editor dekliniert den Namen nicht, sondern markiert ihn nur mit 🗣️, und bei gender zeigt sie beide Texte an, zum Beispiel Milý/Milá. Auch der Zeichenzähler rechnet mit diesen Formen. Das tatsächliche Ergebnis sehen Sie in einer Testnachricht.

Variablen in der API

In der API senden Sie die Werte direkt in der Anfrage, im Parameter variables: einem Objekt, dessen Schlüssel der Variablenname und dessen Wert der einzusetzende Inhalt ist. Der Text verwendet dieselbe Schreibweise, einschließlich Standardwerten und Filtern.

Der Empfänger erhält Hallo Peter, Bestellung 12345 ist unterwegs. Sie können eine Variable beliebig benennen — <order> im Beispiel ist kein Kontaktfeld, sondern nur ein Schlüssel aus variables.

Wohin die Variablen gehören

Welche Werte Sie senden

• Text oder eine Zahl. Zahlen werden unverändert eingesetzt (12 → 12).
• null, false und leerer Text gelten als fehlender Wert — es gilt der Standardwert, andernfalls bleibt die Variable wörtlich im Text.
• Ein Array oder ein Objekt als Wert akzeptiert die Advanced API nicht und gibt den Fehler invalid_input_parameters zurück.
• Zusätzliche Schlüssel, die im Text nicht vorkommen, werden ignoriert.
• Vokativ. Aus first_name und last_name ermittelt die Advanced API first_name_vokativ und last_name_vokativ selbst — sie überschreibt dabei Ihre eigenen Werte dieser beiden Schlüssel. Die Integration API ermittelt den Vokativ nicht. Wie das funktioniert, beschreibt Tschechische Anrede.

Kanäle und Länge

Die Anzahl der SMS-Teile und der Preis werden beide aus dem Text nach dem Einsetzen der Werte berechnet. Diakritische Zeichen aus einem eingesetzten Wert schalten die SMS nur mit "unicode": true auf Unicode um. Viber-, RCS- und WhatsApp-Text, der nach dem Einsetzen der Werte das Limit des Kanals überschreitet (Viber 1.000 Zeichen, RCS und WhatsApp 5.000), wird gekürzt.