14. Für Entwickler

Diese Sektion ist die technische Referenz für Entwicklerinnen und Entwickler, die Klariton tiefer in eine eigene Website, einen Shop oder eine SaaS-Oberfläche integrieren wollen. Sie beschreibt die zwei offiziellen Integrationswege, den Embed-Vertrag des Widgets und die öffentlich lesbaren API-Endpunkte pro Touchpoint.

Klariton ist API-First aufgebaut (MACH-Architektur: Microservices, API-First, Cloud-native, Headless). Das bedeutet konkret: Alles, was die Klariton-Touchpoints (FAQ, Chat-Advisor, Infobox) im Browser anzeigen, kommt aus klar definierten HTTP-Endpunkten. Du kannst diese Endpunkte mit dem mitgelieferten Widget konsumieren oder — für die heute öffentlich lesbaren Touchpoint-Typen — direkt aus einem eigenen Frontend ansprechen.

Best Practice: Für den schnellen Start nutze das <klariton-widget>-Snippet — eine Zeile Script plus ein HTML-Element, fertig. Für ein vollständig eigenes Frontend (eigenes Rendering, eigenes Design-System, eigene Framework-Komponenten) gehst du direkt gegen die öffentliche Klariton-Read-API und renderst die Antworten selbst.

14.1 Zwei Integrationswege im Überblick

Weg	Wann	Aufwand
`<klariton-widget>`-Embed (LIVE)	Schneller Start, Standard-Rendering im eigenen Branding	Script-Tag + ein HTML-Element
Direkte API-Anbindung (LIVE)	Vollständig eigenes Frontend, eigenes Rendering	HTTP-Calls gegen die Public-Read-API

Beide Wege sind additiv und unabhängig: Du kannst mit dem Widget starten und später auf eine eigene API-Anbindung wechseln, ohne die Datenmodellierung in Klariton zu ändern.

14.2 Embed-Vertrag — `<klariton-widget>` (LIVE)

Das Klariton-Widget ist ein Custom Element. Die Integration besteht aus zwei Teilen: einem Loader-Script im <head> und einem oder mehreren <klariton-widget>-Elementen an den Stellen, wo die Beratung erscheinen soll.

Loader

Das Loader-Script wird als ES-Modul eingebunden. type="module" ist Pflicht, weil das Bundle ESM ist. Die Reihenfolge im Dokument ist unkritisch — das Custom Element wird beim ersten DOM-Mount registriert.

<script
  type="module"
  src="https://worker.klariton.com/v1/klariton-widget.universal.js">
</script>

Element und Attribute

<klariton-widget
  tenant-id="dein-org-slug"
  touchpoint-id="dein-touchpoint-slug-oder-id"
  locale="de-DE"
  data-worker-url="https://worker.klariton.com">
</klariton-widget>

Attribut	Pflicht	Bedeutung
`tenant-id`	ja	Org-Slug aus dem Klariton-Studio. Muss exakt (byte-gleich) mit dem in Klariton hinterlegten Slug übereinstimmen.
`touchpoint-id`	ja	Touchpoint-Slug oder Touchpoint-ID. Der Slug ist menschenlesbar, die ID bleibt stabil, auch wenn der Slug geändert wird.
`locale`	nein	Sprach-Tag im BCP-47-Format (z.B. `de-DE`). Ohne Angabe nutzt Klariton die Default-Sprache der Organisation.
`data-worker-url`	nein	Override der Worker-URL. Default ist `https://worker.klariton.com`. Hat deine Organisation eine eigene Worker-Subdomain hinterlegt (z.B. `chat.deine-domain.de`), läuft die Einbettung darüber first-party — das Studio generiert das Snippet dann automatisch mit dieser Subdomain.

Breite und Höhe bringt das Element selbst mit; das Layout wird beim Rendern bestimmt. Das Widget rendert automatisch den passenden Touchpoint-Typ: Ein FAQ-Touchpoint erscheint als Frage-Antwort-Akkordeon, ein Chat-Advisor als Chat-Oberfläche, eine Infobox als eingebetteter Hinweisblock. Du musst den Typ nicht im Markup angeben — er wird aus der Touchpoint-Konfiguration abgeleitet.

