Formular-Erfassung
Wandle Website-Formulareinsendungen in Zickt-Konversationen um — mit automatischer Kontakt-Zuordnung und Team-Routing. HTML-, React- und Vue-Codebeispiele inklusive.
Formular-Erfassung wandelt HTML-Formularübermittlungen auf deiner Website in Zickt-Konversationen um. Jede Einsendung erstellt einen Kontakt (oder findet einen bestehenden), öffnet eine Konversation in deinem Posteingang und leitet sie an das richtige Team weiter.
So funktioniert es
- Du erstellst einen Formular-Erfassungs-Kanal unter Einstellungen → Kanäle und konfigurierst deine Felder.
- Du fügst das generierte Code-Snippet auf deiner Website ein.
- Wenn ein Besucher das Formular absendet, erstellt oder findet Zickt einen Kontakt, öffnet eine Konversation und wendet deine Standard-Zuweisungsregeln an.
API-Endpunkt
Alle Formularübermittlungen werden an einen einzelnen Endpunkt gesendet. Ersetze DEIN_CHANNEL_KEY durch den Key aus dem Tab Installation deines Kanals.
POST https://api.zickt.com/v1/forms/DEIN_CHANNEL_KEY/submit
Content-Type: application/jsonAntwortformat
{
"success": true,
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"contact_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}{
"success": false,
"error": "Validation failed",
"field_errors": {
"email": "Invalid email format",
"phone": "Invalid phone number format"
}
}{
"success": false,
"error": "Origin not allowed"
}Code-Beispiele
<form id="kontakt-formular">
<input type="text" name="name" placeholder="Dein Name" required />
<input type="email" name="email" placeholder="Deine E-Mail" required />
<textarea name="message" placeholder="Deine Nachricht" required></textarea>
<button type="submit">Senden</button>
</form>
<script>
document.getElementById('kontakt-formular').addEventListener('submit', async (e) => {
e.preventDefault();
const data = Object.fromEntries(new FormData(e.target).entries());
const res = await fetch('https://api.zickt.com/v1/forms/DEIN_CHANNEL_KEY/submit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
});
if (res.ok) {
e.target.reset();
alert('Danke! Wir melden uns bald bei dir.');
}
});
</script>import { useState } from 'react';
export function KontaktFormular() {
const [status, setStatus] = useState<'idle' | 'sending' | 'sent'>('idle');
const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
e.preventDefault();
setStatus('sending');
const data = Object.fromEntries(new FormData(e.currentTarget));
const res = await fetch('https://api.zickt.com/v1/forms/DEIN_CHANNEL_KEY/submit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
});
setStatus(res.ok ? 'sent' : 'idle');
};
if (status === 'sent') return <p>Danke! Wir melden uns bald bei dir.</p>;
return (
<form onSubmit={handleSubmit}>
<input name="name" placeholder="Name" required />
<input name="email" type="email" placeholder="E-Mail" required />
<textarea name="message" placeholder="Nachricht" required />
<button type="submit" disabled={status === 'sending'}>
{status === 'sending' ? 'Wird gesendet…' : 'Senden'}
</button>
</form>
);
}'use client';
import { useState } from 'react';
export default function KontaktSeite() {
const [status, setStatus] = useState<'idle' | 'sending' | 'sent'>('idle');
const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
e.preventDefault();
setStatus('sending');
const data = Object.fromEntries(new FormData(e.currentTarget));
const res = await fetch('https://api.zickt.com/v1/forms/DEIN_CHANNEL_KEY/submit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
});
setStatus(res.ok ? 'sent' : 'idle');
};
if (status === 'sent') return <p>Danke! Wir melden uns bald bei dir.</p>;
return (
<form onSubmit={handleSubmit}>
<input name="name" placeholder="Name" required />
<input name="email" type="email" placeholder="E-Mail" required />
<textarea name="message" placeholder="Nachricht" required />
<button type="submit" disabled={status === 'sending'}>
{status === 'sending' ? 'Wird gesendet…' : 'Senden'}
</button>
</form>
);
}<script setup lang="ts">
import { ref } from 'vue';
const status = ref<'idle' | 'sending' | 'sent'>('idle');
const handleSubmit = async (e: Event) => {
status.value = 'sending';
const data = Object.fromEntries(new FormData(e.target as HTMLFormElement));
const res = await fetch('https://api.zickt.com/v1/forms/DEIN_CHANNEL_KEY/submit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
});
status.value = res.ok ? 'sent' : 'idle';
};
</script>
<template>
<p v-if="status === 'sent'">Danke! Wir melden uns bald bei dir.</p>
<form v-else @submit.prevent="handleSubmit">
<input name="name" placeholder="Name" required />
<input name="email" type="email" placeholder="E-Mail" required />
<textarea name="message" placeholder="Nachricht" required />
<button type="submit" :disabled="status === 'sending'">
{{ status === 'sending' ? 'Wird gesendet…' : 'Senden' }}
</button>
</form>
</template>Ersetze DEIN_CHANNEL_KEY durch den Channel Key aus Einstellungen → Kanäle → Formular-Erfassung
→ Installation.
Feld-Zuordnung
Jedes Formularfeld wird einer Kontakt-Eigenschaft, Unternehmens-Eigenschaft oder der ersten Nachricht der Konversation zugeordnet. Konfiguriere Zuordnungen im Tab Feld-Zuordnung des Kanals oder nutze den visuellen Formular-Builder bei der Kanalerstellung.
Standardfelder
Neue Formular-Erfassungs-Kanäle starten mit diesen Feldern:
| Feldname | Zuordnung | Pflicht | Validierung |
|---|---|---|---|
name | Kontaktname | Nein | — |
email | Kontakt-E-Mail | Ja | |
message | Erste Nachricht der Konversation | Nein | — |
Verfügbare Feldziele
Jeder Formular-Erfassungs-Kanal muss mindestens ein Identifikatorfeld enthalten (contact.email,
contact.phone, contact.external_id oder ein Social-/CRM-Identifikator). Dies stellt sicher,
dass Zickt einen Kontakt erstellen oder zuordnen kann.
Validierungstypen
| Typ | Verhalten |
|---|---|
email | Muss @ und eine Domain enthalten |
phone | Akzeptiert Formate wie +49 (30) 123-4567, mindestens 10 Ziffern |
url | Muss eine gültige URL sein |
number | Muss numerisch sein |
Transformationstypen
| Typ | Verhalten |
|---|---|
lowercase | Konvertiert zu Kleinbuchstaben |
uppercase | Konvertiert zu Großbuchstaben |
trim | Entfernt führende/nachstehende Leerzeichen |
Kontakt-Zuordnung
Wenn ein Formular abgesendet wird, sucht Zickt nach einem bestehenden Kontakt, indem Identifikatoren in dieser Reihenfolge geprüft werden:
- E-Mail — höchste Priorität
- Telefon
- Externe ID
- Andere Identifikatoren — soziale Profile, CRM-IDs
Wird eine Übereinstimmung gefunden, wird der bestehende Kontakt mit neuen Daten aus der Einsendung aktualisiert. Wird keine Übereinstimmung gefunden, wird ein neuer Kontakt erstellt.
Unternehmensdaten werden ebenso behandelt: Wenn company.domain oder company.name einem bestehenden Unternehmen entspricht, wird der Kontakt automatisch verknüpft.
Erlaubte Ursprünge
Formular-Erfassung validiert den Origin-Header bei jeder Einsendung. Nur Anfragen von genehmigten Domains werden akzeptiert.
- Konfiguriere Ursprünge unter Einstellungen → Kanäle → Formular-Erfassung → Sicherheit
- Wildcard-Subdomains werden unterstützt:
*.example.compasst aufapp.example.com,staging.example.comundexample.com - Wenn keine Ursprünge konfiguriert sind, werden alle Domains akzeptiert (nützlich während der initialen Entwicklung)
Einsendungen von nicht gelisteten Ursprüngen geben einen 403-Fehler zurück. Füge localhost zu
deinen erlaubten Ursprüngen für die lokale Entwicklung hinzu.
Standard-Zuweisung
Weise optional ein Standard-Team oder Teammitglied zu Konversationen zu, die über ein Formular erstellt werden. Konfiguriere dies in den Kanal-Einstellungen:
- Standard-Team — alle Formular-Konversationen werden diesem Team zugewiesen
- Standard-Zuweisung — alle Formular-Konversationen werden dieser Person zugewiesen
Diese können nach der Erstellung der Konversation manuell überschrieben werden.
Kanalwechsel
Leite Konversationen nach der initialen Formulareinsendung an einen anderen Kanal weiter. Zum Beispiel: Erfasse Leads über ein Kontaktformular, aber leite die fortlaufende Konversation an deinen Web-Messenger-Kanal für Live-Chat-Follow-up weiter.
Konfiguriere dies unter Kanal wechseln in den Sicherheitseinstellungen des Kanals.
Fehlerbehebung
Nächste Schritte
Verbinde deinen Gmail-Posteingang mit Zickt und verwalte E-Mail-Konversationen in einem gemeinsamen Team-Posteingang. OAuth-Einrichtung, Threading, Signaturen und Filterung.
Slack
Verbinde Slack mit Zickt für bidirektionalen Kundensupport. Leite Konversationen an Slack-Kanäle, antworte aus Threads und halte deinen Posteingang synchron.