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>Email <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('Залиште, будь ласка, телефон або email, щоб ми могли відповісти.');
      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 data-crm-ignore>Ставиться не на форму, а на поле або на будь-яку обгортку (fieldset, div…). Поле — чи все, що всередині обгортки, — до заявки не потрапить. На саму форму та її предків не ставте — тоді не піде жодне поле. Див. «Поля, які ніколи не надсилаються».

Події форми

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

ПодіяКолиevent.detailМожна скасувати
crm:lead-beforeОдразу після submit, до надсилання заявки{ 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 — відповісти ж не було б як.

Поля, які ніколи не надсилаються

Заявка — не місце для паролів і номерів карток, навіть якщо вони випадково опинилися в тій самій формі. Тож віджет пропускає:

  • поля 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, cvv, csrf_token і user_password до CRM не дійдуть. acc_num — теж: без роздільників це accnum, а в ньому є ccnum. А discard_reason — дійде: card там не окреме слово, а шматок discard.

Якщо одне поле з якимось ім’ям виключено, виключаються всі поля з цим ім’ям, де б вони не стояли. А от приховані поля (type="hidden") надсилаються — ними зручно передати товар, тариф чи сторінку, — якщо тільки їхнє ім’я не чутливе.

Що піде в заявку, а що ніhtml
<form data-crm-lead="signup_request">
  <input name="name" autocomplete="name">                <!-- ✓ -->
  <input name="email" type="email">                      <!-- ✓ -->
  <input name="account_pin" type="password">             <!-- ✗ пароль, ім’я не має значення -->
  <input name="card_number" inputmode="numeric">         <!-- ✗ card — окреме слово -->
  <input type="hidden" name="plan" value="pro">          <!-- ✓ приховане, піде в «Інші поля форми» -->

  <fieldset data-crm-ignore>                             <!-- ✗ усе всередині -->
    <legend>Лише для оплати</legend>
    <input name="billing_address">
    <input name="billing_zip">
  </fieldset>

  <button>Зареєструватися</button>
</form>

Сервер застосовує той самий фільтр імен ще раз — до заявок з віджета, з crmLead() і навіть до заявок із сервера, підписаних секретним ключем. Тож поле з чутливим ім’ям в CRM не потрапить ніколи, хоч би звідки прийшла заявка.

Варіант B: надсилайте заявки з JavaScript

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

crmLead(name, fields, options)

const { ok } = await window.crmLead(
  'callback_request',
  { name: 'Anna', 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обовʼязково
Дані форми у вигляді простих пар ключ–значення. Ключі підкоряються тим самим правилам імен полів, що й у формах: відомі заповнюють ім’я, телефон, пошту й повідомлення, решта йде в «Інші поля форми». Ключі з чутливими іменами (card_number, csrf_token…) відкидаються так само, як у формі.
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;
  }
}

Як працює захист від спаму

Публічна форма — магніт для ботів. Щоб їх не пускати, CAPTCHA не потрібна: віджет і сервер справляються з цим разом, а справжні відвідувачі нічого не помічають.

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

Перед надсиланням віджет отримує від сервера підписаний «пропуск форми». Бере він його заздалегідь — щойно відвідувач уперше торкається поля форми, будь-якої форми на сторінці, зокрема тієї, що потім надішле заявку через 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": "Anna",
    "email": "anna@example.com",
    "message": "Hi!",
    "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": "Anna Schmidt",
      "phone": "+49 30 1234567",
      "message": "Two pairs of Air 3, graphite. Delivery to the office."
    },
    "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
Завжди true при 200. Проблеми повертаються як 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. Сайт розпізнається за origin сторінки (www. відкидається) за точним збігом: піддомен на кшталт shop.example.com — окремий сайт. Тест на localhost чи на тестовому домені, якого не додано в CRM, дає unknown_domain на вкладці Network. Щойно додали домен — зачекайте до 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 знайде її заявки й листування (за поштою або телефоном) та обліковий запис на вашому сайті (лише за поштою). Кнопка «Видалити все знайдене» видаляє все разом.

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