Docs
  1. Документация
  2. Виджет

Заявки: формы сайта прямо в CRM

Обновлено:

Форма обратной связи, которая шлёт письмо сотруднику в отпуске, — кладбище заявок. В Sitecog каждая форма вашего сайта превращается в карточку в CRM: с телефоном или почтой, состоянием и ответственным, который перезвонит. Хватит одного атрибута на <form>, а если нужно больше контроля — есть JavaScript и отправка с сервера.

Отправить заявку можно тремя способами — выбирайте подходящий:

  • Форма с data-crm-lead — ноль JavaScript. Виджет сам перехватывает отправку и делает остальное.
  • window.crmLead() — для React, Vue и любых форм, состоянием которых вы управляете сами.
  • POST /marketing/event с вашего сервера — заказы по телефону, формы на бэкенде, интеграции с другими системами.

Как заявка попадает из формы в CRM

У каждой формы заявок есть имя. Одна форма на сайте уже есть — встроенная lead_submit, «Заявка с сайта». Любая форма с пустым атрибутом data-crm-lead отправляет заявку в неё, и каждая отправка становится карточкой в CRM → Заявки — без единого шага в CRM. Встроенная форма появляется на сайтах, тариф которых включает заявки.

  1. Посетитель заполняет форму и жмёт «Отправить».
  2. Виджет собирает поля формы и отправляет их; где имя, телефон, почта и сообщение, разбирает сервер.
  3. Сервер проверяет, что такая форма есть, в заявке есть телефон или почта и она не похожа на бота.
  4. В CRM появляется карточка заявки, а если настроено — ещё и уведомление в Telegram.

Два правила, которые стоит запомнить сразу:

  • Незаведённое имя отклоняется. CRM принимает только формы, о которых знает, — опечатки не превращаются в мусор. Сама появляется только встроенная lead_submit.
  • Формы заявок и события аналитики не смешиваются. Заявка, отправленная на имя события аналитики, отклоняется, а crmTrack с именем формы заявок ничего не записывает. Каждый такой отказ CRM показывает в «Последних отказах».

Отдельные формы: заведите их в CRM

Встроенной формы хватает, пока заявки на сайте одного вида. Хотите отличать «Заказать звонок» от «Рассчитать стоимость» — в списке заявок, в фильтре и в счётчиках на странице «Формы»? Дайте каждой форме своё имя. Пара кликов, один раз на каждый вид формы:

  1. Откройте Заявки → Формы

    Кнопка «Формы» в шапке раздела «Заявки». Здесь все формы заявок сайта и сколько заявок пришло с каждой за последние 30 дней. Формы в архиве видны по галочке «Показывать архив».
  2. Нажмите «Новая форма»

    Дайте ей имя, которое будет в коде: латиница, цифры и подчёркивания, первой — буква: callback_request, quote_request. Имя потом не поменять — проверьте написание.
  3. По желанию: отметьте «Форма приносит деньги»

    Только тогда у заявки сохранятся сумма и валюта. Без этой отметки они тихо игнорируются.
  4. Поставьте имя на сайте

    data-crm-lead="callback_request" на форме, crmLead('callback_request', …) в коде или "name": "callback_request" в запросе с сервера. Готовый код для всех трёх способов CRM показывает на странице формы.

Способ A: форма с одним атрибутом

Добавьте атрибут data-crm-lead любой форме на странице, где подключён скрипт виджета. Это вся интеграция. Пустой атрибут отправляет заявку во встроенную форму lead_submit, значение — в вашу форму с этим именем (data-crm-lead="quote_request"). Формы, которые появляются позже — в модальном окне, после перехода в одностраничном приложении, — подхватываются автоматически, если вставлены в страницу уже с атрибутом.

Минимум: встроенная форма, ничего заводить не нужноhtml
<form data-crm-lead>
  <input name="name">
  <input name="phone" type="tel">
  <textarea name="message"></textarea>
  <button type="submit">Отправить</button>
</form>

Полный пример

Форма «Запросить расчёт» (quote_request заведена в «Заявки → Формы» с отметкой «Форма приносит деньги»): имя, телефон, почта и сообщение, сумма заказа (итог по форме виден на её карточке в «Заявки → Формы»), «спасибо» после отправки и своя проверка. Сначала чистый HTML; версии для React и Vue вызывают crmLead() из собственного обработчика отправки.

<form id="quote" data-crm-lead="quote_request" data-crm-value="149900" data-crm-currency="EUR">
  <label>Ваше имя <input name="name" autocomplete="name" required></label>
  <label>Телефон <input name="phone" type="tel" autocomplete="tel"></label>
  <label>Почта <input name="email" type="email" autocomplete="email"></label>
  <label>Что нужно сделать? <textarea name="message" rows="4"></textarea></label>

  <!-- Не из списка известных полей: попадёт в карточку заявки как есть -->
  <label>Размер команды
    <select name="team_size">
      <option>1–5</option>
      <option>6–20</option>
      <option>20+</option>
    </select>
  </label>

  <button type="submit">Отправить</button>
  <p class="form-status" role="status" hidden></p>
