Zickt

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

  1. Du erstellst einen Formular-Erfassungs-Kanal unter Einstellungen → Kanäle und konfigurierst deine Felder.
  2. Du fügst das generierte Code-Snippet auf deiner Website ein.
  3. 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/json

Antwortformat

200 OK
{
  "success": true,
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "contact_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
400 Bad Request
{
  "success": false,
  "error": "Validation failed",
  "field_errors": {
    "email": "Invalid email format",
    "phone": "Invalid phone number format"
  }
}
403 Forbidden
{
  "success": false,
  "error": "Origin not allowed"
}

Code-Beispiele

kontakt-formular.html
<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>
KontaktFormular.tsx
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>
  );
}
app/kontakt/page.tsx
'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>
  );
}
KontaktFormular.vue
<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:

FeldnameZuordnungPflichtValidierung
nameKontaktnameNein—
emailKontakt-E-MailJaE-Mail
messageErste Nachricht der KonversationNein—

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

TypVerhalten
emailMuss @ und eine Domain enthalten
phoneAkzeptiert Formate wie +49 (30) 123-4567, mindestens 10 Ziffern
urlMuss eine gültige URL sein
numberMuss numerisch sein

Transformationstypen

TypVerhalten
lowercaseKonvertiert zu Kleinbuchstaben
uppercaseKonvertiert zu Großbuchstaben
trimEntfernt 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:

  1. E-Mail — höchste Priorität
  2. Telefon
  3. Externe ID
  4. 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.com passt auf app.example.com, staging.example.com und example.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

On this page