Принимайте заявки с формы

Скажите, что хотите собирать: имя, адрес почты, сообщение, галочку согласия на ответ. Агент объявляет такую форму на проекте, и с этого момента Birta знает, какие поля может нести заявка.

У каждого поля есть короткий идентификатор и, если нужно, подпись. По идентификатору сверяется заявка, а подпись видите только вы в панели. Текст, который читает посетитель, живёт на странице — его можно менять когда угодно, не трогая форму.

Birta не даёт готового блока формы и не диктует, как она выглядит: агент пишет разметку в дизайне вашего сайта и код, который отправляет заявку. Строка «спасибо» и любой текст ошибки — тоже ваши: Birta сообщает агенту, какое правило нарушила заявка, а агент превращает это в формулировку вашего сайта.

В страницу не попадает ничего секретного: отправка публичная и адресуется относительно самого сайта. Переименование проекта или подключение своего домена оставляют форму работающей без правок.

Форма начинает принимать заявки, как только у проекта есть и объявленная форма, и опубликованный сайт. Объявить форму можно и до публикации, и после — а изменение формы повторной публикации не требует.

Проверяйте на опубликованном сайте: предпросмотр версии заявок не принимает, и это намеренно — заявка принадлежит живому сайту, а не черновику.

Каждая принятая заявка появляется в разделе «Формы» проекта — с полями точно в том виде, в каком она пришла. Позднее изменение формы никогда не перепишет уже полученную заявку. Агент тоже умеет их читать, так что можно попросить его собрать сводку.

Эту часть читать не обязательно — она здесь, чтобы видеть: скрытой настройки нет. Каждый раз, когда агент объявляет, меняет или читает форму, он получает контракт целиком: правило на каждое поле, куда уходит заявка, что считается принятым, все основания отказа и как часто форму можно отправлять. Числа ниже — те, которые действительно применяет этот экземпляр Birta.

Form contact ("Talk to us") — 5 fields
1. name ("Name") — short text, required
   JSON string, at most 500 characters. Refused as missing_field, invalid_value, value_too_long.
2. email ("Email") — email, required
   JSON string, matching /^[^\s@]+@[^\s@]+\.[^\s@]+$/, at most 254 characters. Refused as missing_field, invalid_value, value_too_long.
3. topic ("What is it about?") — single choice, optional
   JSON string, one of: demo ("Product demo"), pricing ("Pricing"), support ("Support"). Matched exactly against the declared values, not against what the page displays. Refused as invalid_value, not_an_option.
4. message ("Message") — long text, optional
   JSON string, at most 5000 characters. Refused as invalid_value, value_too_long.
5. consent ("May we reply to you?") — consent, required
   JSON boolean, which has to be true — a required consent counts only as given. Refused as missing_field, invalid_value, consent_not_given.

Submit: POST /_forms/contact on the site's own host — the standard address or a connected domain, whichever the visitor is on. Intake is public: no key, token, project id or absolute address belongs in the markup.
Body: content-type application/json, a JSON object of these field keys and nothing else. An absent key, null, "" and [] all mean not filled in: a required field is refused, an optional one is simply left out of the lead. A submission is at most 65536 bytes. The page's own script sends it — a browser's native form submit posts form-encoded fields and is refused as invalid_body.
Answers: 201 {"status":"accepted"}. A refusal is 400 (invalid_body, unknown_field, missing_field, invalid_value, not_an_option, value_too_long, value_out_of_range, value_too_precise, too_many_values, consent_not_given), 403 (preview_not_accepted), 404 (no_such_form), 413 (payload_too_large), 429 (too_many_submissions, project_busy), carrying {"error","code","field"} — branch on "code", never on the sentence.
Limits: a visitor may send 5 submissions in 10 minutes (too_many_submissions), and the site takes 200 leads in an hour (project_busy). Every attempt spends the visitor's budget, refused ones included: resending a broken submission until it works runs into the limit.
Live only: a version preview refuses every submission as preview_not_accepted — test intake on the published site. A declared form accepts as soon as the project has a published site; declaring or changing a form needs no re-publish.
Keys: the form key and the field keys above are the contract, matched exactly. The text a visitor reads is yours to choose — renaming a label on the page changes nothing here.