Обработка форм

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

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

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

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

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

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

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

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

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

{    "type": "view",    "event": "submit",    "private_metadata": "{'timeoff_id':4378}",    "callback_id": "timeoff_reguest_form",    "user_id": 1235523,    "data": {        "date_start": "2025-07-01",        "date_end": "2025-07-14",        "request_doc": [            {                "name": "request.png",                "size": 19153,                "url": "<url>"            }        ],        "accessibility": "phone_only",        "info": "Поеду в сибирь на свадьбу лучшего друга",        "newsletters": ["new_tasks", "project_updates"],        "team": "success",        "time": "22:00"    },    "webhook_timestamp": 1755075544}

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

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

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

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

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

HTTP/1.1 400 Bad RequestServer: nginx/1.14.2Date: Wed, 22 Apr 2025 12:32:29 GMTContent-Type: application/json; charset=utf-8Transfer-Encoding: chunkedConnection: closeETag: W/"4d63aae1430a3bbd35e95e3db6b364df"Cache-Control: max-age=0, private, must-revalidateX-Request-Id: 12f8a05c-c5cf-4a79-8d2f-f82cc477c410X-Runtime: 0.117503Vary: OriginX-Rack-CORS: miss; no-origin {    "errors": {        "date_end": "Дата окончания отпуска не может быть меньше даты начала",        "request_doc": "В заявлении не найдена электронная подпись"    }}

Пример отображения ошибок в интерфейсе представления

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

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

HTTP/1.1 200 OKServer: nginx/1.14.2Date: Wed, 22 Apr 2025 12:32:29 GMTContent-Type: text/plain; charset=utf-8