Flow JSON

Flow JSON est le format utilisé par Meta pour décrire un WhatsApp Flow : quels écrans il comporte, quels champs et textes y figurent et ce que fait chaque bouton. WhatsApp lit cette description et affiche le formulaire dans le chat.

Qu'est-ce que le Flow JSON ?

Derrière chaque WhatsApp Flow se trouve une description au format JSON, le Flow JSON. Elle définit les écrans du flow, les composants qu'ils contiennent et ce qui se passe quand on touche un bouton : passer à l'écran suivant, envoyer des données à un serveur ou terminer le flow. Parmi les composants figurent des titres, du texte, des champs de saisie, des listes de choix, un sélecteur de date, des cases d'opt-in et l'envoi de photos ou de documents.

Les principales parties de premier niveau :

• version : la version du format. Elle détermine les composants disponibles.
• screens : la liste des écrans et de leurs composants.
• routing_model : les chemins autorisés entre les écrans. Obligatoire pour les flows avec un endpoint de données.
• data_api_version : la version de l'API de données, elle aussi uniquement pour les flows avec endpoint.

Exemple : un flow d'un seul écran

Ce Flow JSON décrit une demande de rappel. Un seul écran avec un champ obligatoire pour le numéro de téléphone ; le bouton du pied de page termine le flow et renvoie la saisie :

{
  "version": "7.3",
  "screens": [
    {
      "id": "RAPPEL",
      "title": "Rappel",
      "terminal": true,
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextInput",
            "name": "telephone",
            "label": "Numéro de téléphone",
            "input-type": "phone",
            "required": true
          },
          {
            "type": "Footer",
            "label": "Envoyer",
            "on-click-action": {
              "name": "complete",
              "payload": { "telephone": "${form.telephone}" }
            }
          }
        ]
      }
    }
  ]
}

Un vrai flow comporte en général plusieurs écrans, des champs de choix et une case de consentement. Le principe reste le même : chaque écran est une entrée dans screens, et chaque bouton porte une action.

Versions et limites

Meta fait évoluer le format en permanence, et les nouveaux composants arrivent avec les nouvelles versions. L'envoi de photos et de documents, par exemple, nécessite la version 4.0 ou une version ultérieure, le texte enrichi la version 5.1. Les anciennes versions finissent par être gelées : les flows qui les utilisent ne peuvent plus être publiés ni modifiés, mais peuvent encore être envoyés. Une fois une version expirée, les clients ne peuvent plus ouvrir les flows construits dessus.

Il existe aussi des limites fixes. Un fichier Flow JSON peut peser au maximum 10 Mo, un modèle de routage compte au plus 10 branches, et chaque écran a ses plafonds, comme 50 composants et un seul pied de page avec le bouton.

Flow JSON, builders et messages

• Le Flow JSON décrit le formulaire lui-même, sa structure et sa logique.
• Un builder visuel génère ce JSON pour que personne n'ait à l'écrire à la main.
• Le message qui délivre un flow est autre chose : un message interactif ou un modèle avec un bouton Flow qui renvoie simplement vers le flow publié.

Le Flow JSON n'est pas non plus la même chose que les automatisations d'un flow builder. Celles-ci décrivent des étapes qui s'exécutent en arrière-plan, pas un formulaire dans le chat.

Pourquoi le Flow JSON compte

• Connaître les limites : si vous savez ce que le format permet, vous ne prévoyez pas de formulaires que Meta refusera ensuite.
• Diagnostic : quand Meta refuse un flow, la raison se trouve souvent dans le JSON, par exemple un composant que la version choisie ne prend pas encore en charge.
• Surveiller les versions : quand Meta gèle une version, les flows qui l'utilisent doivent passer à une version plus récente avant leur prochaine modification.

Le Flow JSON dans SendSeven

Dans le builder pour WhatsApp Flows de SendSeven (bêta), vous n'écrivez pas le Flow JSON à la main. Vous construisez le flow dans un éditeur visuel, et SendSeven génère un Flow JSON en version 7.3, la version actuellement recommandée par Meta. L'onglet JSON affiche deux versions : le Builder JSON, que vous pouvez modifier, et le WhatsApp JSON qui en est généré, en lecture seule. L'API accepte elle aussi le Builder JSON.

Vous ne collez pas de Flow JSON tout prêt provenant d'autres sources. Les flows que vous avez créés dans le builder de Meta peuvent être importés. C'est dans le builder que vous définissez si un flow a besoin d'un endpoint de données : les flows statiques sont disponibles dès le forfait Basic, les flows dynamiques à partir du forfait Scale.

WhatsApp Flows est en bêta. Le coût d'un flow envoyé et d'un flow terminé est expliqué dans la fiche WhatsApp Flows.

Conforme au RGPD, hébergé dans l'UE. 14 jours d'essai gratuit.