</form>

<script>
  const form = document.getElementById('quote');
  const status = form.querySelector('.form-status');
  const button = form.querySelector('button');

  function say(text) {
    status.textContent = text;
    status.hidden = false;
  }

  // 1. Перед отправкой: своя проверка. preventDefault() = ничего не уйдёт
  form.addEventListener('crm:lead-before', (event) => {
    const phone = form.elements.phone.value.trim();
    const email = form.elements.email.value.trim();
    if (!phone && !email) {
      event.preventDefault();
      say('Оставьте телефон или почту, чтобы мы могли ответить.');
      return;
    }
    button.disabled = true;
  });

  // 2. После отправки: виджет ничего не показывает, «спасибо» — за вами
  form.addEventListener('crm:lead', (event) => {
    button.disabled = false;
    say(event.detail.ok
      ? 'Спасибо! Ответим в течение рабочего дня.'
      : 'Что-то пошло не так. Попробуйте ещё раз или позвоните нам.');
  });
</script>

<script src="https://widget.sitecog.com/widget.js" defer></script>

Что происходит при отправке формы

  1. Виджет отменяет обычную отправку — нажатием кнопки, клавишей Enter или вызовом form.requestSubmit(): страница не перезагружается, action формы не используется.
  2. Генерирует на форме событие crm:lead-before. Если какой-нибудь обработчик вызовет event.preventDefault(), на этом всё — ничего не отправится.
  3. Собирает поля через FormData — кроме исключённых: паролей, полей с data-crm-ignore и полей с «чувствительными» именами. Учитываются только текстовые значения: поля с файлами пропускаются. Несколько полей с одним именем (группа чекбоксов) склеиваются через ", ". Значение нажатой кнопки не отправляется — если оно нужно, передайте его скрытым полем.
  4. Отправляет заявку под защитой одноразового пропуска формы (подробнее — в разделе о защите от спама). Повторная отправка той же формы, пока идёт первая, — двойной клик — не уходит.
  5. Когда отправка завершилась — сервер ответил или не удалось связаться, — генерирует crm:lead с { ok: true } или { ok: false } в event.detail.
  6. Если ok равно true, вызывает form.reset(). При неудаче форма остаётся как есть — посетитель не потеряет набранное.

Своего интерфейса у виджета нет: ни всплывашки, ни спиннера, ни «спасибо». Сайт ваш, дизайн ваш, слова тоже ваши — слушайте crm:lead и показывайте что угодно.

Атрибуты формы

АтрибутПримерЧто делает
data-crm-lead"quote_request"Превращает форму в форму заявки. Пустой атрибут — встроенная форма lead_submit, она работает без настройки. Значение — имя вашей формы из «Заявки → Формы».
data-crm-value"149900"Сумма в минимальных единицах, целым числом: 149900 — это 1499,00. Сохраняется, только если у формы отмечено «Форма приносит деньги». Не число — не уходят ни сумма, ни валюта.
data-crm-currency"EUR"Валюта суммы: EUR, USD, UAH… — от 1 до 10 латинских букв или цифр. Не указана — берётся валюта формы.
data-crm-ignoreбез значенияСтавится не на форму, а на поле или любую обёртку (fieldset, div…): само поле или всё, что внутри обёртки, в заявку не попадёт. На саму форму и её предков не ставьте — тогда не уйдёт ни одно поле. См. поля, которые никогда не отправляются.

События формы

Оба события всплывают, поэтому слушать их можно на самой форме или один раз на document — сразу для всех форм страницы.

СобытиеКогдаevent.detailМожно отменить
crm:lead-beforeСразу после отправки формы, до отправки заявки{ name } — имя формыДа: preventDefault() отменяет отправку
crm:leadКогда отправка завершилась: сервер ответил или связаться не удалось{ ok } — true, если заявка принятаНет
Один обработчик для всех форм заявок на страницеjs
document.addEventListener('crm:lead', (event) => {
  if (event.detail.ok) {
    event.target.closest('.modal')?.classList.add('is-thanks');
  }
});

Какие имена полей понимает CRM

В карточке заявки четыре главных места: имя, телефон, почта и сообщение. Сервер раскладывает данные по именам полей: обрезает пробелы, переводит в нижний регистр и сверяет с этим списком точно (так что Phone сработает, а your-phone — нет):

