Форма зворотного зв’язку, що шле листи людині у відпустці, — ідеальне місце, де заявки тихо помирають. З Sitecog кожна форма на вашому сайті потрапляє в CRM карткою — з телефоном чи поштою, статусом і відповідальним, який має передзвонити. Вистачить одного атрибута на <form>, а коли потрібно більше контролю, є варіанти з JavaScript і з сервера.
Три способи надіслати заявку — обирайте, який зручніший:
- Форма з
data-crm-lead— нуль JavaScript. Віджет перехоплює надсилання й робить усе сам. window.crmLead()— для React, Vue і будь-якої форми, якою ви керуєте самі.POST /marketing/eventз вашого сервера — замовлення телефоном, форми на бекенді, інтеграції з іншими системами.
Як заявка потрапляє з форми в CRM
Кожна форма заявок має ім’я. Одна форма на сайті вже є — вбудована lead_submit, «Заявка з сайту». Будь-яка форма з порожнім атрибутом data-crm-lead надсилає заявки до неї, і кожне надсилання стає карткою в CRM → Заявки — без жодного кроку в CRM. Вбудована форма з’являється на сайтах, тариф яких передбачає заявки.
- Відвідувач заповнює форму й натискає «Надіслати».
- Віджет збирає поля форми й відправляє їх; де ім’я, телефон, пошта й повідомлення, розбирається сервер.
- Сервер перевіряє, що така форма існує, що в заявці є телефон або пошта і що вона не схожа на бота.
- У CRM з’являється картка заявки — а якщо налаштуєте, то й сповіщення в Telegram.
Два правила, які варто запам’ятати одразу:
- Невідоме ім’я відхиляється. CRM приймає лише форми, про які знає, — жодного несподіваного сміття через одруківки. Сама з’являється тільки вбудована
lead_submit. - Форми заявок і події аналітики не змішуються. Заявку, надіслану на ім’я події аналітики, буде відхилено, а
crmTrackз ім’ям форми заявок нічого не записує. Кожну таку відмову CRM показує в «Останніх відмовах».
Окремі форми: заведіть їх у CRM
Вбудованої форми досить, поки заявки на сайті одного виду. Хочете відрізняти «Замовити дзвінок» від «Розрахувати вартість» — у списку заявок, у фільтрі й у лічильниках на сторінці «Форми»? Дайте кожній формі своє ім’я. Кілька кліків, один раз на кожен тип форми:
Відкрийте Заявки → Форми
Кнопка «Форми» в шапці розділу «Заявки». Тут усі форми заявок сайту й скільки заявок прийшло з кожної за останні 30 днів. Форми в архіві видно за галочкою «Показувати архів».Натисніть «Нова форма»
Дайте їй ім’я, яке використовуватиме ваш код: латинські літери, цифри й підкреслення, починаючи з літери, —callback_request,quote_request. Ім’я потім не змінити — перевірте написання.За бажання: позначте «Форма приносить гроші»
Лише тоді зберігаються сума й валюта заявки. Без цієї позначки їх мовчки ігнорують.Вкажіть ім’я на сайті
data-crm-lead="callback_request"на формі,crmLead('callback_request', …)у коді або"name": "callback_request"у запиті з сервера. Готовий код для всіх трьох способів CRM показує на сторінці форми.
Варіант A: форма з одним атрибутом
Додайте атрибут data-crm-lead до будь-якої форми на сторінці, де є скрипт віджета. Це й уся інтеграція. Порожній атрибут надсилає заявки до вбудованої форми lead_submit, атрибут зі значенням — до вашої форми з таким ім’ям (data-crm-lead="quote_request"). Форми, що з’являються пізніше — у модальному вікні, після зміни маршруту в односторінковому застосунку, — підхоплюються автоматично, якщо їх вставлено в сторінку вже з атрибутом.
<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>'use client';
import { useState, type FormEvent } from 'react';
const EMPTY = { name: '', phone: '', email: '', message: '' };
export function QuoteForm() {
const [form, setForm] = useState(EMPTY);
const [status, setStatus] = useState<'idle' | 'sending' | 'done' | 'error'>('idle');
const set = (key: keyof typeof EMPTY) => (e: { target: { value: string } }) =>
setForm((prev) => ({ ...prev, [key]: e.target.value }));
async function onSubmit(e: FormEvent) {
e.preventDefault();
if (!form.phone.trim() && !form.email.trim()) {
setStatus('error');
return;
}
setStatus('sending');
// crmLead ніколи не кидає винятків; undefined він лише тоді, коли widget.js немає на сторінці
const res = await window.crmLead?.('quote_request', form, { value: 149900, currency: 'EUR' });
if (res?.ok) {
setForm(EMPTY);
setStatus('done');
} else {
setStatus('error');
}
}
if (status === 'done') return <p>Дякуємо! Ми відповімо протягом одного робочого дня.</p>;
// Тут немає data-crm-lead: ця форма надсилає через crmLead сама
return (
<form onSubmit={onSubmit}>
<input value={form.name} onChange={set('name')} placeholder="Ваше ім’я" required />
<input value={form.phone} onChange={set('phone')} type="tel" placeholder="Телефон" />
<input value={form.email} onChange={set('email')} type="email" placeholder="Email" />
<textarea value={form.message} onChange={set('message')} placeholder="Що вам потрібно?" />
<button disabled={status === 'sending'}>Надіслати запит</button>
{status === 'error' && <p role="alert">Залиште телефон або email і спробуйте ще раз.</p>}
</form>
);
}<script setup lang="ts">
import { reactive, ref } from 'vue';
const empty = () => ({ name: '', phone: '', email: '', message: '' });
const form = reactive(empty());
const status = ref<'idle' | 'sending' | 'done' | 'error'>('idle');
async function submit() {
if (!form.phone.trim() && !form.email.trim()) {
status.value = 'error';
return;
}
status.value = 'sending';
// crmLead ніколи не кидає винятків; undefined він лише тоді, коли widget.js немає на сторінці
const res = await window.crmLead?.('quote_request', { ...form }, { value: 149900, currency: 'EUR' });
if (res?.ok) {
Object.assign(form, empty());
status.value = 'done';
} else {
status.value = 'error';
}
}
</script>
<template>
<p v-if="status === 'done'">Дякуємо! Ми відповімо протягом одного робочого дня.</p>
<!-- Тут немає data-crm-lead: ця форма надсилає через crmLead сама -->
<form v-else @submit.prevent="submit">
<input v-model="form.name" placeholder="Ваше ім’я" required />
<input v-model="form.phone" type="tel" placeholder="Телефон" />
<input v-model="form.email" type="email" placeholder="Email" />
<textarea v-model="form.message" placeholder="Що вам потрібно?" />
<button :disabled="status === 'sending'">Надіслати запит</button>
<p v-if="status === 'error'" role="alert">Залиште телефон або email і спробуйте ще раз.</p>
</form>
</template>Що відбувається, коли форму надсилають
- Віджет скасовує нативне надсилання — натисканням кнопки, клавішею Enter або викликом
form.requestSubmit(): сторінка не перезавантажується, аactionформи не використовується. - Він запускає на формі
crm:lead-before. Якщо хоч один обробник викличеevent.preventDefault(), історія на цьому закінчується й нічого не надсилається. - Він збирає поля через
FormData. Враховуються лише текстові значення: поля з файлами ігноруються. Кілька полів з однаковим ім’ям (група чекбоксів) склеюються через", ". Паролі, поля з чутливими іменами й усе, що позначеноdata-crm-ignore, пропускаються — див. «Поля, які ніколи не надсилаються». Значення натиснутої кнопки не надсилається — якщо воно потрібне, передайте його прихованим полем. - Він надсилає заявку, захищену одноразовим пропуском форми (детальніше — у розділі про захист від спаму). Повторне надсилання тієї самої форми, поки триває перше, — подвійний клік — не йде.
- Коли надсилання завершилося — сервер відповів або зв’язатися не вдалося, — він запускає
crm:leadз{ ok: true }або{ ok: false }вevent.detail. - Якщо
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, якщо заявку прийнято | Ні |
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") надсилаються — ними зручно передати товар, тариф чи сторінку, — якщо тільки їхнє ім’я не чутливе.
<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, що розв’язується в:
okbooleantrue — заявку прийнято. 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:
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":"…"}), а потім надсилає заявку:
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"
}'// Node 18+ — fetch уже вбудований
const res = await fetch('https://back.sitecog.com/marketing/event', {
method: 'POST',
headers: {
'x-event-key': process.env.CRM_EVENT_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'phone_order',
event_id: `order-${order.id}`, // повтор не створить другу заявку
visitor_id: order.crmVid, // збережено з браузера під час оформлення, якщо є
session_id: order.crmSid,
fields: {
name: order.customerName,
phone: order.phone,
message: order.comment,
delivery: order.deliveryMethod, // піде в «Інші поля форми»
},
value: order.totalCents, // 149900 = 1499,00
currency: 'EUR',
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`CRM lead: ${res.status} ${data.message}`);
// data → { ok: true, duplicate: false, lead: true }import os
import requests
res = requests.post(
"https://back.sitecog.com/marketing/event",
headers={"x-event-key": os.environ["CRM_EVENT_KEY"]},
json={
"name": "phone_order",
"event_id": "order-1024",
"fields": {
"name": "Anna Schmidt",
"phone": "+49 30 1234567",
"message": "Two pairs of Air 3, graphite.",
},
"value": 149900,
"currency": "EUR",
},
timeout=10,
)
res.raise_for_status()
print(res.json()) # {'ok': True, 'duplicate': False, 'lead': True}Тіло запиту
x-event-keyheaderstringобовʼязковоsk_… з CRM. Ключа немає, його відкликано або сайт вимкнено →401 invalid_key.namestringобовʼязковоlead_submit — вбудована, або ваша із «Заявки → Форми». Короткий синонім: n.fieldsobjectобовʼязковоfields: тоді полями заявки вважається все, крім службових ключів цієї таблиці. Але ім’я людини в корені передайте як full_name або fio — name там означає ім’я форми. Поля з чутливими іменами сервер відкидає й тут, навіть із секретним ключем.event_idstring | numberнеобовʼязковоid.visitor_idstringнеобовʼязковоsession_idstringнеобовʼязковоcrm_sid). З ним заявка успадковує рекламний канал і UTM-мітки цієї сесії. Синонім: sid.valueintegerнеобовʼязково149900 = 1499,00. Зберігається лише для форм з позначкою «Форма приносить гроші». Синонім: val.currencystringнеобовʼязковоEUR: від 1 до 10 латинських літер або цифр. Не передано — береться валюта форми. Синонім: cur.urlstringнеобовʼязковоu.Відповідь
{ "ok": true, "duplicate": false, "lead": true }okbooleanduplicatebooleantrue, якщо в цієї форми заявка з таким event_id уже існує. Нічого нового не збережено, і це нормально.leadbooleantrue — запит прийнято як заявку. Адреса спільна з подіями аналітики, а у відповіді для події цього поля немає. Надсилали заявку, а поля lead у відповіді не видно? Ім’я належить події аналітики — картки не буде.На відміну від браузера, серверний маршрут не використовує пропусків форми й перевірок часу — секретного ключа достатньо як доказу. Пастка для ботів діє й тут: непорожнє company_site у fields отримує 400 rejected.
Ідемпотентність: повторюйте без страху
Мережа падає в найгірші моменти. Запит пройшов чи ні? З event_id знати це не обов’язково: просто надішліть ще раз. Повтор поверне {"ok":true,"duplicate":true}, і заявку не буде збережено двічі.
{ "ok": true, "duplicate": true, "lead": true }Атрибуція: яка реклама привела заявку
Заявки з віджета прив’язуються до відвідувача автоматично. Серверна заявка нічого не знає про браузер — якщо ви їй не розкажете. Віджет зберігає ідентифікатор відвідувача в localStorage під ключем crm_vid, а ідентифікатор сесії — під crm_sid. Передайте їх на свій бекенд разом із формою чи замовленням і перешліть далі. Читайте їх, лише коли відвідувач погодився на статистику, і в try/catch: сховище в браузері може бути заборонене, і звернення до нього кине виняток.
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 за хвилину |
| Пропуски форми з одного IP | 20 за хвилину |
| Тіло запиту | 8 КБ |
| Ім’я / пошта / повідомлення | 200 / 320 / 4000 символів |
| Додаткові поля | до 30; ключ до 60, значення до 1000 символів |
| Телефон | 7–20 цифр, щоб рахуватися контактом |
event_id | до 128 символів (довший обрізається) |
| Секретні ключі | до 5 активних на сайт |
Вікна — фіксовані хвилини: після 429 зачекайте, доки почнеться наступна хвилина. Справжній відвідувач навіть не наблизиться до лімітів; скрипт, що гатить по вашій формі, — наблизиться.
Якщо щось не так
Останні відмови
Перше місце, куди варто зазирнути. Унизу сторінки CRM → Заявки → Форми — надсилання вашого сайту, які не стали заявками, і причина кожного: коли, звідки (браузер чи сервер), з яким ім’ям і з якої сторінки.
| Причина | Що робити |
|---|---|
| Імені немає в CRM | Заведіть форму — кнопкою «Завести форму» просто в записі (її бачать ті, хто має право «Правка» в «Заявках»). Якщо ім’я лежить в архіві, запис так і скаже: поверніть форму з архіву. |
| Надіслано на подію аналітики | Ім’я зайняте подією з «Маркетинг → Події». Заведіть форму заявок з іншим ім’ям і вкажіть його на сайті. |
Надіслано через crmTrack | crmTrack записує лише події аналітики. Для форми — атрибут 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-бота — сповіщення про нову заявку прийде протягом пів хвилини, з посиланням на її картку:
Створіть бота й вставте токен
Бота створюють у@BotFather. У CRM: Заявки → «Налаштування заявок» (у шапці розділу), поле «Токен бота», кнопка «Підключити». Бот один на сайт — сповіщення через нього отримають усі менеджери, яких ви оберете.Зберіть отримувачів
Кожен, хто має отримувати заявки, пише боту/start(бота можна додати й у робочу групу). Потім натисніть «Оновити список» у блоці «Кому повідомляти» й увімкніть потрібних: нові з’являються вимкненими. Без цього кроку не прийде нічого.Увімкніть сповіщення й перевірте
Позначте «Надсилати сповіщення», за бажання — «Надсилати й підозрілі», збережіть і натисніть «Перевірити зв’язок»: CRM скаже, скільком отримувачам дійшло пробне повідомлення.
- Тихі години відкладають сповіщення, а не викидають їх: нічна заявка прийде першого ж ранку. Вікно спільне для сайту, але кожному отримувачу можна задати своє або вимкнути тишу.
- Підозрілі заявки за вимкненої галочки не надсилаються взагалі — ні одразу, ні вранці. У CRM вони однаково є.
- Якщо в бота стоїть webhook, список отримувачів не збереться: зніміть webhook або заведіть для заявок окремого бота.
Сповіщення оформлені HTML-розміткою, а все, що ввів відвідувач, перед надсиланням екранується. «Ім’я» на кшталт <a href="…">Натисніть сюди</a> прийде звичайним текстом: замаскувати посилання під текст чи зламати оформлення відвідувач не зможе. Адресу, набрану в полі як є, Telegram сам покаже посиланням. Довгі поля обрізаються — повідомлення до 500 символів, решта до 200, — заявка повністю завжди є в CRM.
Видалення даних людини на запит
«Видаліть усе, що у вас є про мене» — звичайне прохання, і відповідь на нього не має перетворюватися на тиждень розкопок у таблицях. У CRM для цього є два інструменти, код із вашого боку не потрібен.
Із заявки або чату
У картці заявки й у картці чату є «Видалити дані відвідувача». Перед видаленням CRM показує, що саме буде видалено:
- профіль відвідувача та аналітика — перегляди сторінок і події;
- чати й вкладення — скільки чатів, повідомлень і файлів;
- заявки — лише якщо позначити «Також видалити заявки цього відвідувача». За замовчуванням вимкнено: заявка часто — угода в роботі, і вирішувати вам.
Заявка без visitor_id — надіслана із сервера без нього або з браузера до згоди відвідувача в режимі згоди — до відвідувача не прив’язана: у неї видаляється лише сама заявка.
За поштою або телефоном
Зазвичай прохання надходить листом: «Я anna@example.com, забудьте мене». Відкрийте CRM → Налаштування → «Запити на видалення даних», введіть пошту або телефон, які вказала людина, — і CRM знайде її заявки й листування (за поштою або телефоном) та обліковий запис на вашому сайті (лише за поштою). Кнопка «Видалити все знайдене» видаляє все разом.
- Статистика відвідувань. Галочка «Також видалити статистику відвідувань пов’язаних відвідувачів» увімкнена за замовчуванням — зніміть її, якщо статистику треба зберегти.
- Листування видаляється повністю. У знайдених відвідувачів зникають усі їхні чати, зокрема архівні, разом із вкладеннями. Файли, вставлені в сторінки сайту, лишаються.
- Права. Для видалення потрібне право «Правка» у відповідному розділі: заявки — «Заявки», листування — «Чати», облікові записи — «Користувачі сайту», статистика — «Відвідуваність». Менеджер, який має лише «Перегляд», побачить знайдене, але видалити не зможе.
- Журнал дій. Кожне видалення записується в журнал — без пошти й телефону людини, інакше журнал зберігав би саме те, що просили забути.
- Без скасування. Видалено — отже, видалено. Перевірте цифри, перш ніж підтверджувати.