Best Practice: Hinterlege tenant-id und touchpoint-id als Slug, wenn die URL für Menschen lesbar bleiben soll, und als ID, wenn du maximale Stabilität gegen spätere Umbenennungen brauchst. Beide werden serverseitig akzeptiert. Lass dir das Snippet im Studio generieren — dann ist die Worker-URL (inkl. evtl. eigener Subdomain) bereits korrekt gesetzt.

Branding

Das Widget rendert im Branding der Organisation. Farben, Logo und Theme werden zentral im Studio gepflegt und pro Touchpoint geliefert — du musst im Embed kein Styling setzen.

Studio-Vorschau (Preview-Token) (LIVE)

Für die Live-Vorschau eines noch nicht veröffentlichten Touchpoints im Studio existiert ein signierter, kurzlebiger Preview-Token. Er wird intern vom Studio gesetzt und ist kein Bestandteil der regulären Kunden-Integration. Für eine produktive Einbettung brauchst du ihn nicht.

14.3 Public-Read-API pro Touchpoint (LIVE)

Wenn du ein eigenes Frontend baust und das Klariton-Widget nicht nutzen willst, kannst du die Inhalte eines Touchpoints direkt über die öffentliche Read-API abrufen und selbst rendern.

Universal-Touchpoint-Read

GET /api/v1/orgs/{slug}/touchpoints/{idOrSlug}

{slug}: Org-Slug der Organisation.
{idOrSlug}: Touchpoint-ID oder Touchpoint-Slug. Der Server erkennt automatisch, welches Format vorliegt.

Der Endpunkt ist type-discriminiert: Die Antwort trägt ein type-Feld und ist je Touchpoint-Typ unterschiedlich strukturiert. Heute liefern über diesen Endpunkt FAQ- und WIZARD_LEGACY-Touchpoints Daten. Die Auslieferung von CHAT_ADVISOR und INFOBOX über die Public-Read-API ist Teil der Roadmap (BALD) — bis dahin antwortet der Endpunkt für diese Typen mit 404. Dein Frontend wertet das type-Feld aus und rendert entsprechend.

Die Antwort hat die Form:

{
  "type": "FAQ",
  "tenantSlug": "dein-org-slug",
  "touchpointId": "…",
  "touchpointSlug": "…",
  "config": { "...typabhängig..." },
  "lastUpdated": "2026-05-31T10:00:00.000Z"
}

Bei type=FAQ enthält config.entries die ausgespielten Antwort-Einheiten, jeweils mit question, answer, personaId und order.

Eigenschaften des Endpunkts:

Keine Authentifizierung für lesende Zugriffe (GET). Der Endpunkt ist für lesenden Konsum offen.
Es werden nur veröffentlichte (LIVE) Touchpoints ausgeliefert. Entwürfe und gelöschte Touchpoints liefern keine Daten. Bei FAQ werden zudem nur live-fähige Antwort-Einheiten ausgespielt (kein Roh-Entwurf, keine abgelehnten Einträge).
Existiert der Touchpoint nicht (oder ist er nicht LIVE), antwortet der Endpunkt mit 404 und einem JSON-Body { "error": "NotFound" }.
Caching: Die Antwort trägt Cache-Control: public, max-age=300, stale-while-revalidate=600 (5 Minuten Edge-Cache, 10 Minuten Stale-Toleranz). Nach einer Veröffentlichung im Studio wird der Cache invalidiert.
CORS: Lesende Zugriffe sind Cross-Origin möglich; der Endpunkt beantwortet auch CORS-Preflights (OPTIONS).

Best Practice: Cache die API-Antworten in deinem eigenen Frontend nicht aggressiver als der Cache-Control-Header vorgibt. Klariton invalidiert serverseitig bei jeder Veröffentlichung; eine zu lange clientseitige Cache-Dauer würde veröffentlichte Änderungen verzögern.

Hinweis zu Confidence-Levels