МестоИмена полейПредел
Имяname, fio, username, user_name, fullname, full_name, firstname, first_name, contact_name, client_name, имя, фио, ім'я200 символов
Телефонphone, tel, telephone, mobile, phone_number, contact_phone, телефон, тел7–20 цифр
Почтаemail, e_mail, e-mail, mail, contact_email, почта, пошта, емейл320 символов
Сообщениеmessage, comment, comments, text, question, note, description, task, сообщение, комментарий, вопрос, повідомлення, коментар4000 символов
  • Побеждает первое подходящее поле. Если в форме есть и phone, и mobile, место займёт то поле, что идёт в форме раньше.
  • Остальное тоже не теряется. Незнакомые поля и повторные совпадения попадают в «дополнительные» и показываются в карточке в порядке формы. До 30 таких полей; имя — до 60 символов, значение — до 1000.
  • Телефон засчитывается, только если в нём от 7 до 20 цифр. Пробелы, скобки и дефисы не мешают. Хранится он в виде для набора — только цифры и плюс в начале: +49 30 1234567 станет +49301234567.
  • Почта засчитывается, только если похожа на адрес (имя@домен.зона). Иначе значение уйдёт в «дополнительные».
  • Телефон или почта обязательны. Заявка без того и другого отклоняется с no_contact — ответить-то некуда.

Поля, которые никогда не отправляются

Форма регистрации с паролем или оплата с номером карты тоже могут оказаться формой заявки. Чтобы такие данные случайно не осели в CRM, кое-что виджет просто не отправляет:

  • Пароли — любые <input type="password">.
  • Всё, что помечено data-crm-ignore. Атрибут можно поставить на само поле или на любую обёртку — fieldset, div, что угодно: тогда пропускается всё внутри.
  • Поля с «чувствительными» именами. Имя разбивается на слова (по _, -, ., camelCase и так далее), и поле отбрасывается, если отдельным словом в нём стоит card, cc, csc, cvv, cvc, cvv2, cvc2, iban, ssn, secret или pass — либо если в имени, склеенном без разделителей, где угодно встречается password, passwd, pwd, token, csrf, xsrf, creditcard, cardnumber, cardnum, ccnum, ccnumber, cvv или cvc.
Имя поляУйдёт в заявку?Почему
card_numberнетcard — отдельное слово
cvvнетв списке слов
csrf_tokenнетсодержит csrf и token
user_passwordнетсодержит password
acc_numнетбез разделителей это accnum, а в нём есть ccnum
discard_reasonдаcard здесь часть слова discard, а не отдельное слово

Ещё пара деталей:

  • Исключение действует на имя целиком. Если хотя бы одно поле с каким-то именем отброшено, отбрасываются все поля с этим именем.
  • Скрытые поля отправляются. <input type="hidden"> — удобный способ передать товар, тариф или страницу. Если, конечно, его имя не из списка выше.
  • Сервер страхует. Тот же фильтр применяется и на нашей стороне — в том числе к заявкам с сервера. Так что чувствительное поле в CRM не попадёт никаким путём.
Что уйдёт, а что нетhtml
<form data-crm-lead="signup_request">
  <input name="email" type="email">            <!-- уйдёт: это почта заявки -->
  <input name="password" type="password">      <!-- не уйдёт: пароль -->

  <fieldset data-crm-ignore>                   <!-- всё внутри пропускается -->
    <input name="company_inn">
    <input name="billing_address">
  </fieldset>

  <input type="hidden" name="plan" value="pro"> <!-- уйдёт: скрытое поле с обычным именем -->
  <input name="card_number">                   <!-- не уйдёт: card — отдельное слово -->

  <button type="submit">Отправить</button>
</form>

Способ B: отправка из JavaScript

Если состоянием формы управляете вы — React, Vue, многошаговый мастер, чат-бот, — вызывайте виджет напрямую. Обе функции появляются в window, как только загрузится widget.js (внутри iframe их нет). Пропуск формы виджет берёт сам, когда посетитель впервые трогает поле любой формы на странице, — так заявка из вашего кода не выглядит «заполненной за секунду».

crmLead(name, fields, options)

const { ok } = await window.crmLead(
  'callback_request',
  { name: 'Анна', phone: '+49 30 1234567', message: 'Перезвоните после 17:00, пожалуйста' },
  { value: 149900, currency: 'EUR' },
);
namestringобязательно
Имя формы заявок: lead_submit — встроенная, или ваша из «Заявки → Формы». Латиница, цифры и подчёркивания, первой — буква (^[A-Za-z][A-Za-z0-9_]*$). С неподходящим именем в консоли появится предупреждение, а вернётся { ok: false }. Имя события аналитики здесь тоже вернёт { ok: false }.
fieldsobjectобязательно
Данные формы — простые пары «ключ — значение». Ключи разбираются по тем же правилам имён, что и в формах: знакомые заполняют имя, телефон, почту и сообщение, остальные уходят в «дополнительные». Ключи с чувствительными именами (password, card_number…) отбрасываются так же, как поля формы.
options.valueintegerнеобязательно
Сумма в минимальных единицах: 149900 = 1499,00. Сохраняется только у форм с отметкой «Форма приносит деньги».
options.currencystringнеобязательно
Валюта суммы, например EUR: от 1 до 10 латинских букв или цифр. Не указана — берётся валюта формы.

