Forms в TelePost

Forms в TGPT — небольшой модуль для публичных заявок. Он нужен в момент, когда у владельца ящика появляется внешняя точка контакта: страница, лендинг или простая форма обратной связи, откуда данные должны попасть в TelePost и сразу дать сигнал в Telegram.

Идея модуля простая: не собирать отдельную систему для каждой формы, а дать внешнему сайту понятный endpoint. У формы есть публичный hash_id, сайт отправляет payload на endpoint формы, TelePost сохраняет сабмит и уведомляет владельца. При необходимости после успешной отправки можно сделать redirect или отправить внешний POST на subscription_url.

Что решает Forms

Forms закрывает практичную задачу: принять сообщение с публичной страницы и сразу связать его с владельцем в TelePost. Это превращает форму не в отдельный разрозненный виджет, а в ещё один вход в общий рабочий поток рядом с письмами.

Это полезно для простых сценариев:

• заявка с лендинга;
• короткая форма обратной связи;
• сбор контакта и сообщения;
• передача данных во внешний endpoint после сабмита;
• уведомление владельца в Telegram без ручной проверки админки.

Важно: текущая документация фиксирует работу с обычным payload и отдельно отмечает ограничения. Я не описываю здесь поддержку multipart/form-data, потому что она не подтверждена текущей спецификацией.

Как работает публичный сабмит

Публичный путь формы выглядит как /api/v1/f/:hash_id. Когда внешний сайт отправляет сабмит, backend не просто принимает данные вслепую, а последовательно проверяет форму и запрос:

1. находит форму по hash_id;
2. проверяет, что форма активна;
3. проверяет Origin по списку разрешённых источников;
4. проверяет content-type и размер payload;
5. валидирует тело запроса;
6. сохраняет payload в базу;
7. отправляет Telegram-уведомление владельцу;
8. запускает внешний POST на subscription_url, если он задан;
9. делает redirect, если у формы есть redirect_url.

Такой flow оставляет публичный endpoint достаточно понятным для внешней страницы и достаточно контролируемым для TelePost: форма принимает данные, сохраняет их и возвращает предсказуемый результат.

Управление формами в Mini App

В TelePost есть UI-менеджер форм внутри Mini App. Через него владелец управляет тем, как форма выглядит для системы: задаёт название, разрешённые origin, redirect URL, subscription URL и активность формы.

Отдельно хранится список сабмитов. Это важно, потому что Telegram-уведомление помогает быстро заметить новую заявку, но не должно быть единственным местом, где она существует. Владелец может вернуться к полученным сабмитам в Mini App и спокойно посмотреть детали.

Telegram-уведомление владельцу

После успешного сабмита TelePost отправляет владельцу формы уведомление в Telegram. В уведомлении показываются основные поля payload — обычно первые полезные поля, чтобы быстро понять, что пришло и требует ли заявка реакции.

Так Forms поддерживает общую идею проекта: Telegram остаётся точкой быстрых событий, а Mini App — местом, где можно открыть детали и продолжить работу.

Зачем это полезно

Forms добавляет к почтовому сервису ещё один входной канал. Письма приходят через Mox, а заявки и обращения с внешних страниц — через публичный endpoint формы. В обоих случаях владелец видит событие в Telegram и может дальше обработать его в TelePost.

В будущем такой входной поток можно связать с автоматизацией: например, превращать часть заявок или писем в рабочие действия. Об этом подробнее — в статье TelePost и Audio Scribe: будущая интеграция.