Ein Kontaktformular, das an jemanden im Urlaub mailt, ist der Ort, an dem Leads sterben. Mit Sitecog landet jedes Formular deiner Website als Karte im CRM — mit Telefonnummer oder E-Mail, einem Status und jemandem, der zurückruft. Ein Attribut am <form> reicht; JavaScript- und Server-Varianten sind da, wenn du mehr Kontrolle brauchst.
Drei Wege, einen Lead zu senden — nimm, was passt:
- Ein Formular mit
data-crm-lead— null JavaScript. Das Widget fängt den Submit ab und erledigt den Rest. window.crmLead()— für React, Vue und jedes Formular, das du selbst steuerst.POST /marketing/eventvon deinem Server — telefonische Bestellungen, Backend-Formulare, Integrationen mit anderen Systemen.
Wie ein Lead vom Formular ins CRM kommt
Jedes Lead-Formular hat einen Namen. Eins hat deine Site schon: das integrierte lead_submit, im CRM „Anfrage über die Website“. Jedes Formular mit leerem Attribut data-crm-lead sendet seine Leads dorthin, und jede Einsendung wird zur Karte unter CRM → Leads — ohne einen einzigen Schritt im CRM. Das integrierte Formular gibt es auf jeder Site, deren Tarif Leads enthält.
- Ein Besucher füllt das Formular aus und drückt „Senden“.
- Das Widget sammelt die Felder des Formulars ein und schickt sie ab; welches davon Name, Telefon, E-Mail und Nachricht ist, entscheidet der Server.
- Der Server prüft, ob es dieses Formular gibt, ob der Lead eine Telefonnummer oder E-Mail hat und nicht nach Bot aussieht.
- Im CRM erscheint eine Lead-Karte — und, falls eingerichtet, eine Benachrichtigung in Telegram.
Zwei Regeln, die du dir von Anfang an merken solltest:
- Ein nicht angelegter Name wird abgelehnt. Das CRM nimmt nur Formulare an, die es kennt — kein überraschender Müll durch Tippfehler. Von selbst entsteht nur das integrierte
lead_submit. - Lead-Formulare und Analytics-Events werden nie vermischt. Ein Lead, der unter dem Namen eines Analytics-Events gesendet wird, wird abgelehnt, und
crmTrackmit dem Namen eines Lead-Formulars zeichnet nichts auf. Jede solche Ablehnung zeigt dir das CRM unter „Letzte Ablehnungen“.
Eigene Formulare im CRM anlegen
Das integrierte Formular reicht, solange auf deiner Site nur eine Art von Anfrage ankommt. Du willst „Rückruf anfordern“ von „Angebot anfordern“ unterscheiden — in der Lead-Liste, im Filter und in den Zählern auf der Seite „Formulare“? Dann gib jedem Formular einen eigenen Namen. Ein paar Klicks, einmal pro Formulartyp:
Leads → Formulare öffnen
Der Button „Formulare“ oben im Bereich Leads führt zur Seite „Lead-Formulare“: Hier stehen alle Lead-Formulare der Site und wie viele Leads jedes davon in den letzten 30 Tagen gebracht hat. Archivierte Formulare siehst du mit dem Haken „Archiv anzeigen“.Auf „Neues Formular“ klicken
Gib ihm den Namen, den dein Code verwenden wird: lateinische Buchstaben, Ziffern und Unterstriche, beginnend mit einem Buchstaben —callback_request,quote_request. Den Namen kannst du später nicht mehr ändern — prüf die Schreibweise.Optional: Haken bei „Dieses Formular bringt Umsatz“
Nur dann werden Betrag und Währung des Leads gespeichert. Ohne den Haken werden sie stillschweigend ignoriert.Den Namen auf der Site einsetzen
data-crm-lead="callback_request"am Formular,crmLead('callback_request', …)im Code oder"name": "callback_request"im Request von deinem Server. Fertigen Code für alle drei Wege zeigt dir das CRM auf der Seite des Formulars.
Variante A: ein Formular mit einem Attribut
Setz das Attribut data-crm-lead an ein beliebiges Formular auf einer Seite mit dem Widget-Script. Das ist die ganze Integration. Ein leeres Attribut sendet den Lead an das integrierte Formular lead_submit, ein Wert an dein eigenes Formular mit diesem Namen (data-crm-lead="quote_request"). Formulare, die später auftauchen — in einem Modal, nach einem Routenwechsel in einer Single-Page-App —, werden automatisch erkannt, wenn sie schon mit dem Attribut in die Seite eingefügt werden.
<form data-crm-lead>
<input name="name">
<input name="phone" type="tel">
<textarea name="message"></textarea>
<button type="submit">Senden</button>
</form>Komplettes Beispiel
Ein „Angebot anfordern“-Formular (quote_request, angelegt unter Leads → Formulare mit dem Haken „Dieses Formular bringt Umsatz“) mit Name, Telefon, E-Mail und Nachricht, einem Bestellbetrag (die Summe pro Formular steht auf seiner Karte unter Leads → Formulare), einer Danke-Nachricht und einer eigenen Prüfung. Erst reines HTML; die React- und Vue-Versionen rufen crmLead() aus ihrem eigenen Submit-Handler auf.
<form id="quote" data-crm-lead="quote_request" data-crm-value="149900" data-crm-currency="EUR">
<label>Dein Name <input name="name" autocomplete="name" required></label>
<label>Telefon <input name="phone" type="tel" autocomplete="tel"></label>
<label>E-Mail <input name="email" type="email" autocomplete="email"></label>
<label>Was brauchst du? <textarea name="message" rows="4"></textarea></label>
<!-- Keins der bekannten Felder: erscheint so, wie es ist, in der Lead-Karte -->
<label>Teamgröße
<select name="team_size">
<option>1–5</option>
<option>6–20</option>
<option>20+</option>
</select>
</label>
<button type="submit">Anfrage senden</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. Vor dem Senden: unsere eigene Prüfung. preventDefault() = nichts wird gesendet
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('Bitte hinterlass eine Telefonnummer oder E-Mail, damit wir antworten können.');
return;
}
button.disabled = true;
});
// 2. Nach dem Senden: Das Widget zeigt nichts an, das „Danke“ kommt von uns
form.addEventListener('crm:lead', (event) => {
button.disabled = false;
say(event.detail.ok
? 'Danke! Wir melden uns innerhalb eines Werktags.'
: 'Da ist etwas schiefgelaufen. Versuch es bitte noch mal oder ruf uns an.');
});
</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 wirft nie; undefined ist es nur, wenn widget.js nicht auf der Seite ist
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>Danke! Wir melden uns innerhalb eines Werktags.</p>;
// Hier kein data-crm-lead: Dieses Formular sendet selbst über crmLead
return (
<form onSubmit={onSubmit}>
<input value={form.name} onChange={set('name')} placeholder="Dein Name" required />
<input value={form.phone} onChange={set('phone')} type="tel" placeholder="Telefon" />
<input value={form.email} onChange={set('email')} type="email" placeholder="E-Mail" />
<textarea value={form.message} onChange={set('message')} placeholder="Was brauchst du?" />
<button disabled={status === 'sending'}>Anfrage senden</button>
{status === 'error' && <p role="alert">Bitte hinterlass Telefon oder E-Mail und versuch es noch mal.</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 wirft nie; undefined ist es nur, wenn widget.js nicht auf der Seite ist
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'">Danke! Wir melden uns innerhalb eines Werktags.</p>
<!-- Hier kein data-crm-lead: Dieses Formular sendet selbst über crmLead -->
<form v-else @submit.prevent="submit">
<input v-model="form.name" placeholder="Dein Name" required />
<input v-model="form.phone" type="tel" placeholder="Telefon" />
<input v-model="form.email" type="email" placeholder="E-Mail" />
<textarea v-model="form.message" placeholder="Was brauchst du?" />
<button :disabled="status === 'sending'">Anfrage senden</button>
<p v-if="status === 'error'" role="alert">Bitte hinterlass Telefon oder E-Mail und versuch es noch mal.</p>
</form>
</template>Was beim Absenden des Formulars passiert
- Das Widget bricht den nativen Submit ab — per Button, mit der Enter-Taste oder über
form.requestSubmit(): Die Seite lädt nicht neu, und dieactiondes Formulars wird nicht genutzt. - Es feuert
crm:lead-befoream Formular. Ruft irgendein Listenerevent.preventDefault()auf, ist die Geschichte hier zu Ende, und nichts wird gesendet. - Es sammelt die Felder mit
FormDataein — außer den ausgeschlossenen. Es zählen nur Textwerte: Datei-Inputs werden ignoriert. Mehrere Felder mit demselben Namen (eine Gruppe Checkboxen) werden mit", "verbunden. Der Wert des gedrückten Buttons wird nicht gesendet — brauchst du ihn, gib ihn über ein verstecktes Feld mit. - Es sendet den Lead, geschützt durch einen einmaligen Formular-Pass (mehr dazu unter Spamschutz). Ein erneuter Submit desselben Formulars, während der erste noch läuft — ein Doppelklick —, wird nicht gesendet.
- Wenn das Senden abgeschlossen ist — der Server hat geantwortet oder war nicht erreichbar —, feuert es
crm:leadmit{ ok: true }oder{ ok: false }inevent.detail. - Ist
oktrue, ruft esform.reset()auf. Bei einem Fehler bleibt das Formular, wie es ist, damit der Besucher nicht verliert, was er getippt hat.
Das Widget zeigt keine eigene UI — keinen Toast, keinen Spinner, kein „Danke“. Deine Site, dein Design, deine Worte: Hör auf crm:lead und zeig, was du willst.
Formular-Attribute
| Attribut | Beispiel | Was es tut |
|---|---|---|
data-crm-lead | "quote_request" | Macht das Formular zum Lead-Formular. Ein leeres Attribut steht für das integrierte Formular lead_submit, das ohne Einrichtung funktioniert. Ein Wert ist der Name deines Formulars aus Leads → Formulare. |
data-crm-value | "149900" | Betrag in kleinsten Einheiten, eine Ganzzahl: 149900 sind 1.499,00. Wird nur gespeichert, wenn beim Formular „Dieses Formular bringt Umsatz“ gesetzt ist. Ist der Wert keine Zahl, werden weder Betrag noch Währung gesendet. |
data-crm-currency | "EUR" | Währung des Betrags: EUR, USD, UAH… — 1 bis 10 lateinische Buchstaben oder Ziffern. Fehlt sie, gilt die Währung des Formulars. |
data-crm-ignore | (ohne Wert) | Gehört nicht ans Formular, sondern an ein Feld oder einen Wrapper (<fieldset>, <div>…): Das Feld bzw. alles darin wird nie gesendet. Nicht an das Formular selbst oder einen seiner Vorfahren setzen — dann wird kein einziges Feld gesendet. Siehe Felder, die nie gesendet werden. |
Formular-Events
Beide Events bubbeln, du kannst also am Formular selbst lauschen oder einmal an document für alle Formulare der Seite.
| Event | Wann | event.detail | Abbrechbar |
|---|---|---|---|
crm:lead-before | Direkt nach dem Submit, bevor der Lead gesendet wird | { name } — der Formularname | Ja: preventDefault() stoppt das Senden |
crm:lead | Wenn das Senden abgeschlossen ist: Der Server hat geantwortet oder war nicht erreichbar | { ok } — true, wenn der Lead angenommen wurde | Nein |
document.addEventListener('crm:lead', (event) => {
if (event.detail.ok) {
event.target.closest('.modal')?.classList.add('is-thanks');
}
});Feldnamen, die das CRM versteht
Eine Lead-Karte hat vier Hauptfelder: Name, Telefon, E-Mail und Nachricht. Der Server füllt sie anhand der Feldnamen. Die Namen werden getrimmt und kleingeschrieben und dann exakt mit dieser Liste verglichen (Phone funktioniert also, your-phone nicht):
| Feld | Feldnamen, die es füllen | Limit |
|---|---|---|
| Name | name, fio, username, user_name, fullname, full_name, firstname, first_name, contact_name, client_name, имя, фио, ім'я | 200 Zeichen |
| Telefon | phone, tel, telephone, mobile, phone_number, contact_phone, телефон, тел | 7–20 Ziffern |
email, e_mail, e-mail, mail, contact_email, почта, пошта, емейл | 320 Zeichen | |
| Nachricht | message, comment, comments, text, question, note, description, task, сообщение, комментарий, вопрос, повідомлення, коментар | 4000 Zeichen |
- Das erste passende Feld gewinnt. Hat ein Formular sowohl
phoneals auchmobile, füllt das erste im Formular das Feld. - Alles andere bleibt auch erhalten. Unbekannte Felder und zweite Treffer landen in „Zusätzlich“ und erscheinen in der Lead-Karte in Formular-Reihenfolge. Bis zu 30 Zusatzfelder; Keys bis 60 Zeichen, Werte bis 1000.
- Eine Telefonnummer zählt nur mit 7 bis 20 Ziffern. Leerzeichen, Klammern und Bindestriche sind okay. Gespeichert wird sie so, wie man sie wählt — nur Ziffern und ein führendes
+: Aus+49 30 1234567wird+49301234567. - Eine E-Mail zählt nur, wenn sie wie eine Adresse aussieht (
name@domain.tld). Sonst landet der Wert in „Zusätzlich“. - Telefon oder E-Mail ist Pflicht. Ein Lead ohne beides wird mit
no_contactabgelehnt — es gäbe keinen Weg, zu antworten.
Felder, die nie gesendet werden
Manche Daten haben in einem CRM nichts verloren — Passwörter, Kartennummern, CSRF-Tokens. Das Widget lässt sie weg, bevor irgendetwas das Formular verlässt:
- Passwortfelder — jedes
<input type="password">. - Alles mit
data-crm-ignore— am Feld selbst oder an einem beliebigen Wrapper (<fieldset>,<div>…). Dann wird alles darin übersprungen. - Felder mit sensiblem Namen. Als eigenes Wort im Namen (getrennt durch
_,-,.oder camelCase):card,cc,csc,cvv,cvc,cvv2,cvc2,iban,ssn,secret,pass. Irgendwo im Namen, ohne Trennzeichen zusammengeschrieben:password,passwd,pwd,token,csrf,xsrf,creditcard,cardnumber,cardnum,ccnum,ccnumber,cvv,cvc.
Ein paar Beispiele: card_number ✗, cvv ✗, csrf_token ✗, user_password ✗, acc_num ✗ (ohne Trennzeichen accnum, und darin steckt ccnum) — aber discard_reason ✓, denn dort ist „card“ kein eigenes Wort.
- Ein Name, ein Urteil. Ist ein Feld mit einem bestimmten Namen ausgeschlossen, sind es alle Felder mit diesem Namen.
- Versteckte Inputs werden gesendet — praktisch für Produkt, Tarif oder Seite. Es sei denn, ihr Name ist sensibel.
<form data-crm-lead="signup_request">
<input name="email" type="email"> <!-- ✓ gesendet -->
<input name="password" type="password"> <!-- ✗ Passwortfeld -->
<input type="hidden" name="plan" value="pro"> <!-- ✓ versteckt, aber gesendet -->
<fieldset data-crm-ignore> <!-- ✗ alles hier drin -->
<input name="billing_address">
<input name="vat_id">
</fieldset>
<input name="card_number"> <!-- ✗ „card“ als eigenes Wort -->
<input name="discard_reason"> <!-- ✓ hier ist „card“ kein eigenes Wort -->
<button type="submit">Registrieren</button>
</form>Dieselbe Namensregel gilt für die Keys von crmLead(). Und der Server filtert genauso — auch bei Leads von deinem Server mit geheimem Schlüssel. Ein sensibles Feld landet also nie im CRM, egal auf welchem Weg es kommt.
Variante B: Leads aus JavaScript senden
Wenn du den Formular-State selbst hältst — React, Vue, ein mehrstufiger Wizard, ein Chatbot —, ruf das Widget direkt auf. Beide Funktionen erscheinen auf window, sobald widget.js geladen ist (in einem iframe gibt es sie nicht). Den Formular-Pass holt sich das Widget selbst, sobald der Besucher zum ersten Mal ein Feld irgendeines Formulars auf der Seite berührt — so sieht ein Lead aus deinem Code nicht aus wie „in einer Sekunde ausgefüllt“.
crmLead(name, fields, options)
const { ok } = await window.crmLead(
'callback_request',
{ name: 'Anna', phone: '+49 30 1234567', message: 'Bitte ruf mich nach 17 Uhr an' },
{ value: 149900, currency: 'EUR' },
);namestringPflichtlead_submit für das integrierte oder dein eigenes aus Leads → Formulare. Lateinische Buchstaben, Ziffern und Unterstriche, beginnend mit einem Buchstaben (^[A-Za-z][A-Za-z0-9_]*$). Ein Name, der nicht passt, bringt eine Warnung in der Konsole und { ok: false }. Der Name eines Analytics-Events liefert hier ebenfalls { ok: false }.fieldsobjectPflichtoptions.valueintegeroptional149900 = 1.499,00. Wird nur bei Formularen mit „Dieses Formular bringt Umsatz“ gespeichert.options.currencystringoptionalEUR: 1 bis 10 lateinische Buchstaben oder Ziffern. Fehlt sie, gilt die Währung des Formulars.Jeder Aufruf ist ein eigener Lead mit eigenem Pass: Zwei verschiedene Aufrufe hintereinander ergeben zwei Leads. Derselbe Aufruf mit denselben Daten, solange der erste noch unterwegs ist, und ein paar Sekunden danach (Doppelklick) wird nicht noch einmal gesendet — er liefert die Antwort des ersten.
Gibt ein Promise zurück, das aufgelöst wird zu:
okbooleantrue — der Lead ist angenommen. false — er wurde abgelehnt oder ist nicht durchgekommen; den Grund verraten wir absichtlich nicht (siehe warum).crmLeadForm(form, name)
Macht genau das, was das Attribut data-crm-lead macht, nur aus dem Code. Praktisch, wenn das Formular von einer Fremdbibliothek gerendert wird und du keine Attribute ergänzen kannst, oder wenn der Formularname erst zur Laufzeit feststeht. Gibt nichts zurück; Ergebnisse kommen über dasselbe crm:lead-Event. Ohne Namen sendet das Formular an das integrierte lead_submit. Ein Formular, das schon verbunden ist, ändert ein erneuter Aufruf nicht.
const form = document.querySelector('#newsletter-popup form');
window.crmLeadForm(form, 'newsletter_signup');
form.addEventListener('crm:lead', (e) => {
if (e.detail.ok) form.innerHTML = '<p>Du bist dabei! Schau in dein Postfach.</p>';
});formHTMLFormElementPflichtnamestringoptionalcrmLead. Ohne Namen: das integrierte lead_submit.TypeScript-Deklarationen
Das Widget ist ein einfaches Script, TypeScript weiß also nichts davon. Pack das in eine beliebige .d.ts-Datei:
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;
}
}Wie der Spamschutz funktioniert
Ein öffentliches Formular zieht Bots an wie ein Magnet. Ein CAPTCHA brauchst du trotzdem nicht — Widget und Server erledigen das gemeinsam, und echte Besucher merken nichts davon.
Ein einmaliger Formular-Pass
Vor dem Senden holt sich das Widget einen signierten „Formular-Pass“ vom Server. Es holt ihn im Voraus — sobald der Besucher zum ersten Mal ein Feld berührt, in irgendeinem Formular auf der Seite, auch in einem, das den Lead später über crmLead sendet. Die Zeit von dieser Berührung bis zum Senden ist die Ausfüllzeit. Ein Pass ist:
- einmalig — ein Pass, ein Lead; fürs nächste Senden holt das Widget einen neuen;
- an deine Site gebunden — ein Pass von einer Site ist auf einer anderen nutzlos;
- 24 Stunden gültig — ist der Tab länger offen, holt das Widget einen frischen.
Bots, die blind an den Endpoint POSTen, haben keinen Pass und werden abgelehnt. Eine Wiederholung des Requests mit demselben Pass liefert { ok: true }, der Lead wird aber nur einmal gespeichert. Einen Doppelklick auf den Button fängt das Widget selbst ab: Solange das erste Senden läuft, geht das zweite nicht raus.
Der Honeypot
Das versteckte Feld company_site von oben. Ein Mensch sieht es nicht, also bleibt es leer. Ein Bot, der jedes Feld ausfüllt, das er findet, verrät sich selbst, und der Lead wird abgelehnt.
„Verdächtige“ Leads
Manche Leads sehen seltsam aus, könnten aber echt sein. Die werden angenommen und bekommen im CRM das Label Verdächtig, damit ein Manager vor dem Anruf kurz draufschauen kann:
- zwischen der ersten Berührung des Formulars und dem Absenden lagen weniger als 3 Sekunden — schneller als menschenmöglich;
- das Formular war vor dem Absenden länger als 30 Minuten offen;
- mehr als 5 Einsendungen kamen innerhalb einer Stunde von derselben IP-Adresse — alle zählen, auch abgelehnte.
Ein Formular, das ganz ohne Berührung der Felder abgeschickt wird (Autofill und sofort „Senden“), markiert das Widget ebenfalls als zu schnell: Der Pass wird in diesem Fall erst beim Absenden geholt. Leads vom Server bekommen keine Markierungen.
Die IP-Adresse, die du in der Lead-Karte siehst, ist übrigens gekürzt: Bei IPv4 ist das letzte Oktett genullt, IPv6 ist auf /48 abgeschnitten. In die Datenbank kommt die volle Adresse nicht; für die Zähler des Spamschutzes hält der Server sie höchstens eine Stunde im Speicher. Mehr dazu unter Was wir speichern und wie lange.
„Spam“ ist ein Status, den ein Mensch im CRM von Hand setzt. Nichts wird automatisch als Spam markiert, also fliegt kein echter Kunde stillschweigend raus.
Warum der Browser nur ok: true oder false bekommt
Einem Bot „abgelehnt: Honeypot ausgefüllt“ zu sagen, ist eine Gratis-Lektion, wie man durchkommt. Deshalb bekommt der Code der Seite — crmLead() und das Event crm:lead — nur ok: true oder ok: false, ohne Grund. Du debuggst dein eigenes Formular? Den Grund siehst du trotzdem: Das CRM trägt ihn unter „Letzte Ablehnungen“ ein, und Konfigurationsfehler — ein nicht angelegter Name, ein Formular an ein Analytics-Event, weder Telefon noch E-Mail — siehst du auch im Network-Tab: eine 400-Antwort mit dem Feld message. Ablehnungen durch den Schutz (kein Pass, Honeypot ausgefüllt) kommen als schlichtes { "ok": false }. Die Checkliste zur Fehlersuche deckt den Rest ab.
Unter der Haube: der Browser-Request
Für Neugierige — selbst bauen musst du das nie. Das Widget holt sich einen Pass über POST https://back.sitecog.com/marketing/fk (Antwort: {"pass":"…"}) und sendet dann den 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": "…"
}Antworten: { "ok": true } — der Lead ist angenommen (oder es ist eine Wiederholung mit demselben Pass); { "ok": false } — abgelehnt bei der Prüfung von Pass oder Honeypot; Fehler im Lead selbst kommen als 400 mit dem Feld message (siehe Fehler). Ist der Lead-Empfang auf dem Server nicht eingerichtet, antwortet /fk mit { "pass": null, "reason": "not_configured" }. vid und sid sind die IDs von Besucher und Session, damit der Lead mit dem Werbekanal verknüpft wird, über den der Besucher kam — siehe Events & Analytics.
Leads von deinem Server senden
Nicht jeder Lead beginnt im Browser. Nimm die Server-Route, wenn:
- ein Manager eine Bestellung am Telefon annimmt und in dein Backoffice eintippt;
- dein Formular im Backend verarbeitet wird (ein PHP-Handler, eine Next.js Server Action) und du nicht vom Widget abhängen willst;
- Leads aus einem anderen System kommen: einem Marktplatz, einem Buchungsservice, einem Bot.
POST https://back.sitecog.com/marketing/event
x-event-key: sk_…
Content-Type: application/jsonDas ist dieselbe Adresse wie bei den Server-Events: Der Server erkennt am Namen, was ankommt. Der Name eines Lead-Formulars erzeugt einen Lead, der Name eines Analytics-Events ein Event. Enthält der Request aber Formularfelder (fields) und gehört der Name einem Analytics-Event, ist das ein Fehler und kein Event: 400 not_lead_form. Die bisherige Adresse https://back.sitecog.com/marketing/lead funktioniert weiterhin, nimmt aber nur Lead-Formulare an.
Geheime Schlüssel
Die Server-Route authentifiziert sich mit einem geheimen Schlüssel. Ausstellen kannst du ihn an zwei Stellen — die Liste ist eine pro Site: CRM → Leads → Formulare, Tab „Vom Server“ bei jedem Formular, oder CRM → Marketing → Ereignisse, Panel „Geheime Schlüssel“. Gib einen Namen ein und klick auf „Schlüssel ausstellen“. Ein Schlüssel sieht aus wie sk_ + 48 Hex-Zeichen; eine Site kann bis zu 5 aktive Schlüssel haben, und jeder davon lässt sich widerrufen. Gib jedem Schlüssel einen Namen, der sagt, wo er lebt („Payment-Server“, „Telefonbestellungen“) — dein zukünftiges Ich wird es dir danken, wenn einer widerrufen werden muss.
Sehen und ausstellen kann Schlüssel der Inhaber oder ein Manager, der „Leads“ (oder „Marketing → Ereignisse“) bearbeiten darf. Wer nur ansehen darf, sieht keine Schlüssel.
Beispiel-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": "Zwei Paar Air 3, Graphit. Lieferung ins Büro."
},
"value": 149900,
"currency": "EUR",
"url": "https://shop.example/contacts"
}'// Node 18+ — fetch ist eingebaut
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}`, // ein Retry erzeugt keinen zweiten Lead
visitor_id: order.crmVid, // beim Checkout aus dem Browser gespeichert, falls vorhanden
session_id: order.crmSid,
fields: {
name: order.customerName,
phone: order.phone,
message: order.comment,
delivery: order.deliveryMethod, // landet in „Zusätzlich“
},
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": "Zwei Paar Air 3, Graphit.",
},
"value": 149900,
"currency": "EUR",
},
timeout=10,
)
res.raise_for_status()
print(res.json()) # {'ok': True, 'duplicate': False, 'lead': True}Request-Body
x-event-keyheaderstringPflichtsk_… aus dem CRM. Fehlt er, ist er widerrufen oder ist die Site deaktiviert → 401 invalid_key.namestringPflichtlead_submit für das integrierte oder dein eigenes aus Leads → Formulare. Kurzer Alias: n.fieldsobjectPflichtfields: Dann zählt alles außer den Service-Keys dieser Tabelle als Feld des Leads. Den Namen der Person gibst du dort aber als full_name oder fio mit — name ist dort der Formularname. Felder mit sensiblem Namen filtert der Server auch hier heraus — siehe Felder, die nie gesendet werden.event_idstring | numberoptionalid.visitor_idstringoptionalsession_idstringoptionalcrm_sid). Damit erbt der Lead Werbekanal und UTM-Tags dieser Session. Alias: sid.valueintegeroptional149900 = 1.499,00. Wird nur bei Formularen mit „Dieses Formular bringt Umsatz“ gespeichert. Alias: val.currencystringoptionalEUR: 1 bis 10 lateinische Buchstaben oder Ziffern. Fehlt sie, gilt die Währung des Formulars. Alias: cur.urlstringoptionalu.Response
{ "ok": true, "duplicate": false, "lead": true }okbooleanduplicatebooleantrue, wenn es bei diesem Formular schon einen Lead mit dieser event_id gibt. Nichts Neues wurde gespeichert, und das ist in Ordnung.leadbooleantrue — der Request wurde als Lead angenommen. Die Adresse teilen sich Leads und Analytics-Events, und bei einem Event fehlt dieses Feld in der Antwort. Du hast einen Lead gesendet, aber lead fehlt? Dann gehört der Name einem Analytics-Event — eine Lead-Karte gibt es nicht.Anders als der Browser nutzt die Server-Route weder Formular-Pässe noch Zeitprüfungen — der geheime Schlüssel ist Beweis genug. Der Honeypot gilt trotzdem: Ein nicht leeres company_site in fields bekommt 400 rejected.
Idempotenz: Retry ohne Angst
Netzwerke fallen im ungünstigsten Moment aus. Ist der Request durchgegangen oder nicht? Mit event_id musst du das nicht wissen: Schick ihn einfach noch mal. Eine Wiederholung liefert {"ok":true,"duplicate":true}, und der Lead wird nicht doppelt gespeichert.
{ "ok": true, "duplicate": true, "lead": true }Attribution: welche Anzeige den Lead gebracht hat
Leads aus dem Widget werden automatisch mit dem Besucher verknüpft. Ein Server-Lead weiß nichts über den Browser — es sei denn, du sagst es ihm. Das Widget legt die Besucher-ID in localStorage unter crm_vid ab und die Session-ID unter crm_sid. Schick sie zusammen mit dem Formular oder der Bestellung an dein Backend und reich sie weiter. Lies sie nur, wenn der Besucher der Statistik zugestimmt hat, und in einem try/catch: Der Speicher im Browser kann gesperrt sein, und der Zugriff darauf wirft dann eine Exception.
let crm = {};
try {
// Ohne Consent-Modus liefert status() immer 'granted'
if (window.crmConsent?.status() === 'granted') {
crm = {
vid: localStorage.getItem('crm_vid'),
sid: localStorage.getItem('crm_sid'),
};
}
} catch {
// Speicher nicht verfügbar — der Lead geht ohne Attribution raus
}
await fetch('/api/orders', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ...order, crm }),
});
// …und auf dem Server: visitor_id: body.crm.vid, session_id: body.crm.sidMit session_id erbt der Lead Werbekanal, Werbelink und UTM-Tags des ersten Seitenaufrufs dieser Session — du siehst sie in der Lead-Karte im Block „Herkunft“. Mehr dazu unter Events & Analytics.
Fehler
Aus dem Browser sagen crmLead() und das crm:lead-Event immer nur ok: false. Die Server-Route antwortet mit einem Status und einer message:
| Status | Body | Was passiert ist |
|---|---|---|
| 400 | {"message":"unknown_event","name":"phone_order"} | Kein Formular mit diesem Namen im CRM. Leg es unter Leads → Formulare an (prüf Schreibweise und Groß-/Kleinschreibung) oder stell es aus dem Archiv wieder her. |
| 400 | {"message":"not_lead_form","name":"purchase"} | Ein Lead — mit Formularfeldern (fields) oder an die bisherige Adresse /lead — wurde an den Namen eines Analytics-Events gesendet. Leg ein Lead-Formular mit einem anderen Namen an. |
| 400 | {"message":"invalid_event_name"} | Der Name fehlt, enthält Zeichen außer lateinischen Buchstaben, Ziffern und Unterstrichen oder beginnt nicht mit einem Buchstaben. |
| 400 | {"message":"no_contact"} | Weder eine Telefonnummer (7–20 Ziffern) noch eine E-Mail, die wie eine Adresse aussieht. |
| 400 | {"message":"invalid_body"} | Der Body ist kein JSON-Objekt, oder der Request hat einen unpassenden Content-Type (nötig ist application/json). Kaputtes JSON bekommt eine 400 mit dem Text des Parser-Fehlers. |
| 400 | {"message":"rejected"} | Das Honeypot-Feld company_site ist ausgefüllt. |
| 401 | {"message":"invalid_key"} | x-event-key fehlt, ist fehlerhaft, widerrufen — oder die Site ist deaktiviert. |
| 413 | — | Der Body ist größer als 8 KB. |
| 429 | {"message":"rate_limit_exceeded"} | Zu viele Requests in dieser Minute. Warte auf die nächste. |
Browser-Requests können außerdem 400 unknown_domain bekommen — die Domain der Seite ist keine Site im CRM oder deaktiviert — und 400 unknown_origin — der Request hat weder Origin noch Referer (etwa wenn die Seite direkt aus einer Datei geöffnet wurde). Die siehst du im Network-Tab, während der Code weiterhin ok: false bekommt.
Limits
| Was | Limit |
|---|---|
| Requests pro IP (alle Marketing-Routen zusammen) | 120 pro Minute |
| Requests pro Site | 6000 pro Minute |
| Formular-Pässe pro IP | 20 pro Minute |
| Request-Body | 8 KB |
| Name / E-Mail / Nachricht | 200 / 320 / 4000 Zeichen |
| Zusatzfelder | bis zu 30; Key bis 60, Wert bis 1000 Zeichen |
| Telefon | 7–20 Ziffern, um als Kontakt zu zählen |
event_id | bis 128 Zeichen (Längeres wird abgeschnitten) |
| Geheime Schlüssel | bis zu 5 aktive pro Site |
Die Zeitfenster sind feste Minuten: Nach einer 429 wartest du, bis die nächste Minute beginnt. Ein echter Besucher kommt nie in die Nähe; ein Script, das auf dein Formular einhämmert, schon.
Fehlersuche
Letzte Ablehnungen
Der erste Ort, an dem du nachsehen solltest. Ganz unten auf der Seite CRM → Leads → Formulare stehen die Einsendungen deiner Site, die nicht zu Leads wurden, jeweils mit Grund: wann, woher (Browser oder Server), unter welchem Namen und von welcher Seite.
| Grund | Was tun |
|---|---|
| Name nicht im CRM | Leg das Formular an — mit dem Button Formular „…“ anlegen direkt im Eintrag (sichtbar für alle, die „Leads“ bearbeiten dürfen). Liegt der Name im Archiv, sagt dir das der Eintrag: Stell das Formular aus dem Archiv wieder her (Haken bei „Archiv anzeigen“ über der Liste). |
| An ein Analytics-Event gesendet | Der Name gehört einem Event aus Marketing → Ereignisse. Leg ein Lead-Formular mit einem anderen Namen an und setz diesen auf der Site ein. |
Über crmTrack gesendet | crmTrack schreibt nur Analytics-Events. Für ein Formular nimm das Attribut data-crm-lead oder crmLead(). |
| Weder Telefon noch E-Mail | Prüf die Feldnamen anhand der Tabelle. |
| Ungültiger Name | Nur lateinische Buchstaben, Ziffern und Unterstriche, beginnend mit einem Buchstaben. |
| Honeypot ausgefüllt | Das versteckte Feld company_site war ausgefüllt — so senden Bots. Ist es eines deiner echten Felder, benenn es um. |
Gespeichert werden die letzten 50 Ablehnungen der Site — gemeinsam für Formulare und Events; die Liste verschwindet 7 Tage nach der letzten Ablehnung. Dieselbe Ablehnung (gleicher Grund, gleicher Name, gleiche Quelle — Browser oder Server) wird höchstens einmal pro Minute eingetragen. Die abgelehnten Leads selbst — Telefon, E-Mail, Text — werden nicht gespeichert, nur ihre Spur. Requests ohne Formular-Pass, also am Widget vorbei, tauchen hier nicht auf, es sei denn, der Honeypot ist ausgefüllt: Das ist kein Problem deines Formulars, sondern ein Bot, der blind an den Endpoint POSTet. Ablehnungen von Analytics-Events stehen auf ihrer eigenen Seite, Marketing → Ereignisse.
Der Lead ist nicht angekommen
Schau zuerst unter „Letzte Ablehnungen“. Ist dort nichts, geh die Liste durch:
- Der Name ist nicht angelegt. Unter Leads → Formulare muss es ein Formular mit genau diesem Namen geben, inklusive Groß-/Kleinschreibung. Ein leeres
data-crm-leadist das integriertelead_submit: Es entsteht von selbst, aber nur in einem Tarif mit Leads, und kommt aus dem Archiv nicht von allein zurück. - Der Name gehört einem Analytics-Event. Ein Lead unter diesem Namen wird nicht angenommen: Leg ein Formular mit einem anderen Namen an.
- Gesendet über
crmTrack. Das erzeugt keine Leads — du brauchst das Attributdata-crm-leadodercrmLead(). - Kein Telefon und keine E-Mail. Oder sie sind da, aber unter Namen, die das CRM nicht kennt (
your-phone,contact[email]), und sind in „Zusätzlich“ gelandet. Benenne sie um — siehe die Feldtabelle. Eine Telefonnummer mit weniger als 7 Ziffern zählt auch nicht. - Die Daten steckten in einem Datei-Input. Dateien werden ignoriert — das Widget sendet nur Text.
- Ein echtes Feld heißt
company_site. Das ist der Honeypot-Name; der Lead wird als Bot behandelt. - Dein eigener
crm:lead-before-Listener hatpreventDefault()aufgerufen — vielleicht nicht dann, wann du dachtest. - Das Widget ist nicht auf dieser Seite. Ohne
widget.jstut das Attribut nichts, und das Formular wird auf die altmodische Art abgeschickt (oder gar nicht). - Das Formular steckt in einem iframe, das Attribut kam erst später dazu, oder es wird per
form.submit()abgeschickt. In diesen Fällen fängt das Widget das Formular nicht ab — siehe wo das Attribut nicht greift. data-crm-ignoresteht am Formular selbst oder an einem Wrapper darum. Dann wird kein einziges Feld gesendet, und der Lead wird mit „Weder Telefon noch E-Mail“ abgelehnt.- Eine Content Security Policy blockiert es. Hat deine Site eine CSP, braucht sie
script-src https://widget.sitecog.comundconnect-src https://back.sitecog.com. Die Browser-Konsole sagt es dir in Rot. - Die Domain ist keine Site im CRM. Die Site wird am Origin der Seite erkannt (
www.wird entfernt), und zwar exakt: Eine Subdomain wieshop.example.comist eine eigene Site. Ein Test auflocalhostoder einer Staging-Domain, die nicht im CRM eingetragen ist, ergibtunknown_domainim Network-Tab. Hast du die Domain gerade erst eingetragen, warte bis zu 5 Minuten. - Du hast viel getestet. 20 Formular-Pässe pro Minute und IP reichen für Menschen locker, aber nicht für hektisches Klicken. Warte eine Minute.
Ein Feld ist nicht angekommen
Der Lead ist da, aber ein Feld fehlt? Meist wurde es mit Absicht weggelassen:
- Der Name klingt sensibel. Prüf ihn gegen die Regeln unter Felder, die nie gesendet werden:
promo_passetwa fliegt wegenpassraus. Benenn es um —promo_codekommt problemlos durch. - Irgendwo steht
data-crm-ignore. Am Feld selbst oder an einem Wrapper weiter oben im DOM — dort gilt es für alles darin. - Ein anderes Feld mit demselben Namen ist ausgeschlossen. Dann sind es alle Felder mit diesem Namen.
- Es ist ein Passwortfeld oder ein Datei-Input. Passwörter werden nie gesendet, und Dateien ignoriert das Widget sowieso.
Der Betrag wird nicht angezeigt
Der Betrag erscheint als Summe der letzten 30 Tage auf der Karte des Formulars unter Leads → Formulare; in der Lead-Karte selbst steht er nicht. Ist er auch dort leer, setz beim Formular den Haken „Dieses Formular bringt Umsatz“ (Symbol „Bearbeiten“ beim Formular): Beträge werden bei Leads gespeichert, die danach eingehen. Prüf außerdem, ob der Betrag eine Ganzzahl in kleinsten Einheiten ist: 1499.00 wird als 149900 gesendet.
Benachrichtigungen in Telegram
Ein Lead, den niemand sieht, ist ein verlorener Lead. Verbinde deinen eigenen Telegram-Bot — die Benachrichtigung über einen neuen Lead kommt innerhalb einer halben Minute, mit einem Link zu seiner Karte:
Bot anlegen und Token einfügen
Bots legst du bei@BotFatheran. Im CRM: Leads → „Lead-Einstellungen“ (oben im Bereich), Feld „Bot-Token“, Button „Verbinden“. Ein Bot pro Site — über ihn bekommen alle Manager Benachrichtigungen, die du auswählst.Empfänger sammeln
Alle, die Leads bekommen sollen, schreiben dem Bot/start(du kannst den Bot auch in eine Arbeitsgruppe aufnehmen). Dann klick im Block „Wer sie erhält“ auf „Aktualisieren“ und schalte die Richtigen ein: Neue erscheinen ausgeschaltet. Ohne diesen Schritt kommt gar nichts an.Benachrichtigungen einschalten und testen
Setz den Haken „Benachrichtigungen senden“, nach Wunsch auch „Auch verdächtige senden“, speichere und klick auf „Verbindung testen“: Das CRM sagt dir, bei wie vielen Empfängern die Testnachricht angekommen ist.
- Ruhezeiten verschieben Benachrichtigungen, statt sie wegzuwerfen: Ein nächtlicher Lead kommt gleich am Morgen an. Das Zeitfenster gilt für die ganze Site, aber jeder Empfänger kann ein eigenes bekommen oder gar keine Ruhezeiten.
- Verdächtige Leads kommen bei ausgeschaltetem Haken gar nicht — weder sofort noch am Morgen. Im CRM sind sie trotzdem.
- Hat der Bot einen Webhook, lässt sich die Empfängerliste nicht aufbauen: Entferne den Webhook oder nimm für Leads einen eigenen Bot.
Benachrichtigungen sind mit HTML formatiert, und alles, was der Besucher eingegeben hat, wird vorher escaped. Ein „Name“ wie <a href="…">Hier klicken</a> kommt als reiner Text an: Niemand kann einen Link als Text tarnen oder die Formatierung zerschießen. Eine Adresse, die jemand einfach so ins Feld tippt, zeigt Telegram selbst als Link an. Lange Felder werden gekürzt — die Nachricht auf 500 Zeichen, alle anderen auf 200 —, der vollständige Lead steht immer im CRM.
Daten einer Person auf Anfrage löschen
„Bitte löscht alles, was ihr über mich habt“ ist eine ganz normale Bitte, und sie zu erfüllen sollte nicht eine Woche Wühlen in Tabellen bedeuten. Das CRM hat dafür zwei Werkzeuge – ohne Code auf deiner Seite.
Aus einem Lead oder Chat
Die Lead-Karte und die Chat-Karte haben beide „Daten des Besuchers löschen“. Bevor etwas gelöscht wird, zeigt das CRM genau, was alles verschwindet:
- das Besucherprofil und Analytics – Seitenaufrufe und Events;
- Chats und Anhänge – die Zahl der Chats, Nachrichten und Dateien;
- Leads – nur, wenn du „Auch die Anfragen dieses Besuchers löschen“ ankreuzt. Standardmäßig aus: Ein Lead ist oft ein laufender Deal, und die Entscheidung liegt bei dir.
Ein Lead ohne visitor_id – von deinem Server ohne sie gesendet oder aus dem Browser vor der Einwilligung des Besuchers im Consent-Modus – hängt an keinem Besucher: Dort lässt sich nur der Lead selbst löschen.
Per E-Mail oder Telefon
Meist kommt die Bitte per E-Mail: „Ich bin anna@example.com, vergesst mich“. Geh zu CRM → Einstellungen → „Anfragen zur Datenlöschung“, gib die E-Mail oder Telefonnummer ein, die die Person angegeben hat, und das CRM findet ihre Leads und Chats (per E-Mail oder Telefon) und ihr Konto auf deiner Website (nur per E-Mail). Der Button „Alles Gefundene löschen“ löscht alles auf einmal.
- Besuchsstatistik. Der Haken „Auch die Besuchsstatistik der zugehörigen Besucher löschen“ ist standardmäßig gesetzt – nimm ihn raus, wenn die Statistik bleiben soll.
- Chats werden komplett gelöscht. Bei den gefundenen Besuchern verschwinden alle Chats, auch archivierte, samt Anhängen. Dateien, die in Seiten der Website eingebunden sind, bleiben.
- Rechte. Zum Löschen brauchst du das Recht, den jeweiligen Bereich zu bearbeiten: Leads – „Leads“, Chats – „Chats“, Konten – „Website-Nutzer“, Statistik – „Traffic“. Ein Manager, der nur ansehen darf, sieht die Treffer, kann sie aber nicht löschen.
- Aktivitätsprotokoll. Jede Löschung landet im Aktivitätsprotokoll – ohne E-Mail und Telefonnummer der Person, sonst würde das Protokoll genau das aufbewahren, was vergessen werden sollte.
- Kein Rückgängig. Gelöscht ist gelöscht. Prüf die Zahlen, bevor du bestätigst.