Flow JSON

Flow JSON ist das Format, in dem Meta einen WhatsApp Flow beschreibt: welche Bildschirme es gibt, welche Felder und Texte darauf stehen und was jede Schaltfläche auslöst. WhatsApp liest diese Beschreibung und zeigt daraus das Formular im Chat an.

Was ist Flow JSON?

Hinter jedem WhatsApp Flow steht eine Beschreibung im JSON-Format, das Flow JSON. Sie legt fest, welche Bildschirme der Flow hat, welche Komponenten darauf stehen und was beim Tippen auf eine Schaltfläche passiert: zum nächsten Bildschirm wechseln, Daten an einen Server schicken oder den Flow abschließen. Komponenten sind zum Beispiel Überschriften, Texte, Eingabefelder, Auswahllisten, Datumsauswahl, Opt-in-Kästchen und Foto- oder Dokument-Upload.

Die wichtigsten Bestandteile auf oberster Ebene:

• version: die Version des Formats. Sie bestimmt, welche Komponenten zur Verfügung stehen.
• screens: die Liste der Bildschirme mit ihren Komponenten.
• routing_model: die erlaubten Wege zwischen den Bildschirmen. Für Flows mit Daten-Endpunkt ist es Pflicht.
• data_api_version: die Version der Daten-Schnittstelle, ebenfalls nur für Flows mit Endpunkt.

Beispiel: ein Flow mit einem Bildschirm

Dieses Flow JSON beschreibt einen Rückrufwunsch. Ein Bildschirm mit einem Pflichtfeld für die Telefonnummer, und die Schaltfläche in der Fußzeile schließt den Flow ab und gibt die Eingabe zurück:

{
  "version": "7.3",
  "screens": [
    {
      "id": "RUECKRUF",
      "title": "Rückruf",
      "terminal": true,
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextInput",
            "name": "telefon",
            "label": "Telefonnummer",
            "input-type": "phone",
            "required": true
          },
          {
            "type": "Footer",
            "label": "Absenden",
            "on-click-action": {
              "name": "complete",
              "payload": { "telefon": "${form.telefon}" }
            }
          }
        ]
      }
    }
  ]
}

Ein echter Flow hat meist mehrere Bildschirme, Auswahlfelder und eine Einwilligung. Das Prinzip bleibt gleich: Jeder Bildschirm ist ein Eintrag in screens, und jede Schaltfläche trägt eine Aktion.

Versionen und Grenzen

Meta entwickelt das Format laufend weiter, neue Komponenten kommen mit neuen Versionen. Foto- und Dokument-Upload gibt es zum Beispiel ab Version 4.0, formatierten Text ab Version 5.1. Ältere Versionen friert Meta irgendwann ein: Flows darauf lassen sich nicht mehr veröffentlichen oder ändern, aber weiter senden. Läuft eine Version aus, können Kunden Flows darauf nicht mehr öffnen.

Dazu kommen feste Grenzen. Eine Flow-JSON-Datei darf höchstens 10 MB groß sein, ein Routing-Modell hat höchstens 10 Verzweigungen, und pro Bildschirm gelten Obergrenzen, etwa 50 Komponenten und eine Fußzeile mit der Schaltfläche.

Flow JSON, Builder und Nachricht

• Flow JSON beschreibt das Formular selbst, also Aufbau und Logik.
• Ein visueller Builder erzeugt dieses JSON, damit niemand es von Hand schreiben muss.
• Die Nachricht, mit der ein Flow verschickt wird, ist etwas anderes: eine interaktive Nachricht oder eine Vorlage mit Flow-Schaltfläche, die nur auf den veröffentlichten Flow verweist.

Nicht zu verwechseln ist Flow JSON außerdem mit den Abläufen in einem Flow-Builder für Automatisierungen. Die beschreiben Schritte im Hintergrund, nicht ein Formular im Chat.

Warum Flow JSON wichtig ist

• Grenzen kennen: Wer weiß, was das Format erlaubt, plant keine Formulare, die Meta später nicht annimmt.
• Fehlersuche: Lehnt Meta einen Flow ab, liegt der Grund oft im JSON, etwa eine Komponente, die die gewählte Version noch nicht kennt.
• Versionen im Blick: Friert Meta eine Version ein, müssen Flows darauf vor der nächsten Änderung auf eine neuere Version.

Flow JSON in SendSeven

Im Builder für WhatsApp Flows von SendSeven (Beta) schreiben Sie kein Flow JSON von Hand. Sie bauen den Flow im visuellen Editor, und SendSeven erzeugt daraus Flow JSON in Version 7.3, die Meta derzeit empfiehlt. Der Tab „JSON“ zeigt zwei Fassungen: das Builder-JSON, das Sie bearbeiten können, und das daraus erzeugte WhatsApp-JSON, das nur zum Lesen dient. Auch die API nimmt das Builder-JSON entgegen.

Fertiges Flow JSON aus anderen Quellen fügen Sie nicht direkt ein. Flows, die Sie in Metas eigenem Builder erstellt haben, übernehmen Sie per Import. Ob ein Flow einen Daten-Endpunkt braucht, legen Sie im Builder fest: statische Flows gibt es ab dem Basic-Tarif, dynamische ab dem Scale-Tarif.

WhatsApp Flows ist in der Beta. Was ein gesendeter und ein abgeschlossener Flow kostet, lesen Sie im Eintrag WhatsApp Flows.

DSGVO-konform, EU-gehostet, deutschsprachiger Support. 14 Tage kostenlos testen.