Flow JSON

O Flow JSON é o formato que a Meta usa para descrever um WhatsApp Flow: que ecrãs tem, que campos e textos aparecem neles e o que faz cada botão. O WhatsApp lê esta descrição e apresenta o formulário dentro do chat.

O que é o Flow JSON?

Por trás de cada WhatsApp Flow está uma descrição em formato JSON, o Flow JSON. Define que ecrãs o flow tem, que componentes existem em cada um e o que acontece quando se toca num botão: avançar para o ecrã seguinte, enviar dados para um servidor ou concluir o flow. Os componentes incluem títulos, texto, campos de introdução, listas de seleção, um seletor de data, caixas de opt-in e carregamento de fotografias ou documentos.

As principais partes de nível superior:

• version: a versão do formato. Determina que componentes estão disponíveis.
• screens: a lista de ecrãs e respetivos componentes.
• routing_model: os caminhos permitidos entre ecrãs. Obrigatório em flows com endpoint de dados.
• data_api_version: a versão da API de dados, também apenas para flows com endpoint.

Exemplo: um flow com um só ecrã

Este Flow JSON descreve um pedido de contacto telefónico. Um ecrã com um campo obrigatório para o número de telefone; o botão do rodapé conclui o flow e devolve o valor introduzido:

{
  "version": "7.3",
  "screens": [
    {
      "id": "CONTACTO",
      "title": "Pedido de contacto",
      "terminal": true,
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextInput",
            "name": "telefone",
            "label": "Número de telefone",
            "input-type": "phone",
            "required": true
          },
          {
            "type": "Footer",
            "label": "Enviar",
            "on-click-action": {
              "name": "complete",
              "payload": { "telefone": "${form.telefone}" }
            }
          }
        ]
      }
    }
  ]
}

Um flow real tem normalmente vários ecrãs, campos de escolha e uma caixa de consentimento. O princípio mantém-se: cada ecrã é uma entrada em screens, e cada botão tem uma ação associada.

Versões e limites

A Meta continua a desenvolver o formato, e os novos componentes chegam com novas versões. O carregamento de fotografias e documentos, por exemplo, exige a versão 4.0 ou superior; o texto formatado, a 5.1. As versões antigas acabam por ser congeladas: os flows que as usam deixam de poder ser publicados ou atualizados, mas ainda podem ser enviados. Quando uma versão expira, os clientes deixam de conseguir abrir os flows criados com ela.

Há também limites fixos. Um ficheiro Flow JSON pode ter no máximo 10 MB, um modelo de encaminhamento tem no máximo 10 ramificações, e cada ecrã tem limites, como 50 componentes e um único rodapé com o botão.

Flow JSON, construtores e mensagens

• O Flow JSON descreve o próprio formulário, a sua estrutura e a sua lógica.
• Um construtor visual gera esse JSON para que ninguém o tenha de escrever à mão.
• A mensagem que entrega um flow é outra coisa: uma mensagem interativa ou um modelo com botão de Flow que apenas aponta para o flow publicado.

O Flow JSON também não é o mesmo que as automações de um flow builder. Essas descrevem passos que correm em segundo plano, não um formulário dentro do chat.

Porque é que o Flow JSON importa

• Conhecer os limites: se souber o que o formato permite, não planeia formulários que a Meta depois rejeita.
• Resolução de problemas: quando a Meta rejeita um flow, o motivo está muitas vezes no JSON, por exemplo um componente que a versão escolhida ainda não suporta.
• Acompanhar as versões: quando a Meta congela uma versão, os flows que a usam precisam de uma versão mais recente antes da próxima alteração.

O Flow JSON na SendSeven

No construtor de WhatsApp Flows da SendSeven (Beta) não escreve Flow JSON à mão. Cria o flow num editor visual e a SendSeven gera Flow JSON na versão 7.3, a versão que a Meta recomenda atualmente. O separador JSON mostra duas versões: o Builder JSON, que pode editar, e o WhatsApp JSON gerado a partir dele, só de leitura. A API também aceita o Builder JSON.

Não cola Flow JSON já pronto de outras fontes. Os flows que criou no construtor da Meta podem ser importados. É no construtor que define se um flow precisa de um endpoint de dados: os flows estáticos estão disponíveis a partir do plano Basic, os dinâmicos a partir do plano Scale.

Os WhatsApp Flows estão em Beta. O custo de um flow enviado e de um flow concluído é explicado na entrada WhatsApp Flows.

Em conformidade com o RGPD, alojado na UE. Teste 14 dias gratuitamente.