Каждый вызов — отдельная заявка со своим пропуском: два разных вызова подряд дадут две заявки. Тот же вызов с теми же данными, пока первый ещё в пути и пару секунд после (двойной клик), повторно не уходит — он вернёт ответ первого.

Возвращает Promise, который разрешается в:

okboolean
true — заявка принята. false — отклонена или не дошла; причину мы намеренно не сообщаем (почему).

crmLeadForm(form, name)

Делает ровно то же, что атрибут data-crm-lead, только из кода. Пригодится, когда форму рисует сторонняя библиотека и атрибут ей не добавить или когда имя формы выясняется на лету. Ничего не возвращает; результат приходит тем же событием crm:lead. Без имени форма отправляет во встроенную lead_submit. Форму, которая уже подключена, повторный вызов не меняет.

const form = document.querySelector('#newsletter-popup form');
window.crmLeadForm(form, 'newsletter_signup');

form.addEventListener('crm:lead', (e) => {
  if (e.detail.ok) form.innerHTML = '<p>Готово! Загляните в почту.</p>';
});
formHTMLFormElementобязательно
Элемент формы, который нужно подключить.
namestringнеобязательно
Имя формы заявок — по тем же правилам, что и в crmLead. Не передано — встроенная lead_submit.

Типы для TypeScript

Виджет — обычный скрипт, и TypeScript о нём ничего не знает. Добавьте это в любой файл .d.ts:

crm-widget.d.tsts
export {};

declare global {
  interface Window {
    crmLead?: (
      name: string,
      fields: Record<string, string>,
      options?: { value?: number; currency?: string },
    ) => Promise<{ ok: boolean }>;
    crmLeadForm?: (form: HTMLFormElement, name?: string) => void;
  }
}

Как устроена защита от спама

Открытая форма притягивает ботов как магнит. Капча, чтобы их отвадить, не нужна: виджет и сервер справляются вдвоём, а живые посетители ничего не замечают.

Одноразовый пропуск формы

Перед отправкой виджет получает у сервера подписанный «пропуск формы». Берёт он его заранее — как только посетитель впервые трогает поле формы, любой формы на странице, в том числе той, что потом отправит заявку через crmLead. Время от этого касания до отправки и есть время заполнения. Пропуск:

  • одноразовый — один пропуск, одна заявка; следующей отправке виджет возьмёт новый;
  • привязан к вашему сайту — с другого сайта он бесполезен;
  • действует 24 часа — если вкладка открыта дольше, виджет возьмёт свежий.

Боты, которые вслепую шлют POST на адрес приёма, пропуска не имеют и получают отказ. Повтор запроса с тем же пропуском вернёт { ok: true }, но заявка сохранится один раз. Двойной клик по кнопке виджет отсекает сам: пока идёт первая отправка, вторая не уходит.

Ловушка для ботов

То самое скрытое поле company_site. Человек его не видит, и оно остаётся пустым. Бот, который заполняет всё, что находит, выдаёт себя — и заявка отклоняется.

«Подозрительные» заявки

Некоторые заявки выглядят странно, но могут оказаться настоящими. Такие принимаются и получают в CRM пометку «подозрительная» — менеджер посмотрит на неё, прежде чем звонить:

  • от первого касания формы до отправки прошло меньше 3 секунд — быстрее, чем способен человек;
  • форма провисела открытой больше 30 минут;
  • с одного IP-адреса за час пришло больше 5 отправок — считаются все, в том числе отклонённые.

Форму, отправленную совсем без касания полей (автозаполнение и сразу «Отправить»), виджет тоже пометит быстрой: пропуск в этом случае берётся в момент отправки. Заявки с сервера пометок не получают.

«Спам» — это состояние, которое человек ставит в CRM вручную. Автоматически в спам ничего не попадает, так что настоящий клиент молча не потеряется.

IP-адрес в карточке заявки показывается усечённым: у IPv4 последний октет обнуляется (203.0.113.57 → 203.0.113.0), IPv6 обрезается до /48. В базу полный адрес не попадает; для счётчиков защиты от спама он держится в памяти сервера не дольше часа. Подробнее — в разделе Что мы храним и сколько.

Почему браузер получает только ok: true или false