Klariton führt intern pro Antwort-Einheit ein Confidence-Level (CONFIRMED, SINGLE_SOURCE, EXTERNAL, INFERRED). Über die auth-freie Universal-Read-API oben wird dieses Level aktuell nicht mit ausgeliefert — die FAQ-Einträge dort enthalten Frage, Antwort, Persona-Zuordnung und Reihenfolge. Confidence-Informationen liefert heute ein eigener, worker-seitiger Endpunkt an das Klariton-Widget (siehe 14.4); dieser verlangt das Server-zu-Server-Secret und ist nicht für direkten Browser-Zugriff gedacht. Wenn du Confidence in einem eigenen Frontend brauchst, sprich das Klariton-Team zur Anbindung an. Behandle ein evtl. vorhandenes Confidence-Feld immer als optional: Ist es nicht gesetzt, lasse es weg, statt einen Platzhalter anzunehmen.

14.4 Chat-Advisor über die API (LIVE, serverseitiger Vertrag)

Für den Chat-Advisor-Touchpoint existiert ein dedizierter Frage-Endpunkt, der Endkunden-Fragen entgegennimmt und eine quellenbelegte Antwort zurückliefert. Dieser Endpunkt ist worker-only: Er verlangt das Server-zu-Server-Secret (X-Klariton-Worker-Secret) und wird in der Standard-Integration vom Klariton-Worker im Auftrag des Widgets angesprochen. Eine direkte Anbindung aus einem komplett eigenen Chat-Frontend ist damit ein serverseitiges Integrationsprojekt — für ein reines Browser-Frontend ist das Widget der empfohlene Weg.

Streaming-Antworten (Server-Sent Events, text/event-stream) für den Chat sind serverseitig vorhanden und werden vom Worker an das Widget durchgereicht.

Best Practice: Baue den Chat nicht von Browser-Seite direkt gegen den Frage-Endpunkt, sondern nutze das <klariton-widget> — es kapselt die Session-Behandlung, das Streaming und die Eskalation zum Lead. Ein vollständig eigenes Chat-Frontend ist ein serverseitiges Integrationsprojekt; sprich dafür das Klariton-Team an.

14.5 Webhooks (geplant / bald) (BALD)

Ausgehende Webhooks an Kundensysteme (z.B. eine Benachrichtigung bei einem neuen Lead an dein CRM) sind als Klariton-Funktion geplant, aber noch nicht als öffentliches Produkt verfügbar. Die heute im System vorhandenen Webhook-Mechanismen dienen ausschließlich der internen Plattform-Synchronisation und sind nicht als Kunden-Schnittstelle gedacht.

Für ereignisgetriebene Integrationen (Lead-Übergabe, neue Antworten) bis zur Verfügbarkeit von Kunden-Webhooks: Frage die relevanten Daten periodisch über die Public-Read-API ab, oder sprich das Klariton-Team für die aktuelle Lead-Übergabe an.

14.6 SDKs (geplant / bald) (BALD)

Ein offizielles React-/Next.js-SDK ist geplant, aber noch nicht verfügbar. Bis dahin sind die beiden produktiven Wege:

das <klariton-widget>-Embed (funktioniert in jedem Framework, da es ein natives Custom Element ist), und
direkte HTTP-Calls gegen die Public-Read-API aus deinem Framework-Code.

In React/Next.js lässt sich das <klariton-widget>-Element direkt im JSX verwenden; der Loader-Script gehört dann in das Layout bzw. den Dokument-Head.

14.7 Zusammenfassung — Was ist heute live?

Fähigkeit	Status
`<klariton-widget>`-Embed-Vertrag	LIVE
Automatisches Typ-Rendering (FAQ / Chat / Infobox) im eigenen Branding	LIVE
Public-Read-API pro Touchpoint (`GET .../touchpoints/{idOrSlug}`), FAQ + WIZARD_LEGACY	LIVE
Public-Read-API für CHAT_ADVISOR / INFOBOX	BALD
CORS + Edge-Caching auf der Read-API	LIVE
Confidence-Level in der auth-freien Public-Read-API	BALD
Confidence-Auslieferung an das Widget (worker-seitiger Endpunkt, Server-Secret)	LIVE
Chat-Advisor (über Widget / serverseitigen Worker-Vertrag)	LIVE
Ausgehende Kunden-Webhooks	BALD
React-/Next.js-SDK	BALD