Forms в TelePost

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

Сценарий простой: у формы есть публичный 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 достаточно простым: форма принимает данные, сохраняет их и отдаёт предсказуемый результат внешней странице.

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

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

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

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

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

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

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

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

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