Формы
Формы подписки, люди, которые их заполняют, и их показатели.
Инструменты форм
| Инструмент | Что делает |
|---|---|
| listForms | Формы подписки рабочего пространства, сначала недавно изменённые, с их статусом, подписками и просмотрами. |
| getForm | Одна форма целиком: её поля, тексты, аудитории, двойное подтверждение и уведомления. У опубликованной формы добавляются её ссылка, код для встраивания и адрес, на который отправляет данные обычная HTML-форма, а includeDesign возвращает черновик в виде JSON. |
| listFormStarters | Заготовки, с которых может начинаться новая форма, с полями, которые запрашивает каждая из них. |
| createForm | Создать форму из заготовки, из дизайна, написанного как document, или из заготовки с изменениями поверх неё, с любыми настройками. Форма остаётся черновиком, если publish не равен true. |
| updateForm | Изменить название и настройки формы, которые применяются сразу, или дизайн её черновика через document. Тексты и оформление объединяются ключ за ключом, а fields заменяет весь список. |
| publishForm | Сделать текущий черновик тем, что видят посетители, чтобы форма принимала подписки. |
| setFormStatus | Приостановить опубликованную форму или снова открыть её. |
| duplicateForm | Скопировать форму в новый черновик без её подписок. |
| deleteForm | Удалить форму и её подписки навсегда. Её ссылка и встроенные формы перестают работать, а люди, которых она добавила, остаются в ваших контактах. |
| getFormAnalytics | Просмотры, подписки, добавленные и всё ещё ожидающие люди и коэффициент конверсии за период, в целом и по минутам, часам или дням. Просмотры хранятся по часам. |
| listFormSubmissions | Люди, которые заполнили форму, от новых к старым, с их ответами и статусом, по одной странице за раз. Поиск по адресу электронной почты и фильтр по статусу. |
| getFormSubmission | Одна подписка целиком: каждый ответ, её статус, когда она пришла и когда человека добавили, страница, с которой она пришла, и её аудитории. |
| approveFormSubmission | Добавить подписку, которая ждёт подтверждения, без письма с подтверждением. Нужен также contacts:write. |
| resendFormConfirmation | Отправить по всё ещё ожидающей подписке письмо с новой ссылкой для подтверждения. Ничего не отправляется, если эта форма уже отправляла письмо на этот адрес за последние десять минут или если на этот адрес за последние сутки ушло уже пять писем из этого рабочего пространства. Нужен также emails:send. |
| removeFormSubmissions | Удалить до 200 подписок формы по id. Контакты и аудитории остаются как есть. |
Для чтения нужен forms:read, а для любого изменения нужен forms:write. Для всего, что заставляет форму отправлять почту, нужен также emails:send: для включения двойного подтверждения, задания отправителя или письма с подтверждением, публикации или открытия формы с двойным подтверждением и повторной отправки подтверждения. Клиент, действующий от имени участника, видит только формы, созданные этим участником, а клиент, ограниченный некоторыми адресами, может отправлять подтверждения только с тех адресов, к которым у него есть доступ, и уведомлять только такие адреса.
Дизайн формы по письменному описанию создаётся в чате приложения. Через MCP дизайнером выступает клиент: передайте поля, тексты и оформление как document в createForm или updateForm, а инструменты приведут дизайн в порядок и сообщат, что изменили.
Семь инструментов этого сервера вносят изменение, которое REST API защищает кодом подтверждения, и спрашивают тот же код: createRule, setRuleEnabled, removeDomain, removeDomainAddress, removeAppHost, deleteForm и deleteAudience для созданной вами аудитории. Пока клиент не подтвердил код за последние 60 минут и человек не выбрал для него «Разрешить изменения на 60 минут» в разделе «Аккаунт → Подключённые приложения», такой инструмент отвечает результатом, который начинается с Refused (step_up_required):, и ничего не меняет. emptyAudience никогда не спрашивает код. Страница «Аутентификация» в API показывает, как запросить код и подтвердить его.
Инструменты применяют те же правила и отказы, что и REST API, а страницы /forms справочника API описывают каждое поле. listForms сортирует по последнему изменению, а createForm и updateForm приводят в порядок частичный document, тогда как API принимает его только целиком.
