Форма обратной связи, которая шлёт письмо сотруднику в отпуске, — кладбище заявок. В 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>Почта <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>'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="Почта" />
<textarea value={form.message} onChange={set('message')} placeholder="Что нужно сделать?" />
<button disabled={status === 'sending'}>Отправить</button>
{status === 'error' && <p role="alert">Оставьте телефон или почту и попробуйте ещё раз.</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="Почта" />
<textarea v-model="form.message" placeholder="Что нужно сделать?" />
<button :disabled="status === 'sending'">Отправить</button>
<p v-if="status === 'error'" role="alert">Оставьте телефон или почту и попробуйте ещё раз.</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, div…): само поле или всё, что внутри обёртки, в заявку не попадёт. На саму форму и её предков не ставьте — тогда не уйдёт ни одно поле. См. поля, которые никогда не отправляются. |
События формы
Оба события всплывают, поэтому слушать их можно на самой форме или один раз на document — сразу для всех форм страницы.
| Событие | Когда | event.detail | Можно отменить |
|---|---|---|---|
crm:lead-before | Сразу после отправки формы, до отправки заявки | { 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— ответить-то некуда.
Поля, которые никогда не отправляются
Форма регистрации с паролем или оплата с номером карты тоже могут оказаться формой заявки. Чтобы такие данные случайно не осели в 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 не попадёт никаким путём.
<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, который разрешается в:
okbooleancrmLeadForm(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;
}
}Как устроена защита от спама
Открытая форма притягивает ботов как магнит. Капча, чтобы их отвадить, не нужна: виджет и сервер справляются вдвоём, а живые посетители ничего не замечают.
Одноразовый пропуск формы
Перед отправкой виджет получает у сервера подписанный «пропуск формы». Берёт он его заранее — как только посетитель впервые трогает поле формы, любой формы на странице, в том числе той, что потом отправит заявку через 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": "Анна",
"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"
}'// 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": "Анна Шмидт",
"phone": "+49 30 1234567",
"message": "Две пары Air 3, графит.",
},
"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. Сайт определяется по адресу страницы (
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-бота — оповещение о новой заявке придёт в течение полуминуты, со ссылкой на её карточку:
Создайте бота и вставьте токен
Бота создают у@BotFather. В CRM: Заявки → «Настройки заявок» (в шапке раздела), поле «Токен бота», кнопка «Подключить». Бот один на сайт — оповещения через него получат все менеджеры, которых вы выберете.Соберите получателей
Каждый, кто должен получать заявки, пишет боту/start(можно добавить бота и в рабочую группу). Затем нажмите «Обновить список» в блоке «Кому сообщать» и включите нужных: новые появляются выключенными. Без этого шага не придёт ничего.Включите оповещения и проверьте
Отметьте «Присылать оповещения», при желании — «Присылать и подозрительные», сохраните и нажмите «Проверить связь»: CRM скажет, скольким получателям дошло пробное сообщение.
- Тихие часы откладывают оповещения, а не выбрасывают их: ночная заявка придёт первым же утром. Окно общее для сайта, но каждому получателю можно задать своё или выключить тишину.
- Подозрительные заявки при выключенной галочке не присылаются вовсе — ни сразу, ни утром. В CRM они всё равно есть.
- Если у бота стоит webhook, список получателей не соберётся: снимите webhook или заведите для заявок отдельного бота.
Уведомления оформлены HTML-разметкой, а всё, что ввёл посетитель, перед отправкой экранируется. «Имя» вида <a href="…">Нажмите сюда</a> придёт обычным текстом: замаскировать ссылку под текст или сломать оформление посетитель не сможет. Адрес, набранный в поле как есть, Telegram сам покажет ссылкой. Длинные поля обрезаются — сообщение до 500 символов, остальные до 200, — заявка целиком всегда есть в CRM.
Удаление данных человека по запросу
«Удалите всё, что у вас обо мне есть» — обычная просьба, и ответ на неё не должен превращаться в неделю раскопок по таблицам. В CRM для этого два инструмента, код с вашей стороны не нужен.
Из заявки или чата
В карточке заявки и в карточке чата есть «Удалить данные посетителя». Перед удалением CRM показывает, что именно уйдёт:
- профиль посетителя и аналитика — просмотры страниц и события;
- чаты и вложения — сколько чатов, сообщений и файлов;
- заявки — только если отметить «Также удалить заявки этого посетителя». По умолчанию выключено: заявка часто — сделка в работе, и решать вам.
Заявка без visitor_id — отправленная с сервера без него или из браузера до согласия посетителя в режиме согласия — к посетителю не привязана: у неё удаляется только сама заявка.
По почте или телефону
Обычно просьба приходит письмом: «Я anna@example.com, забудьте меня». Откройте CRM → Настройки → «Запросы на удаление данных», введите почту или телефон, которые указал человек, — и CRM найдёт его заявки и переписку (по почте или телефону) и учётную запись на вашем сайте (только по почте). Кнопка «Удалить всё найденное» удаляет всё разом.
- Статистика посещений. Галочка «Также удалить статистику посещений связанных посетителей» включена по умолчанию — снимите её, если статистику нужно сохранить.
- Переписка удаляется целиком. У найденных посетителей уходят все их чаты, в том числе архивные, вместе с вложениями. Файлы, которые вставлены в страницы сайта, остаются.
- Права. Для удаления нужно право править соответствующий раздел: заявки — «Заявки», переписку — «Чаты», учётные записи — «Пользователи сайта», статистику — «Посещаемость». Менеджер, который может только смотреть, увидит найденное, но удалить не сможет.
- Журнал действий. Каждое удаление записывается в журнал — без почты и телефона человека, иначе журнал хранил бы ровно то, что просили забыть.
- Без отмены. Удалено — значит удалено. Проверьте цифры, прежде чем подтверждать.