Сообщить боту «отклонено: заполнена ловушка» — значит бесплатно научить его проходить защиту. Поэтому код страницы — crmLead() и событие crm:lead — получает только ok: true или ok: false, без причины. Отлаживаете свою форму? Причину видите вы: CRM записывает её в «Последние отказы», а ошибки настройки — незаведённое имя, форма на событие аналитики, нет телефона и почты — видны и во вкладке Network: ответ 400 с полем message. Отказы защиты (нет пропуска, сработала ловушка) приходят просто { "ok": false }. Список типичных проблем покрывает остальное.

Под капотом: запрос из браузера

Для любопытных — собирать это вручную не придётся. Виджет получает пропуск в POST https://back.sitecog.com/marketing/fk (ответ: {"pass":"…"}), а затем отправляет заявку:

Что отправляет виджетhttp
POST https://back.sitecog.com/marketing/f
Content-Type: application/json

{
  "n": "contact_form",
  "pass": "…",
  "fields": {
    "name": "Анна",
    "email": "anna@example.com",
    "message": "Здравствуйте!",
    "company_site": ""
  },
  "val": 149900,
  "cur": "EUR",
  "u": "https://shop.example/contacts",
  "vid": "…",
  "sid": "…"
}

Ответы: { "ok": true } — заявка принята (или это повтор с тем же пропуском); { "ok": false } — отказ при проверке пропуска или ловушки; ошибки самой заявки — код 400 с полем message (см. ошибки). Если приём заявок на сервере не настроен, /fk отвечает { "pass": null, "reason": "not_configured" }. vid и sid — идентификаторы посетителя и сессии: благодаря им заявка связывается с рекламным каналом, из которого пришёл человек. Подробнее — в разделе События и аналитика.

Отправка заявок с сервера

Не каждая заявка начинается в браузере. Серверный способ нужен, когда:

  • менеджер принимает заказ по телефону и вносит его в вашу учётную систему;
  • форма обрабатывается на бэкенде (обработчик на PHP, server action в Next.js), и зависеть от виджета не хочется;
  • заявки приходят из другой системы: маркетплейса, сервиса бронирования, бота.
POST https://back.sitecog.com/marketing/event
x-event-key: sk_…
Content-Type: application/json

Это тот же адрес, что и у событий с сервера: по имени приём сам понимает, что пришло. Имя формы заявок создаёт заявку, имя события аналитики — событие. Если же в запросе есть поля формы (fields), а имя принадлежит событию аналитики, это ошибка, а не событие: 400 not_lead_form. Прежний адрес https://back.sitecog.com/marketing/lead тоже работает, но принимает только формы заявок.

Секретные ключи

Серверный способ работает по секретному ключу. Выпустить его можно в двух местах — список один на сайт: CRM → Заявки → Формы, вкладка «С сервера» у любой формы, или CRM → Маркетинг → События, панель «Секретные ключи». Введите название и нажмите «Выпустить ключ». Ключ выглядит как sk_ и 48 шестнадцатеричных символов; у сайта может быть до 5 активных ключей, любой можно отозвать. Называйте ключи по месту использования («платёжный сервер», «заказы по телефону») — когда придёт время отзывать, вы себе спасибо скажете.

Видеть и выпускать ключи может владелец или сотрудник, которому можно править «Заявки» (или «Маркетинг → События»). Кто может только смотреть, ключей не увидит.

Пример запроса

curl https://back.sitecog.com/marketing/event \
  -H "x-event-key: sk_3f9a1c7e5b2d4f6a8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "phone_order",
    "event_id": "order-1024",
    "fields": {
      "name": "Анна Шмидт",
      "phone": "+49 30 1234567",
      "message": "Две пары Air 3, графит. Доставка в офис."
    },
    "value": 149900,
    "currency": "EUR",
    "url": "https://shop.example/contacts"
  }'

Тело запроса

x-event-keyheaderstringобязательно
Секретный ключ sk_… из CRM. Нет ключа, он отозван или сайт выключен → 401 invalid_key.
namestringобязательно
Имя формы заявок: lead_submit — встроенная, или ваша из «Заявки → Формы». Короткий вариант: n.
fieldsobjectобязательно
Сама заявка: имя, телефон, почта, сообщение и всё остальное — по тем же правилам имён. Телефон или почта обязательны. Поля можно положить и прямо в корень тела, без fields: тогда полями заявки считается всё, кроме служебных ключей этой таблицы. Но имя человека в корне передайте как full_name или fio — name там имя формы. Поля с чувствительными именами сервер отбрасывает и здесь, даже при запросе с секретным ключом.
event_idstring | numberнеобязательно
Ваш идентификатор заявки: номер заказа, номер обращения. До 128 символов, длиннее — обрежется; число сохранится строкой. Делает запрос идемпотентным. Уникален в пределах сайта и формы: заявка с номером заказа, под которым уже записана покупка, — отдельная запись, а не повтор. Короткий вариант: id.
visitor_idstringнеобязательно
Идентификатор посетителя из браузера (crm_vid). Короткий вариант: vid. См. атрибуцию.
session_idstringнеобязательно
Идентификатор сессии из браузера (crm_sid). С ним заявка наследует рекламный канал и UTM-метки этой сессии. Короткий вариант: sid.
valueintegerнеобязательно
Сумма в минимальных единицах: 149900 = 1499,00. Сохраняется только у форм с отметкой «Форма приносит деньги». Короткий вариант: val.
currencystringнеобязательно
Валюта суммы, например EUR: от 1 до 10 латинских букв или цифр. Не передана — берётся валюта формы. Короткий вариант: cur.
urlstringнеобязательно
Страница, к которой относится заявка или с которой она пришла. Короткий вариант: u.

