Flow JSON

Flow JSON es el formato con el que Meta describe un WhatsApp Flow: qué pantallas tiene, qué campos y textos aparecen en ellas y qué hace cada botón. WhatsApp lee esta descripción y muestra el formulario dentro del chat.

¿Qué es Flow JSON?

Detrás de cada WhatsApp Flow hay una descripción en formato JSON, el Flow JSON. Define qué pantallas tiene el flow, qué componentes hay en ellas y qué ocurre al tocar un botón: pasar a la siguiente pantalla, enviar datos a un servidor o completar el flow. Entre los componentes hay títulos, textos, campos de entrada, listas de selección, un selector de fecha, casillas de opt-in y la subida de fotos o documentos.

Las partes principales del nivel superior:

  • version: la versión del formato. Determina qué componentes están disponibles.
  • screens: la lista de pantallas y sus componentes.
  • routing_model: los caminos permitidos entre pantallas. Obligatorio en los flows con endpoint de datos.
  • data_api_version: la versión de la API de datos, también solo para flows con endpoint.

Ejemplo: un flow de una sola pantalla

Este Flow JSON describe una solicitud de llamada. Una pantalla con un campo obligatorio para el número de teléfono; el botón del pie completa el flow y devuelve el dato introducido:

{
  "version": "7.3",
  "screens": [
    {
      "id": "LLAMADA",
      "title": "Te llamamos",
      "terminal": true,
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextInput",
            "name": "telefono",
            "label": "Número de teléfono",
            "input-type": "phone",
            "required": true
          },
          {
            "type": "Footer",
            "label": "Enviar",
            "on-click-action": {
              "name": "complete",
              "payload": { "telefono": "${form.telefono}" }
            }
          }
        ]
      }
    }
  ]
}

Un flow real suele tener varias pantallas, campos de selección y una casilla de consentimiento. El principio es el mismo: cada pantalla es una entrada en screens y cada botón lleva una acción.

Versiones y límites

Meta sigue desarrollando el formato, y los nuevos componentes llegan con nuevas versiones. La subida de fotos y documentos, por ejemplo, requiere la versión 4.0 o posterior; el texto enriquecido, la 5.1. Las versiones antiguas acaban congelándose: los flows que las usan ya no se pueden publicar ni actualizar, aunque todavía se pueden enviar. Cuando una versión caduca, los clientes ya no pueden abrir los flows creados con ella.

También hay límites fijos. Un archivo Flow JSON puede ocupar como máximo 10 MB, un modelo de enrutamiento tiene como máximo 10 ramas, y cada pantalla tiene topes, como 50 componentes y un único pie con el botón.

Flow JSON, constructores y mensajes

  • Flow JSON describe el formulario en sí, su estructura y su lógica.
  • Un constructor visual genera ese JSON para que nadie tenga que escribirlo a mano.
  • El mensaje que entrega un flow es otra cosa: un mensaje interactivo o una plantilla con botón de Flow que solo apunta al flow publicado.

Flow JSON tampoco es lo mismo que las automatizaciones de un flow builder. Estas describen pasos que se ejecutan en segundo plano, no un formulario dentro del chat.

Por qué importa Flow JSON

  • Conocer los límites: si sabes lo que permite el formato, no planificarás formularios que Meta rechace después.
  • Resolución de problemas: cuando Meta rechaza un flow, el motivo suele estar en el JSON, por ejemplo un componente que la versión elegida todavía no admite.
  • Vigilar las versiones: cuando Meta congela una versión, los flows que la usan necesitan una versión más reciente antes de su próximo cambio.

Flow JSON en SendSeven

En el constructor de WhatsApp Flows de SendSeven (beta) no escribes Flow JSON a mano. Creas el flow en un editor visual y SendSeven genera Flow JSON en la versión 7.3, la que Meta recomienda actualmente. La pestaña JSON muestra dos versiones: el Builder JSON, que puedes editar, y el WhatsApp JSON generado a partir de él, de solo lectura. La API también acepta el Builder JSON.

No pegas Flow JSON ya hecho de otras fuentes. Los flows que creaste en el constructor de Meta se pueden importar. Si un flow necesita un endpoint de datos se define en el constructor: los flows estáticos están disponibles desde el plan Basic y los dinámicos, desde el plan Scale.

WhatsApp Flows está en beta. Lo que cuestan un flow enviado y un flow completado se explica en la entrada WhatsApp Flows.

Conforme al RGPD, alojado en la UE. Prueba gratuita de 14 días.