A contact form that emails someone who is on holiday is where leads go to die. With Sitecog, every form on your site lands as a card in the CRM — with a phone or an email, a status and someone responsible for calling back. One attribute on a <form> is enough; JavaScript and server-side options are there when you need more control.
Three ways to send a lead, pick whichever fits:
- A form with
data-crm-lead— zero JavaScript. The widget catches the submit and does the rest. window.crmLead()— for React, Vue and any form you control yourself.POST /marketing/eventfrom your server — phone orders, backend forms, integrations with other systems.
How a lead gets from your form to the CRM
Every lead form has a name. One form is already on your site: the built-in lead_submit, “Website lead”. Any form with an empty data-crm-lead attribute sends its leads there, and every submission becomes a card in CRM → Leads — without a single step in the CRM. The built-in form appears on every site whose plan includes leads.
- A visitor fills in the form and presses “Send”.
- The widget collects the form fields and sends them off; the server works out which is the name, phone, email and message.
- The server checks the form exists, the lead has a phone or an email, and it doesn't look like a bot.
- A lead card appears in the CRM — and, if you set it up, a notification in Telegram.
Two rules worth remembering from the start:
- An undeclared name is refused. The CRM only accepts forms it knows about — no surprise junk from typos. The built-in
lead_submitis the only one that appears by itself. - Lead forms and analytics events don't mix. A lead sent under the name of an analytics event is refused, and
crmTrackwith a lead form's name records nothing. The CRM shows every such rejection in “Recent rejections”.
Separate forms: create them in the CRM
The built-in form is enough while all the leads on your site are of one kind. Want to tell “Call me back” from “Get a quote” — in the lead list, in filters and in the counters on the “Forms” page? Give each form its own name. A couple of clicks, once per form type:
Open Leads → Forms
The “Forms” button in the header of the Leads section. It lists every lead form on the site and how many leads each one has brought in the last 30 days. Archived forms show up when you tick “Show archive”.Click “New form”
Give it the name your code will use: Latin letters, digits and underscores, starting with a letter —callback_request,quote_request. The name can't be changed later, so check the spelling.Optional: tick “This form brings revenue”
Only then are the amount and currency of the lead stored. Without it they are quietly ignored.Put the name on your site
data-crm-lead="callback_request"on the form,crmLead('callback_request', …)in code or"name": "callback_request"in a request from your server. The form's page in the CRM shows ready-made code for all three.
Option A: a form with one attribute
Add the data-crm-lead attribute to any form on a page that has the widget script. That is the whole integration. An empty attribute sends leads to the built-in lead_submit form; a value sends them to your own form with that name (data-crm-lead="quote_request"). Forms that show up later — in a modal, after a route change in a single-page app — are picked up automatically, as long as they land on the page with the attribute already in place.
<form data-crm-lead>
<input name="name">
<input name="phone" type="tel">
<textarea name="message"></textarea>
<button type="submit">Send</button>
</form>Full example
A “request a quote” form with name, phone, email and a message, an order amount (the total per form shows on its card in Leads → Forms), a “thank you” message and a custom check. It assumes quote_request is created in Leads → Forms with “This form brings revenue” ticked. Plain HTML first; React and Vue versions call crmLead() from their own submit handler.
<form id="quote" data-crm-lead="quote_request" data-crm-value="149900" data-crm-currency="EUR">
<label>Your name <input name="name" autocomplete="name" required></label>
<label>Phone <input name="phone" type="tel" autocomplete="tel"></label>
<label>Email <input name="email" type="email" autocomplete="email"></label>
<label>What do you need? <textarea name="message" rows="4"></textarea></label>
<!-- Not one of the known fields: shows up in the lead card as is -->
<label>Team size
<select name="team_size">
<option>1–5</option>
<option>6–20</option>
<option>20+</option>
</select>
</label>
<button type="submit">Send request</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. Before sending: our own check. preventDefault() = nothing is sent
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('Please leave a phone number or an email so we can reply.');
return;
}
button.disabled = true;
});
// 2. After sending: the widget shows nothing, the "thank you" is ours
form.addEventListener('crm:lead', (event) => {
button.disabled = false;
say(event.detail.ok
? 'Thank you! We will get back to you within one business day.'
: 'Something went wrong. Please try again or give us a call.');
});
</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 never throws; it is undefined only if widget.js is not on the page
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>Thank you! We will get back to you within one business day.</p>;
// No data-crm-lead here: this form sends through crmLead itself
return (
<form onSubmit={onSubmit}>
<input value={form.name} onChange={set('name')} placeholder="Your name" required />
<input value={form.phone} onChange={set('phone')} type="tel" placeholder="Phone" />
<input value={form.email} onChange={set('email')} type="email" placeholder="Email" />
<textarea value={form.message} onChange={set('message')} placeholder="What do you need?" />
<button disabled={status === 'sending'}>Send request</button>
{status === 'error' && <p role="alert">Please leave a phone or an email, then try again.</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 never throws; it is undefined only if widget.js is not on the page
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'">Thank you! We will get back to you within one business day.</p>
<!-- No data-crm-lead here: this form sends through crmLead itself -->
<form v-else @submit.prevent="submit">
<input v-model="form.name" placeholder="Your name" required />
<input v-model="form.phone" type="tel" placeholder="Phone" />
<input v-model="form.email" type="email" placeholder="Email" />
<textarea v-model="form.message" placeholder="What do you need?" />
<button :disabled="status === 'sending'">Send request</button>
<p v-if="status === 'error'" role="alert">Please leave a phone or an email, then try again.</p>
</form>
</template>What happens when the form is submitted
- The widget cancels the native submit — whether it comes from a button, the Enter key or
form.requestSubmit(): the page doesn't reload, and the form'sactionis not used. - It fires
crm:lead-beforeon the form. If any listener callsevent.preventDefault(), the story ends here and nothing is sent. - It collects the fields with
FormData— except the ones that are never sent (passwords, card numbers and friends). Only text values count: file inputs are ignored. Several fields with the same name (a group of checkboxes) are joined with", ". The value of the button that was pressed isn't sent — if you need it, pass it in a hidden field. - It sends the lead, protected by a one-time form pass (more on that in spam protection). A second submit of the same form while the first is still on its way — a double click — doesn't go out.
- Once sending is over — the server answered or couldn't be reached — it fires
crm:leadwith{ ok: true }or{ ok: false }inevent.detail. - If
okis true, it callsform.reset(). On failure the form is left as is, so the visitor doesn't lose what they typed.
The widget shows no UI of its own — no toast, no spinner, no “thank you”. Your site, your design, your words: listen to crm:lead and show whatever you like.
Form attributes
| Attribute | Example | What it does |
|---|---|---|
data-crm-lead | "quote_request" | Turns the form into a lead form. An empty attribute means the built-in lead_submit form, which works with no setup. A value is the name of your own form from Leads → Forms. |
data-crm-value | "149900" | Amount in minor units, an integer: 149900 is 1,499.00. Stored only if the form has “This form brings revenue” ticked. Not a number — neither the amount nor the currency is sent. |
data-crm-currency | "EUR" | Currency of the amount: EUR, USD, UAH… — 1 to 10 Latin letters or digits. Leave it out and the form's currency is used. |
data-crm-ignore | no value needed | Goes on a field or a wrapper (fieldset, div…), not on the form. The field — or everything inside the wrapper — is never sent. Don't put it on the form itself or on anything around the form — then not a single field is sent. See Fields that are never sent. |
Form events
Both events bubble, so you can listen on the form itself or once on document for every form on the page.
| Event | When | event.detail | Cancelable |
|---|---|---|---|
crm:lead-before | Right after submit, before the lead is sent | { name } — the form name | Yes: preventDefault() stops sending |
crm:lead | When sending is over: the server answered or couldn't be reached | { ok } — true if the lead was accepted | No |
document.addEventListener('crm:lead', (event) => {
if (event.detail.ok) {
event.target.closest('.modal')?.classList.add('is-thanks');
}
});Field names the CRM understands
A lead card has four main slots: name, phone, email and message. The server fills them by looking at field names. Names are trimmed and lowercased, then matched exactly against this list (so Phone works, your-phone does not):
| Slot | Field names that fill it | Limit |
|---|---|---|
| Name | name, fio, username, user_name, fullname, full_name, firstname, first_name, contact_name, client_name, имя, фио, ім'я | 200 characters |
| Phone | phone, tel, telephone, mobile, phone_number, contact_phone, телефон, тел | 7–20 digits |
email, e_mail, e-mail, mail, contact_email, почта, пошта, емейл | 320 characters | |
| Message | message, comment, comments, text, question, note, description, task, сообщение, комментарий, вопрос, повідомлення, коментар | 4000 characters |
- The first suitable field wins. If a form has both
phoneandmobile, the first one in the form fills the slot. - Everything else is kept too. Unknown fields and second matches go to “extra” and appear in the lead card in form order. Up to 30 extra fields; keys up to 60 characters, values up to 1000.
- A phone counts only with 7 to 20 digits. Spaces, brackets and dashes are fine. It is stored ready to dial — digits and a leading plus only:
+49 30 1234567becomes+49301234567. - An email counts only if it looks like an address (
name@domain.tld). Otherwise the value goes to “extra”. - A phone or an email is a must. A lead with neither is refused with
no_contact— there would be no way to reply.
Fields that are never sent
A lead card is for a name, a phone and a question — not for someone's password or card number. So the widget skips some fields on purpose, even when they sit inside a lead form:
- Password inputs — anything with
type="password". - Anything marked
data-crm-ignore— on the field itself or on any wrapper around it (fieldset,div…). Mark a wrapper and everything inside is skipped. - Fields with a sensitive name. The name is split into words (by
_,-,., camelCase and so on), and a field is skipped if it hascard,cc,csc,cvv,cvc,cvv2,cvc2,iban,ssn,secretorpassas a separate word — or ifpassword,passwd,pwd,token,csrf,xsrf,creditcard,cardnumber,cardnum,ccnum,ccnumber,cvvorcvcappears anywhere in the name with the separators removed.
| Field name | Sent? | Why |
|---|---|---|
card_number | no | card is a separate word |
cvv | no | a sensitive word on its own |
csrf_token | no | contains csrf and token |
user_password | no | contains password |
acc_num | no | without separators it is accnum, and that contains ccnum |
discard_reason | yes | card hides inside discard, but it isn't a separate word there |
A few more details:
- One name, one decision. If one field with a given name is excluded, every field with that name is excluded too.
- Hidden inputs are sent. Handy for passing the product, the plan or the page along with the lead — as long as their name isn't a sensitive one.
- The server double-checks. It applies the same filter on its side — for the browser routes and for leads sent from your server with a secret key alike — so a sensitive field never ends up in the CRM, whichever way it was sent.
<form data-crm-lead="signup_request">
<input name="name"> <!-- sent -->
<input name="email" type="email"> <!-- sent -->
<input name="plan" type="hidden" value="pro"> <!-- sent: hidden inputs are fine -->
<input name="account_pass" type="password"> <!-- never sent: a password input -->
<input name="card_number"> <!-- never sent: "card" is a separate word -->
<fieldset data-crm-ignore> <!-- nothing inside is sent -->
<input name="internal_note">
<input name="promo_hint">
</fieldset>
<button type="submit">Sign me up</button>
</form>Option B: send leads from JavaScript
When you own the form state — React, Vue, a multi-step wizard, a chatbot — call the widget directly. Both functions appear on window once widget.js has loaded (not inside an iframe). The widget takes the form pass by itself as soon as the visitor first touches a field of any form on the page — so a lead from your code doesn't look “filled in within a second”.
crmLead(name, fields, options)
const { ok } = await window.crmLead(
'callback_request',
{ name: 'Anna', phone: '+49 30 1234567', message: 'Call me after 5 pm, please' },
{ value: 149900, currency: 'EUR' },
);namestringrequiredlead_submit for the built-in one, or your own from Leads → Forms. Latin letters, digits and underscores, starting with a letter (^[A-Za-z][A-Za-z0-9_]*$). A name that doesn't fit gets a warning in the console and { ok: false }. The name of an analytics event gets { ok: false } here too.fieldsobjectrequiredoptions.valueintegeroptional149900 = 1,499.00. Stored only for forms with “This form brings revenue”.options.currencystringoptionalEUR: 1 to 10 Latin letters or digits. Leave it out and the form's currency is used.Every call is a separate lead with its own form pass: two different calls in a row make two leads. The same call with the same data while the first one is still on its way, and for a couple of seconds after (a double click), doesn't go out again — it returns the first call's answer.
Returns a Promise that resolves to:
okbooleantrue — the lead is accepted. false — it was refused or didn't get through; the reason is not reported, on purpose (see why).crmLeadForm(form, name)
Does exactly what the data-crm-lead attribute does, but from code. Handy when the form is rendered by a third-party library and you can't add attributes to it, or when the form name is decided at runtime. Returns nothing; results arrive through the same crm:lead event. Without a name, the form sends to the built-in lead_submit. Calling it again for a form that is already bound changes nothing.
const form = document.querySelector('#newsletter-popup form');
window.crmLeadForm(form, 'newsletter_signup');
form.addEventListener('crm:lead', (e) => {
if (e.detail.ok) form.innerHTML = '<p>You are in! Check your inbox.</p>';
});formHTMLFormElementrequirednamestringoptionalcrmLead. Leave it out for the built-in lead_submit.TypeScript declarations
The widget is a plain script, so TypeScript doesn't know about it. Drop this into any .d.ts file:
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;
}
}How spam protection works
A public form is a magnet for bots. You don't need a CAPTCHA to keep them out — the widget and the server handle it together, and real visitors never notice.
A one-time form pass
Before sending, the widget gets a signed “form pass” from the server. It takes one in advance — as soon as the visitor first touches a field of a form, any form on the page, including one that later sends its lead through crmLead. The time from that touch to sending is the fill-in time. A pass is:
- single-use — one pass, one lead; the widget takes a new one for the next send;
- bound to your site — a pass from one site is useless on another;
- valid for 24 hours — if the tab stays open longer, the widget takes a fresh one.
Bots that blindly POST to the endpoint have no pass and are refused. Repeating a request with the same pass returns { ok: true }, but the lead is stored once. Double clicks the widget filters out by itself: while the first submit is on its way, the second one doesn't go out.
The honeypot
The hidden company_site field from above. A human can't see it, so it stays empty. A bot that fills in every field it finds gives itself away, and the lead is refused.
“Suspicious” leads
Some leads look odd but might be real. Those are accepted and get a Suspicious label in the CRM, so a manager can take a look before calling:
- under 3 seconds passed from the first touch of the form to sending — faster than humanly possible;
- the form was open for more than 30 minutes before sending;
- more than 5 submissions came from one IP address within an hour — all of them count, rejected ones too.
A form sent without touching a single field (autofill, then straight to “Send”) is marked as fast too: in that case the pass is taken at the moment of sending. Leads sent from a server never get these labels.
“Spam” is a status a person sets by hand in the CRM. Nothing is marked as spam automatically, so no real customer is silently thrown away.
The IP address in the lead card is shown truncated — IPv4 loses its last number (203.0.113.57 → 203.0.113.0), IPv6 is cut to /48. The full address never reaches the database; for the spam-protection counters it is held in the server's memory for an hour at most. More in What we store and for how long.
Why the browser only gets ok: true or false
Telling a bot “refused: honeypot filled” is a free lesson in how to get through. So the page's code — crmLead() and the crm:lead event — only ever gets ok: true or ok: false, no reason given. Debugging your own form? You do get the reason: the CRM records it in “Recent rejections”, and setup errors — an undeclared name, a form sent to an analytics event, no phone and no email — also show in the Network tab: a 400 response with a message field. Protection refusals (no form pass, honeypot filled) come back as a plain { "ok": false }. The troubleshooting checklist covers the rest.
Under the hood: the browser request
For the curious — you never have to build this yourself. The widget gets a pass from POST https://back.sitecog.com/marketing/fk (answer: {"pass":"…"}), then sends the lead:
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": "…"
}Answers: { "ok": true } — the lead is accepted (or it is a repeat with the same pass); { "ok": false } — refused by the pass or honeypot check; errors in the lead itself come back as a 400 with a message field (see errors). If lead intake isn't configured on the server, /fk answers { "pass": null, "reason": "not_configured" }. vid and sid are the visitor and session ids, so the lead is linked to the ad channel the visitor came from — see Events & analytics.
Send leads from your server
Not every lead starts in a browser. Use the server route when:
- a manager takes an order by phone and enters it in your back office;
- your form is processed on the backend (a PHP handler, a Next.js server action) and you'd rather not depend on the widget;
- leads come from another system: a marketplace, a booking service, a bot.
POST https://back.sitecog.com/marketing/event
x-event-key: sk_…
Content-Type: application/jsonIt is the same address as for server events: the intake tells what arrived by the name. A lead form's name creates a lead, an analytics event's name records an event. But if the request carries form fields (fields) and the name belongs to an analytics event, that is an error, not an event: 400 not_lead_form. The old address https://back.sitecog.com/marketing/lead still works, but it accepts lead forms only.
Secret keys
The server route is authenticated with a secret key. You can issue one in two places — there is one list per site: CRM → Leads → Forms, the “From a server” tab of any form, or CRM → Marketing → Events, the “Secret keys” panel. Type a name and press “Issue a key”. A key looks like sk_ + 48 hex characters; a site can have up to 5 active keys, and any of them can be revoked. Give each key a name that says where it lives (“payment server”, “phone orders”) — future you will be grateful when it's time to revoke one.
Keys are visible to and issued by the owner or a manager who can edit Leads (or Marketing → Events). Someone with view-only access won't see the keys.
Example request
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 is built in
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}`, // a retry won't create a second lead
visitor_id: order.crmVid, // saved from the browser at checkout, if you have it
session_id: order.crmSid,
fields: {
name: order.customerName,
phone: order.phone,
message: order.comment,
delivery: order.deliveryMethod, // goes to "extra"
},
value: order.totalCents, // 149900 = 1,499.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}Request body
x-event-keyheaderstringrequiredsk_… from the CRM. Missing, revoked or the site is disabled → 401 invalid_key.namestringrequiredlead_submit for the built-in one, or your own from Leads → Forms. Short alias: n.fieldsobjectrequiredfields: then everything except the service keys from this table counts as a lead field. At the root, though, pass the person's name as full_name or fio — name there is the form name. Fields with sensitive names are filtered out here too, exactly as in the browser (the rules).event_idstring | numberoptionalid.visitor_idstringoptionalsession_idstringoptionalcrm_sid). With it, the lead inherits the ad channel and UTM tags of that session. Alias: sid.valueintegeroptional149900 = 1,499.00. Stored only for forms with “This form brings revenue”. Alias: val.currencystringoptionalEUR: 1 to 10 Latin letters or digits. Leave it out and the form's currency is used. Alias: cur.urlstringoptionalu.Response
{ "ok": true, "duplicate": false, "lead": true }okbooleanduplicatebooleantrue if this form already has a lead with this event_id. Nothing new was stored, and that's fine.leadbooleantrue — the request was accepted as a lead. The address is shared with analytics events, and an event's response has no such field. Sent a lead but got no lead back? The name belongs to an analytics event, and no lead card will appear.Unlike the browser, the server route doesn't use form passes or timing checks — the secret key is proof enough. The honeypot still applies: a non-empty company_site in fields gets 400 rejected.
Idempotency: retry without fear
Networks fail at the worst moments. Did the request go through or not? With event_id you don't have to know: send it again. A repeat returns {"ok":true,"duplicate":true} and the lead is not stored twice.
{ "ok": true, "duplicate": true, "lead": true }Attribution: which ad brought the lead
Leads from the widget are linked to the visitor automatically. A server lead knows nothing about the browser — unless you tell it. The widget keeps the visitor id in localStorage under crm_vid and the session id under crm_sid. Send them to your backend along with the form or order, and pass them on. Read them only once the visitor has agreed to analytics, and inside try/catch: storage may be blocked in the browser, and touching it then throws.
let crm = {};
try {
// Without consent mode, status() is always 'granted'
if (window.crmConsent?.status() === 'granted') {
crm = {
vid: localStorage.getItem('crm_vid'),
sid: localStorage.getItem('crm_sid'),
};
}
} catch {
// storage unavailable — the lead goes without attribution
}
await fetch('/api/orders', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ...order, crm }),
});
// …and on the server: visitor_id: body.crm.vid, session_id: body.crm.sidWith session_id, the lead inherits the ad channel, the ad link and the UTM tags of that session's first page view — you'll see them in the lead card, in the “Where it came from” block. More in Events & analytics.
Errors
From the browser, crmLead() and the crm:lead event only ever say ok: false. The server route answers with a status and a message:
| Status | Body | What happened |
|---|---|---|
| 400 | {"message":"unknown_event","name":"phone_order"} | No form with this name in the CRM. Create it in Leads → Forms (check the spelling and case) or restore it from the archive. |
| 400 | {"message":"not_lead_form","name":"purchase"} | A lead — with form fields (fields) or sent to the old /lead address — went to an analytics event's name. Create a lead form with a different name. |
| 400 | {"message":"invalid_event_name"} | There is no name, or it has characters outside Latin letters, digits and underscores, or doesn't start with a letter. |
| 400 | {"message":"no_contact"} | Neither a phone (7–20 digits) nor an email that looks like an address. |
| 400 | {"message":"invalid_body"} | The body is not a JSON object, or the request has the wrong Content-Type (it must be application/json). Broken JSON gets a 400 with the parser's error text. |
| 400 | {"message":"rejected"} | The honeypot field company_site is filled in. |
| 401 | {"message":"invalid_key"} | Missing, malformed or revoked x-event-key — or the site is disabled. |
| 413 | — | The body is bigger than 8 KB. |
| 429 | {"message":"rate_limit_exceeded"} | Too many requests this minute. Wait for the next one. |
Browser requests can also get 400 unknown_domain — the page's domain is not a site in the CRM, or the site is disabled — and 400 unknown_origin — the request has neither an Origin nor a Referer (say, the page was opened straight from a file). You'll see them in the Network tab, while the code still gets ok: false.
Limits
| What | Limit |
|---|---|
| Requests per IP (all marketing routes together) | 120 per minute |
| Requests per site | 6000 per minute |
| Form passes per IP | 20 per minute |
| Request body | 8 KB |
| Name / email / message | 200 / 320 / 4000 characters |
| Extra fields | up to 30; key up to 60, value up to 1000 characters |
| Phone | 7–20 digits to count as a contact |
event_id | up to 128 characters (longer is cut) |
| Secret keys | up to 5 active per site |
Windows are fixed minutes: after a 429, wait until the next minute starts. A real visitor will never get close; a script hammering your form will.
Troubleshooting
Recent rejections
The first place to look. At the bottom of CRM → Leads → Forms you'll find the submissions from your site that didn't become leads, each with its reason: when, from where (browser or server), under which name and from which page.
| Reason | What to do |
|---|---|
| Name not in the CRM | Create the form with the Create form “…” button right in the entry (it is shown to those who can edit Leads). If the name is archived, the entry says so: tick “Show archive” above the list and restore the form. |
| Sent to an analytics event | The name is taken by an event in Marketing → Events. Create a lead form with a different name and use that name on the site. |
Sent via crmTrack | crmTrack records analytics events only. For a form, use the data-crm-lead attribute or crmLead(). |
| No phone and no email | Check the field names against the table. |
| Invalid name | Latin letters, digits and underscores only, starting with a letter. |
| Honeypot filled | The hidden company_site field was filled in — that's what bots do. If it's a real field of yours, rename it. |
The CRM keeps the 50 latest rejections per site — shared by forms and events; the list disappears 7 days after the last rejection. The same rejection (same reason, same name, same source — browser or server) is recorded at most once a minute. The rejected leads themselves — phone, email, text — are not stored: only the trace remains. Bots that blindly POST to the endpoint — requests without a form pass — don't show up here unless they filled in the honeypot: that's not a problem with your form, just noise from outside. Rejected analytics events have a panel of their own, in Marketing → Events.
The lead didn't arrive
Check “Recent rejections” first. If it's empty, go down the list:
- The name isn't declared. There must be a form with exactly this name in Leads → Forms, case included. An empty
data-crm-leadis the built-inlead_submit: it appears by itself, but only on a plan with leads, and it doesn't come back from the archive on its own. - The name belongs to an analytics event. A lead under that name is refused: create a form with a different name.
- It was sent with
crmTrack. That doesn't create leads — use thedata-crm-leadattribute orcrmLead(). - No phone and no email. Or they are there, but under names the CRM doesn't know (
your-phone,contact[email]) and ended up in “extra”. Rename them — see the field table. A phone with fewer than 7 digits doesn't count either. - The data was in a file input. Files are ignored — the widget sends text only.
- A real field is called
company_site. That's the honeypot name; the lead is treated as a bot. - Your own
crm:lead-beforelistener calledpreventDefault()— maybe not when you expected. - The widget isn't on this page. Without
widget.jsthe attribute does nothing and the form submits the old-fashioned way (or not at all). - The form is in an iframe, the attribute was added later, or the form is sent with
form.submit(). In these cases the widget doesn't catch the form — see where the attribute doesn't work. data-crm-ignoresits on the form itself or on its wrapper. Then not a single field is sent, and the lead gets “no phone and no email”.- A Content Security Policy blocks it. If your site has a CSP, it needs
script-src https://widget.sitecog.comandconnect-src https://back.sitecog.com. The browser console will say so in red. - The domain isn't a site in the CRM. The site is recognized by the page's origin (
www.is stripped), exactly: a subdomain likeshop.example.comis a separate site. Testing onlocalhostor a staging domain that isn't added to the CRM givesunknown_domainin the Network tab. Just added the domain? Give it up to 5 minutes. - You were testing a lot. 20 form passes per minute per IP is plenty for people but not for frantic clicking. Wait a minute.
A field didn't arrive
The lead is there, but one of the fields isn't. Usually it was skipped on purpose:
- Its name looks sensitive. Check it against the sensitive-name rules:
promo_passhaspassas a separate word and is never sent. Rename it to something likepromo_codeand it comes through. - It sits under
data-crm-ignore. The attribute may be on a wrapper a few levels up — afieldsetor adivyou forgot about. - Another field with the same name is excluded. Then all fields with that name are skipped.
- It is a file input. Files are ignored anyway — the widget sends text only.
The amount isn't shown
The amount shows as a total for the last 30 days on the form's card in Leads → Forms; the lead card itself doesn't show it. Empty there too? Tick “This form brings revenue” on the form (the “Edit” icon next to it): amounts are stored for leads that arrive after that. Also check the amount is an integer in minor units: 1499.00 should be sent as 149900.
Notifications in Telegram
A lead nobody sees is a lead lost. Connect your own Telegram bot, and a notification about a new lead arrives within about half a minute, with a link to its card:
Create a bot and paste its token
Bots are created with@BotFather. In the CRM: Leads → “Lead settings” (in the section header), the “Bot token” field, the “Connect” button. One bot per site — every manager you pick gets notifications through it.Collect the recipients
Everyone who should get leads sends the bot/start(you can also add the bot to a team group). Then press “Refresh” in the “Who gets them” block and switch on the people you need: new ones appear switched off. Skip this step and nothing arrives.Turn notifications on and test
Tick “Send notifications” and, if you like, “Send suspicious ones too”, save, and press “Test connection”: the CRM tells you how many recipients the test message reached.
- Quiet hours hold notifications back, they don't throw them away: a lead that comes in at night arrives first thing in the morning. The window is shared by the site, but each recipient can have their own or none at all.
- Suspicious leads are never sent while that box is unticked — not right away, not in the morning. They are still in the CRM.
- If the bot has a webhook, the recipient list can't be collected: remove the webhook or use a separate bot for leads.
Notifications are formatted with HTML, and everything the visitor typed is escaped before it gets there. A “name” like <a href="…">Click here</a> arrives as plain text: a visitor can't disguise a link as text or break the formatting. An address typed into a field as is will be shown as a link by Telegram itself. Long fields are trimmed — the message to 500 characters, other fields to 200 — and the full lead is always in the CRM.
Deleting a person's data on request
“Please delete everything you have about me” is a normal request, and answering it shouldn't mean a week of digging through tables. The CRM has two tools for it — no code on your side.
From a lead or a chat
A lead card and a chat card both have “Delete this visitor's data”. Before anything is deleted, the CRM shows what exactly will go:
- the visitor profile and analytics — page views and events;
- chats and attachments — the number of chats, messages and files;
- leads — only if you tick “Also delete this visitor's leads”. Off by default: a lead is often a deal in progress, and the decision is yours.
A lead without visitor_id — sent from your server without one, or from the browser before the visitor consented in consent mode — isn't linked to a visitor, so only the lead itself can be deleted there.
By email or phone
Usually the request comes as an email: “I'm anna@example.com, forget me”. Go to CRM → Settings → “Data deletion requests”, enter the email or the phone the person gave, and the CRM finds their leads and chats (by email or phone) and their account on your site (by email only). The “Delete everything found” button deletes it all at once.
- Visit analytics. The “Also delete visit analytics of the related visitors” box is ticked by default — untick it if the analytics should stay.
- Chats go entirely. All chats of the found visitors are deleted, archived ones included, together with their attachments. Files inserted into your site's pages stay.
- Rights. Deleting needs the right to edit the matching section: leads — “Leads”, chats — “Support · Chats”, site accounts — “Site users · List”, analytics — “Marketing · Traffic”. A manager who can only view sees what was found but can't delete it.
- Audit log. Every deletion is written to the activity log — without the person's email or phone, otherwise the log would keep exactly what was asked to be forgotten.
- No undo. Deleted means deleted. Check the counts before you confirm.