Ответ

200 OKjson
{ "ok": true, "duplicate": false, "lead": true }
okboolean
При ответе 200 всегда true. Проблемы приходят кодами 4xx с полем message — см. ошибки.
duplicateboolean
true, если у этой формы заявка с таким event_id уже есть. Ничего нового не сохранилось — и это нормально.
leadboolean
true — запрос принят как заявка. Адрес общий с событиями аналитики, а у события этого поля в ответе нет. Отправляли заявку, а lead не пришёл? Имя принадлежит событию аналитики — карточки не будет.

В отличие от браузера, на сервере нет ни пропусков формы, ни проверок по времени: секретного ключа достаточно. А вот ловушка действует: непустое company_site в fields получит 400 rejected.

Идемпотентность: повторяйте без страха

Сеть падает в самый неподходящий момент. Дошёл запрос или нет? С event_id это неважно: просто отправьте ещё раз. Повтор вернёт {"ok":true,"duplicate":true}, и заявка не сохранится дважды.

Тот же event_id, второй разjson
{ "ok": true, "duplicate": true, "lead": true }

Атрибуция: какая реклама привела заявку

Заявки из виджета связываются с посетителем автоматически. Серверная заявка о браузере ничего не знает — пока вы ей не расскажете. Виджет хранит идентификатор посетителя в localStorage под ключом crm_vid, а идентификатор сессии — под crm_sid. Передайте их на бэкенд вместе с формой или заказом, а оттуда — дальше. Читайте их, только когда посетитель согласился на статистику, и в try/catch: хранилище в браузере может быть запрещено, и обращение к нему бросит исключение.

В браузере, при оформлении заказаjs
let crm = {};
try {
  // Без режима согласия status() всегда 'granted'
  if (window.crmConsent?.status() === 'granted') {
    crm = {
      vid: localStorage.getItem('crm_vid'),
      sid: localStorage.getItem('crm_sid'),
    };
  }
} catch {
  // хранилище недоступно — заявка уйдёт без атрибуции
}

await fetch('/api/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ ...order, crm }),
});
// …а на сервере: visitor_id: body.crm.vid, session_id: body.crm.sid

С session_id заявка наследует рекламный канал, рекламную ссылку и UTM-метки первого просмотра этой сессии — они видны в карточке заявки, в блоке «Откуда пришла». Подробнее — в разделе События и аналитика.

Ошибки

В браузере crmLead() и событие crm:lead сообщают только ok: false. Серверный способ отвечает кодом и полем message:

КодТелоЧто случилось
400{"message":"unknown_event","name":"phone_order"}В CRM нет формы с таким именем. Заведите её в «Заявки → Формы» (проверьте написание и регистр) или верните из архива.
400{"message":"not_lead_form","name":"purchase"}Заявку — с полями формы (fields) или на прежний адрес /lead — отправили на имя события аналитики. Заведите форму заявок с другим именем.
400{"message":"invalid_event_name"}Имени нет, или в нём есть что-то кроме латиницы, цифр и подчёркиваний, или оно начинается не с буквы.
400{"message":"no_contact"}Нет ни телефона (7–20 цифр), ни почты, похожей на адрес.
400{"message":"invalid_body"}Тело — не JSON-объект или у запроса неподходящий Content-Type (нужен application/json). Битый JSON получит 400 с текстом ошибки разбора.
400{"message":"rejected"}Заполнено поле-ловушка company_site.
401{"message":"invalid_key"}x-event-key не передан, записан неверно, отозван — или сайт выключен.
413—Тело запроса больше 8 КБ.
429{"message":"rate_limit_exceeded"}Слишком много запросов за эту минуту. Дождитесь следующей.

Запросы из браузера могут получить ещё 400 unknown_domain — домен страницы не заведён в CRM как сайт или выключен — и 400 unknown_origin — у запроса нет ни Origin, ни Referer (например, страница открыта прямо из файла). Их видно во вкладке Network, а код при этом получает ok: false.

Ограничения

