Flow JSON

Flow JSON è il formato con cui Meta descrive un WhatsApp Flow: quali schermate contiene, quali campi e testi vi compaiono e cosa fa ogni pulsante. WhatsApp legge questa descrizione e mostra il modulo dentro la chat.

Cos'è il Flow JSON?

Dietro ogni WhatsApp Flow c'è una descrizione in formato JSON, il Flow JSON. Definisce quali schermate ha il flow, quali componenti contengono e cosa succede quando si tocca un pulsante: passare alla schermata successiva, inviare dati a un server o completare il flow. Tra i componenti ci sono titoli, testi, campi di inserimento, liste di selezione, un selettore di data, caselle di opt-in e il caricamento di foto o documenti.

Le parti principali di primo livello:

• version: la versione del formato. Determina quali componenti sono disponibili.
• screens: l'elenco delle schermate e dei loro componenti.
• routing_model: i percorsi consentiti tra le schermate. Obbligatorio per i flow con endpoint di dati.
• data_api_version: la versione della Data API, anche questa solo per i flow con endpoint.

Esempio: un flow con una sola schermata

Questo Flow JSON descrive una richiesta di richiamata. Una schermata con un campo obbligatorio per il numero di telefono; il pulsante nel footer completa il flow e restituisce il dato inserito:

{
  "version": "7.3",
  "screens": [
    {
      "id": "RICHIAMATA",
      "title": "Richiamata",
      "terminal": true,
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextInput",
            "name": "telefono",
            "label": "Numero di telefono",
            "input-type": "phone",
            "required": true
          },
          {
            "type": "Footer",
            "label": "Invia",
            "on-click-action": {
              "name": "complete",
              "payload": { "telefono": "${form.telefono}" }
            }
          }
        ]
      }
    }
  ]
}

Un flow reale di solito ha più schermate, campi di scelta e una casella per il consenso. Il principio resta lo stesso: ogni schermata è una voce in screens e ogni pulsante porta con sé un'azione.

Versioni e limiti

Meta continua a sviluppare il formato, e i nuovi componenti arrivano con le nuove versioni. Il caricamento di foto e documenti, ad esempio, richiede la versione 4.0 o successiva, il rich text la 5.1. Le versioni più vecchie a un certo punto vengono congelate: i flow che le usano non si possono più pubblicare né aggiornare, ma si possono ancora inviare. Quando una versione scade, i clienti non riescono più ad aprire i flow costruiti su di essa.

Ci sono anche limiti fissi. Un file Flow JSON può pesare al massimo 10 MB, un modello di routing ha al massimo 10 rami, e ogni schermata ha dei tetti, come 50 componenti e un solo footer con il pulsante.

Flow JSON, builder e messaggi

• Il Flow JSON descrive il modulo vero e proprio, la sua struttura e la sua logica.
• Un builder visuale genera quel JSON, così nessuno deve scriverlo a mano.
• Il messaggio che consegna un flow è un'altra cosa: un messaggio interattivo o un template con pulsante Flow che rimanda soltanto al flow pubblicato.

Il Flow JSON non è nemmeno la stessa cosa delle automazioni di un flow builder. Quelle descrivono passaggi eseguiti in background, non un modulo dentro la chat.

Perché il Flow JSON è importante

• Conoscere i limiti: se sai cosa consente il formato, non progetti moduli che Meta poi rifiuta.
• Risoluzione dei problemi: quando Meta rifiuta un flow, il motivo spesso è nel JSON, ad esempio un componente che la versione scelta non supporta ancora.
• Tenere d'occhio le versioni: quando Meta congela una versione, i flow che la usano devono passare a una versione più recente prima della modifica successiva.

Il Flow JSON in SendSeven

Nel builder per WhatsApp Flows di SendSeven (beta) non scrivi il Flow JSON a mano. Costruisci il flow in un editor visuale e SendSeven genera il Flow JSON nella versione 7.3, quella che Meta raccomanda attualmente. La scheda JSON mostra due versioni: il Builder JSON, che puoi modificare, e il WhatsApp JSON generato a partire da esso, in sola lettura. Anche l'API accetta il Builder JSON.

Non incolli Flow JSON già pronti da altre fonti. I flow che hai creato nel builder di Meta si possono importare. Se un flow ha bisogno di un endpoint di dati lo decidi nel builder: i flow statici sono disponibili dal piano Basic, quelli dinamici dal piano Scale.

WhatsApp Flows è in beta. Quanto costano un flow inviato e un flow completato è spiegato nella voce WhatsApp Flows.

Conforme al GDPR, ospitato nell'UE. 14 giorni di prova gratuita.