Из чего состоит файл WhatsApp Flow JSON
В Flow JSON два обязательных свойства: version и screens. У каждого экрана есть id, необязательный title, который отображается в верхней панели, и макет типа SingleColumnLayout, дочерние элементы которого — компоненты: текст, поля ввода, списки выбора, выбор даты, opt-in и одна кнопка Footer.
Навигация задаётся в действиях. Footer с navigate открывает следующий экран. На последнем экране, помеченном как terminal, Footer с complete закрывает Flow и отправляет данные вашей компании вместе с flow token. Начиная с Flow JSON 4.0 любой экран может читать поля предыдущего экрана через ${screen.SCREEN_ID.form.field}, поэтому в шаблонах payload в navigate остаётся пустым, а все ответы собираются в итоговом payload действия complete.
- version: версия Flow JSON, во всех шаблонах это "7.3".
- screens: упорядоченный список экранов; первый экран без входящего маршрута считается стартовым.
- routing_model и data_api_version: нужны только Flow, которые обращаются к вашему эндпоинту данных.
- terminal и success: отмечают последний экран и то, считается ли завершение на нём успешным.
Flow с эндпоинтом данных и без него
Все двенадцать шаблонов работают без эндпоинта. Им не нужен сервер: варианты ответов записаны прямо в JSON, Meta сама формирует модель маршрутизации, а ответы вы получаете на вебхук, когда клиент завершает Flow. Meta рекомендует Flow без эндпоинта во всех случаях, когда не нужны актуальные данные: такие Flow открываются быстрее и создаются быстрее.
Добавляйте эндпоинт данных, если экран зависит от актуальных данных: свободных слотов для записи, меняющейся цены, остатков на складе или проверки по аккаунту клиента. Тогда экраны используют data_exchange, Flow требует data_api_version и routing_model, а ваш эндпоинт должен расшифровывать каждый запрос и отвечать в пределах тайм-аута Meta. Эту часть мы разрабатываем и размещаем для клиентов.
Лимиты символов и правила компонентов, которые нужно соблюдать
Большинство отклонённых Flow не проходят из-за мелких правил. Подписи короткие: 20 символов для текстового поля, текстовой области или выпадающего списка, 30 для группы радиокнопок или флажков, 40 для выбора даты и 35 для кнопки Footer. Названия вариантов ограничены 30 символами, описания — 300. Заголовки могут занимать 80 символов, основной текст — 4 096.
На одном экране можно использовать до 50 компонентов, один Footer, две встроенные ссылки, три изображения и пять opt-in. Id экрана может содержать только буквы и подчёркивания, а SUCCESS зарезервирован. В арабских подписях считаются символы, а не байты, поэтому арабская подпись из 20 символов допустима. Валидатор проверяет все эти правила и указывает, какой экран нужно исправить.
Арабские Flow и RTL для клиентов в странах Персидского залива (GCC)
У каждого шаблона есть версия на арабском языке с теми же экранами и названиями полей, поэтому код вашего вебхука обрабатывает оба языка без изменений. На телефоне клиента WhatsApp выводит арабские Flow справа налево; предпросмотр показывает то же направление.
В библиотеке есть сценарии, важные для стран Персидского залива: регистрация на предложения к Рамадану и Ид со временем отправки сообщения после ифтара, бронирование столика в ресторане, запросы на просмотр недвижимости и чек-лист документов KYC, в котором клиентов просят не присылать фото удостоверений личности в чат.
Как отправить Flow клиентам
После публикации Flow отправьте его как интерактивное сообщение flow, указав Flow ID, сгенерированный вами flow token, короткий текст кнопки и первый экран. Для каждого шаблона библиотека даёт payload сообщения. Интерактивные сообщения работают только в течение 24-часового окна обслуживания клиента; чтобы написать клиентам первыми, прикрепите Flow к одобренному шаблону сообщения с кнопкой Flow.
Когда клиент завершает Flow, WhatsApp показывает ему сводку ответов, а вы получаете полный payload на свой вебхук. Ответьте сообщением с подтверждением, где сказано, что будет дальше и как изменить или отменить запись.