ЧтоПредел
Запросы с одного IP (все маркетинговые адреса вместе)120 в минуту
Запросы на сайт6000 в минуту
Пропуски формы с одного IP20 в минуту
Тело запроса8 КБ
Имя / почта / сообщение200 / 320 / 4000 символов
Дополнительные полядо 30; имя — до 60, значение — до 1000 символов
Телефон7–20 цифр, чтобы считаться контактом
event_idдо 128 символов (длиннее обрезается)
Секретные ключидо 5 активных на сайт

Окна — фиксированные минуты: после 429 дождитесь начала следующей. Живой посетитель к этим пределам даже не приблизится, а скрипт, долбящий вашу форму, — вполне.

Если что-то не так

Последние отказы

Первое место, куда стоит заглянуть. Внизу страницы CRM → Заявки → Формы — отправки вашего сайта, которые не стали заявками, и причина каждой: когда, откуда (браузер или сервер), с каким именем и с какой страницы.

ПричинаЧто делать
Имени нет в CRMЗаведите форму — кнопкой «Завести форму» прямо в записи (она видна тем, кто может править «Заявки»). Если имя лежит в архиве, запись так и скажет: верните форму из архива.
Отправлено на событие аналитикиИмя занято событием из «Маркетинг → События». Заведите форму заявок с другим именем и поставьте его на сайте.
Отправлено через crmTrackcrmTrack пишет только события аналитики. Для формы — атрибут data-crm-lead или crmLead().
Нет телефона и почтыПроверьте имена полей по таблице.
Неподходящее имяТолько латиница, цифры и подчёркивания, первой — буква.
Сработала ловушкаЗаполнено скрытое поле company_site: так отправляют боты. Если это ваше настоящее поле — переименуйте.

Хранятся 50 последних отказов сайта — общих для форм и событий; список исчезает через 7 дней после последнего отказа. Один и тот же отказ (та же причина, то же имя, тот же источник — браузер или сервер) записывается не чаще раза в минуту. Сами отклонённые заявки — телефон, почта, текст — не сохраняются: остаётся только след. Стук мимо виджета — запросы без пропуска формы — сюда не попадает, если в нём не заполнена ловушка: это не беда вашей формы, а бот за забором. Отказы событий аналитики — на своей странице, Маркетинг → События.

Заявка не пришла

Сначала загляните в «Последние отказы». Если там пусто — пройдитесь по списку:

  • Имя не заведено. В «Заявки → Формы» должна быть форма ровно с таким именем, с учётом регистра. Пустой data-crm-lead — это встроенная lead_submit: она появляется сама, но только на тарифе с заявками, и не возвращается из архива сама собой.
  • Имя принадлежит событию аналитики. Заявка на такое имя не принимается: заведите форму с другим именем.
  • Отправка через crmTrack. Он не создаёт заявок — нужен атрибут data-crm-lead или crmLead().
  • Нет ни телефона, ни почты. Или они есть, но под незнакомыми CRM именами (your-phone, contact[email]) и уехали в «дополнительные». Переименуйте поля — см. таблицу имён. Телефон короче 7 цифр тоже не засчитывается.
  • Данные были в поле с файлом. Файлы пропускаются — виджет отправляет только текст.
  • Настоящее поле называется company_site. Это имя ловушки, и заявку принимают за бота.
  • Ваш же обработчик crm:lead-before вызвал preventDefault() — возможно, не тогда, когда вы ждали.
  • На этой странице нет виджета. Без widget.js атрибут ничего не делает, и форма отправляется по старинке (или никуда).
  • Форма в iframe, атрибут добавлен позже или отправка через form.submit(). В этих случаях виджет форму не перехватывает — см. где атрибут не сработает.
  • data-crm-ignore стоит на самой форме или её обёртке. Тогда не уходит ни одно поле, и заявка получает «нет телефона и почты».
  • Мешает Content Security Policy. Если у сайта есть CSP, в ней нужны script-src https://widget.sitecog.com и connect-src https://back.sitecog.com. Консоль браузера скажет об этом красным.
  • Домен не заведён в CRM. Сайт определяется по адресу страницы (www. отбрасывается), точно: поддомен вроде shop.example.com — отдельный сайт. На localhost или тестовом домене, которого нет в CRM, во вкладке Network будет unknown_domain. Только что завели домен — подождите до 5 минут.
  • Вы очень активно тестировали. 20 пропусков в минуту с одного IP людям хватает с запасом, а вот лихорадочным кликам — нет. Подождите минуту.

Не дошло одно поле

