Формы

Формы в Пачке позволяют вам отображать пользователям представления с указанным вами набором полей. Представления отображаются в виде модального окна, а результат заполнения формы вы можетет получить на свой сервер.

На текущий момент вызов модального окна с представлением возможен только через кнопки в сообщении бота.

Модальное окно

Модальное окно состоит из стандартных элементов - заголовка, кнопки закрытия (отмены), набора полей (подзаголовки, текст, ввод текста, выбор, списки и тд.) и кнопки отправки.

Жизненный цикл модального окна

Всё начинается с нажатия пользователем Data-кнопки кнопки в сообщении.

• В результате нажатия кнопки вашему приложению отправляется исходящий вебхук с уникальным trigger_id;
• Затем приложение фомирует представление и отправляет его, а пользователю отображается модальное окно;
• Далее пользователь заполняет поля и вашему приложению отправляется исходящий вебхук с данными заполненных пользователем полей в представлении;
• В ответе на вебхук ваше приложение может отправить список ошибок, которые необходимо отобразить пользателю в представлении, или ответить кодом 200 (после чего модальное окно будет закрыто).

Блоки представления

Блоки - это компоненты представления, которые позволяют вам формировать необходимые поля ввода данных и отображать дополнительную пояснительную информацию. Они указываются в поле view.blocks при открытии представления. Вы можете добавить до 100 блоков в одно представление.

Заголовок (header)

Обычный текст (plain_text)

Форматированный текст (markdown)

В поле text вам необходимо прислать форматированный текст в синтаксисе markdown. Поддерживаются конструкции, указанные в таблице ниже.

Разделитель (divider)

Текстовое поле (input)

Выпадающий список (select)

Радиокнопки (radio)

Чекбоксы (checkbox)

Выбор даты (date)

Выбор времени (time)

Загрузка файлов (file_input)

Открытие представления

Чтобы открыть модальное окно с представлением, ваше приложение должно иметь действительный, неистекший trigger_id. Это требование связано с тем, чтобы приложение открывало модальное окно только с разрешения пользователя и делало это быстро.

Для открытия представления используйте метод Открытие представления.

Получение результатов

После заполнения пользователей полей в представлении и отправки их, в ваше приложение отправляется исходящий вебхук. Вебхук будет отправлен на Webhook URL, который вы указали в настройках бота во вкладке «Исходящий Webhook», от имени которого было отправлено сообщение с кнопкой (нажатие на которую и вызвало открытие представления).

Задача вашего приложения - обработать входяший вебхук в короткое время и дать ответ. Это может быть как успех и команда на закрытие представления пользователю в интерфейсе Пачки, так и набор ошибок, которые необходио отобразить пользователю в представлении.

Ваше приложение должно дать ответ на вебхук в течение 3 секунд. В ином случае, пользователь получит ошибку отправки в интерфейсе Пачки. Все значения полей будут сохранены и пользователь повторит попытку отправки формы. О том, как закрыть представление или отобразить ошибки по конкретным полям, вы можете прочитать в разделе Закрытие и отображение ошибок.

Вебхук содержит информацию, которая была заложена при открытии представления пользователю (такие поля, как private_metadata и callback_id), и данные заполненных полей представления.

Каждый исходящий вебхук защищён с помощью подписи, основанной на хешировании содержимого. Подробнее об этом, а также о других методах проверки подлинности исходящего вебхука, вы можете прочитать в блоке Безопасность.

Закрытие и отображение ошибок

После заполнения пользователем полей в представлении в приложение будет отправлен исходящий вебхук. В этот момент вы можете сохранить полученные значения или провести валидацию правильности заполнения полей и отправить пользователю ошибки.

Вам необходимо оперативно ответить на вебхук (кодом 200 или 400 со списком ошибок). В ином случае, пользователь получит ошибку отправки в интерфейсе Пачки. Все значения полей будут сохранены и пользователь повторит попытку отправки формы.

Закрытие представления

Если вы хотите просто закрыть пользователю представление (нет необходимости отображать ошибки), то ответ должен быть HTTP 200 OK. Никакое тело ответа не требуется.

Отображение ошибок

Если вы хотите отобразить пользователю ошибки заполнения конкретных полей представления, то ответ должен быть HTTP 400 Bad Request, а тело ответа содержать массив полей с указанием текста ошибки.