Заявка в CRM есть, а какого-то поля в ней нет? Скорее всего, виджет (или сервер) отбросил его намеренно:

  • У поля «чувствительное» имя. promo_pass отбрасывается, потому что pass в нём — отдельное слово. Переименуйте во что-нибудь нейтральное, например promo_code. Полный список — в разделе Поля, которые никогда не отправляются.
  • Поле или его обёртка помечены data-crm-ignore. Проверьте всех родителей поля, а не только его самого: атрибут на fieldset или div выше по дереву тоже считается.
  • Это type="password" — пароли не отправляются никогда.
  • Где-то в форме есть второе поле с тем же именем, и оно попало под исключение — тогда отбрасываются все поля с этим именем.
  • Это поле с файлом. Файлы пропускаются в любом случае — виджет отправляет только текст.

Не видно суммы

Сумма видна итогом за последние 30 дней на карточке формы в Заявки → Формы; в карточке самой заявки её нет. Если и там пусто — отметьте у формы «Форма приносит деньги» (значок «Редактировать» у формы): суммы сохранятся у заявок, пришедших после этого. И проверьте, что сумма — целое число в минимальных единицах: 1499.00 отправляется как 149900.

Уведомления в Telegram

Заявка, которую никто не увидел, — потерянная заявка. Подключите своего Telegram-бота — оповещение о новой заявке придёт в течение полуминуты, со ссылкой на её карточку:

  1. Создайте бота и вставьте токен

    Бота создают у @BotFather. В CRM: Заявки → «Настройки заявок» (в шапке раздела), поле «Токен бота», кнопка «Подключить». Бот один на сайт — оповещения через него получат все менеджеры, которых вы выберете.
  2. Соберите получателей

    Каждый, кто должен получать заявки, пишет боту /start (можно добавить бота и в рабочую группу). Затем нажмите «Обновить список» в блоке «Кому сообщать» и включите нужных: новые появляются выключенными. Без этого шага не придёт ничего.
  3. Включите оповещения и проверьте

    Отметьте «Присылать оповещения», при желании — «Присылать и подозрительные», сохраните и нажмите «Проверить связь»: CRM скажет, скольким получателям дошло пробное сообщение.
  • Тихие часы откладывают оповещения, а не выбрасывают их: ночная заявка придёт первым же утром. Окно общее для сайта, но каждому получателю можно задать своё или выключить тишину.
  • Подозрительные заявки при выключенной галочке не присылаются вовсе — ни сразу, ни утром. В CRM они всё равно есть.
  • Если у бота стоит webhook, список получателей не соберётся: снимите webhook или заведите для заявок отдельного бота.

Уведомления оформлены HTML-разметкой, а всё, что ввёл посетитель, перед отправкой экранируется. «Имя» вида <a href="…">Нажмите сюда</a> придёт обычным текстом: замаскировать ссылку под текст или сломать оформление посетитель не сможет. Адрес, набранный в поле как есть, Telegram сам покажет ссылкой. Длинные поля обрезаются — сообщение до 500 символов, остальные до 200, — заявка целиком всегда есть в CRM.

Удаление данных человека по запросу

«Удалите всё, что у вас обо мне есть» — обычная просьба, и ответ на неё не должен превращаться в неделю раскопок по таблицам. В CRM для этого два инструмента, код с вашей стороны не нужен.

Из заявки или чата

В карточке заявки и в карточке чата есть «Удалить данные посетителя». Перед удалением CRM показывает, что именно уйдёт:

  • профиль посетителя и аналитика — просмотры страниц и события;
  • чаты и вложения — сколько чатов, сообщений и файлов;
  • заявки — только если отметить «Также удалить заявки этого посетителя». По умолчанию выключено: заявка часто — сделка в работе, и решать вам.

Заявка без visitor_id — отправленная с сервера без него или из браузера до согласия посетителя в режиме согласия — к посетителю не привязана: у неё удаляется только сама заявка.

По почте или телефону

Обычно просьба приходит письмом: «Я anna@example.com, забудьте меня». Откройте CRM → Настройки → «Запросы на удаление данных», введите почту или телефон, которые указал человек, — и CRM найдёт его заявки и переписку (по почте или телефону) и учётную запись на вашем сайте (только по почте). Кнопка «Удалить всё найденное» удаляет всё разом.

  • Статистика посещений. Галочка «Также удалить статистику посещений связанных посетителей» включена по умолчанию — снимите её, если статистику нужно сохранить.
  • Переписка удаляется целиком. У найденных посетителей уходят все их чаты, в том числе архивные, вместе с вложениями. Файлы, которые вставлены в страницы сайта, остаются.
  • Права. Для удаления нужно право править соответствующий раздел: заявки — «Заявки», переписку — «Чаты», учётные записи — «Пользователи сайта», статистику — «Посещаемость». Менеджер, который может только смотреть, увидит найденное, но удалить не сможет.
  • Журнал действий. Каждое удаление записывается в журнал — без почты и телефона человека, иначе журнал хранил бы ровно то, что просили забыть.
  • Без отмены. Удалено — значит удалено. Проверьте цифры, прежде чем подтверждать.