Chat-Referenz

Mit product: 'chat' wird das Kaleidr-Chat-Panel in Ihre Webseite eingebunden. Das Panel läuft direkt im Dokument, nicht in einem iframe. Es lässt sich mit einem übergebenen Kartenobjekt oder einem angegebenen Kaleidr-Viewer- bzw. Tile-Element verbinden oder ohne Karte als reines Chat-Panel nutzen.

Diese Seite dient als Nachschlagewerk. Beginnen Sie für Ihre erste Seite mit einer Anleitung: Mapbox, MapLibre, Google Maps oder Leaflet.

Voraussetzungen

Tarif	Free und höher
Zugangsdaten	Ein veröffentlichbarer Schlüssel (kld_pk_live_…) oder die ID einer veröffentlichten Studio-Karte mit aktiviertem Control Tower
Berechtigung	ai; standardmäßig in jedem neu erstellten Schlüssel enthalten
Erlaubte Herkunft	Die Herkunft der Webseite, falls der Schlüssel zulässige Ursprünge festlegt
Loader	https://cdn.kaleidr.com/embed/v1/kaleidr.js
Kartenbibliothek	Optional. Siehe Unterstützte Karten.

Minimale Einbindung

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,              // your live map object
  contained: true,  // dock inside #chat
});

Kaleidr.mount(target, options) akzeptiert als target einen CSS-Selektor oder ein Element. Die Funktion gibt synchron ein Handle zurück und löst bei einem fehlgeschlagenen Mount keinen Fehler aus. Das Chat-Bundle wird geladen und der Schlüssel im Hintergrund gegen eine Sitzung eingetauscht. Schlägt einer der Schritte fehl, erscheint eine Fehlermeldung in der Konsole und es wird nichts dargestellt. Nur ein Mount ohne Optionsobjekt löst eine Ausnahme aus: Kaleidr.mount('#chat') wirft einen TypeError.

Mount-Optionen

Alle Optionen werden beim Mount nur einmal gelesen. Um sie zu ändern, rufen Sie destroy() auf und mounten neu. Die einzige Ausnahme ist das Design, das mit setTheme aktualisiert werden kann.

Option	Typ	Standardwert	Erforderlich	Verhalten in Chat
product	'chat'	Keiner	Ja	Wählt das Chat-Produkt.
publishableKey	Zeichenfolge	Keiner	Ja, außer bei Angabe von shareId	Ihr kld_pk_…-Schlüssel. Das SDK tauscht ihn vor der ersten Panel-Anfrage gegen ein Sitzungstoken aus. Ein Serverschlüssel kld_sk_… wird im Browser mit einer Konsolenfehlermeldung abgelehnt; es wird keine Anfrage gesendet.
shareId	Zeichenfolge	Keiner	Ja, außer bei Angabe von publishableKey	ID einer veröffentlichten Studio-Karte mit aktiviertem Control Tower in ihrer Kachel Kaleidr AI. Wird nur ohne Schlüssel verwendet. Der Karteninhaber bezahlt die Anfragen. Der eigene Viewer der veröffentlichten Karte zeigt dieses Panel bereits. Siehe Kaleidr AI auf einer veröffentlichten Karte.
map	Aktives Kartenobjekt	Keiner	Nein	Die Karte, auf der der Assistent Marker platziert und die Ansicht verschiebt. Die Bibliothek wird anhand des Objekts erkannt. Für ein reines Chat-Panel weglassen.
mapTarget	CSS-Selektor	Keiner	Nein	Viewer- oder Tile-Element <kaleidr-map> auf derselben Seite, das das Panel steuern soll. Wird bei Angabe von map ignoriert.
contained	boolesch	false	Nein	true verankert das Panel im Mount-Ziel, das positioniert und dimensioniert sein muss. false fügt es als festes Fenster links oben im sichtbaren Browserbereich zu document.body hinzu.
lang	Zeichenfolge	<html lang> der Seite, sofern gültig, andernfalls Englisch	Nein	Sprache der Antworten als BCP-47-Sprachkennzeichen wie en, ko oder pt-BR. Siehe Sprache.
title	Zeichenfolge	Aus der Unterhaltung abgeleiteter Titel	Nein	Titel in der Kopfzeile des Chatfensters. Siehe Titel und Platzhalter.
placeholder	Zeichenfolge	Ask Kaleidr	Nein	Platzhaltertext im Eingabefeld.
theme	Objekt oder JSON-Zeichenfolge eines Objekts	Keiner	Nein	Anzuwendende benutzerdefinierte CSS-Eigenschaften, z. B. { '--highlight-color': '#7c3aed' }. Sie werden in :root gesetzt und gelten seitenweit.
enabled	boolesch	Keiner	Nein	Mount-spezifischer Schalter der Aktivierungssteuerung. false hält diesen Mount zurück. Siehe kaleidr.js.
apiBase	URL	https://api.kaleidr.com/inference-api	Nein	API für Sitzungsaustausch und Fragen. Der Pfad /inference-api ist erforderlich.
base	URL	https://cdn.kaleidr.com	Nein	Ursprung, von dem das Chat-Bundle geladen wird. Verwendet wird nur der Ursprung; zugelassen sind nur das Kaleidr-CDN (https://cdn.kaleidr.com), der Ladeursprung von kaleidr.js oder der eigene Seitenursprung. Siehe Base-Überschreibung.
apiKey	Zeichenfolge	Keiner	Nein	Veralteter Alias für publishableKey.

Von Chat ignorierte Optionen

center, zoom, pitch, bearing, styleId, viewerBase und tileBase werden bei einem Chat-Mount akzeptiert, aber ignoriert. Das Panel legt keine anfängliche Kameraposition fest; Ihre Karte behält die von Ihnen vorgegebene Ansicht.

Nicht vorhandene Optionen

Es gibt keine Option zum Erzwingen einer Kartenbibliothek, für Sprachsteuerung oder für Rückruffunktionen. Siehe Derzeit nicht verfügbar.

Sprache

lang legt die Antwortsprache des Panels fest und wird mit jeder Frage übertragen.

Ihre Angabe	Verwendete Sprache
lang: 'ko' oder lang="ko" am Element	Das angegebene Sprachkennzeichen.
Kein lang, Seite mit <html lang="fr">	Die Seitensprache, sofern das Kennzeichen gültig ist.
Kein lang, Seite ohne <html lang> oder mit ungültigem Kennzeichen	Englisch.

• Zulässige Werte: BCP-47-Sprachkennzeichen wie en, ko, ja, pt-BR, zh-Hant. Kennzeichen mit mehr als 35 Zeichen werden von der API abgelehnt, wodurch jede Frage mit 422 lang_too_long fehlschlägt.
• Die Seitensprache wird nur bei korrekter Schreibweise übernommen: zwei oder drei Buchstaben, optional gefolgt von bis zu drei durch Bindestriche getrennten Unterkennzeichen mit jeweils einem bis acht Buchstaben oder Ziffern. Ein nicht ersetzter Vorlagenplatzhalter wird übergangen und Englisch verwendet; ein fehlerhaftes <html lang> legt Chat somit nicht lahm.
• Ein ausdrücklich gesetztes lang hat immer Vorrang vor der Seitensprache.
• lang übersetzt weder Titel noch Platzhalter. Deren Standardwerte sind Englisch. Setzen Sie title und placeholder passend zur Sprache von lang.

Titel und Platzhalter

Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,
  contained: true,
  lang: 'fr',
  title: 'Demandez à propos d’un lieu',
  placeholder: 'Posez une question',
});

• placeholder ersetzt den standardmäßigen Eingabetext „Ask Kaleidr“.
• title ist der Titel des Chatfensters. Fenster und Kopfzeile erscheinen beim Beginn einer Unterhaltung und zeigen danach in jeder Unterhaltung Ihren Titel. Ohne title zeigt die Kopfzeile die gekürzte erste Besucherfrage. Ein minimierter Chat zeigt den Titel seiner eigenen Unterhaltung, abgeleitet von der ersten Besucherfrage, unabhängig davon, ob Sie title angegeben haben.
• Beim Element heißt das Titelattribut chat-title, nicht title. Das HTML-Attribut title zeigt stattdessen den Hover-Tooltip des Browsers über dem Elementinhalt.

Welche Zugangsdaten verwendet werden

Ihre Angabe	Ergebnis
publishableKey	Der Schlüssel wird gegen eine Sitzung eingetauscht. Ein gleichzeitig angegebenes shareId wird ignoriert.
Nur shareId	Die veröffentlichte Karte wird gegen eine Sitzung eingetauscht.
Beides fehlt	Das Panel wird angezeigt, aber jede Frage schlägt fehl. Beim Mount wird kein Fehler protokolliert.

Welche Karte verwendet wird

Ihre Angabe	Ergebnis
map	Das übergebene Kartenobjekt. Ein ebenfalls angegebenes mapTarget wird ignoriert.
Nur mapTarget	Das zum Selektor passende Kaleidr-Viewer- oder Tile-Element. Der Selektor wird bei jedem Kartenbedarf ausgewertet; das Element darf daher erst nach dem Panel gemountet werden.
Keines oder ein nicht erkanntes Objekt bzw. ein ungültiger Selektor	Nur Chat: keine Marker, Kamerabewegungen oder Routen. Es gibt keine Protokollmeldung.

Elementattribute

<kaleidr-map product="chat"> ist die deklarative Schreibweise. Das Element selbst bildet das Mount-Ziel.

<kaleidr-map product="chat" share-id="YOUR_MAP_ID" contained
             map-target="#store-map"
             style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>

Attribut	Zugeordnete Option	Hinweise
product="chat"	product	Erforderlich.
publishable-key	publishableKey
share-id	shareId
map-target	mapTarget	CSS-Selektor.
contained	contained	Das bloße Attribut bedeutet true. contained="false" bedeutet false.
lang	lang	BCP-47-Kennzeichen. Siehe Sprache.
chat-title	title	Titel der Kopfzeile. Nicht title, der HTML-Tooltip.
placeholder	placeholder	Eingabeplatzhalter.
theme	theme	JSON-Zeichenfolge. Eine Änderung nach dem Mount wendet den neuen Wert an.
flag	enabled	flag="false" hält den Mount zurück.
api-base	apiBase
base	base
api-key	apiKey	Veralteter Alias für publishable-key.

Wichtiges zur Elementschreibweise:

• Sie kann kein aktives Kartenobjekt erhalten. Für map gibt es kein Attribut. Um eine eigene Mapbox-, MapLibre-, Google- oder Leaflet-Karte zu verbinden, verwenden Sie Kaleidr.mount. Die Elementschreibweise steuert über map-target einen Kaleidr Viewer oder Tile oder führt Chat ohne Karte aus.
• Attribute werden einmal gelesen, wenn das Element verbunden wird. Nur theme wird nach einer späteren Änderung angewendet. Änderungen an share-id, publishable-key, map-target, contained, lang, chat-title, placeholder oder flag nach dem Mount bleiben wirkungslos; entfernen Sie das Element und fügen Sie ein neues ein.
• Kameraattribute sind wirkungslos. center, zoom, pitch und bearing werden beim Chat-Mount ignoriert. Spätere Änderungen führen zu einer Warnung „nicht unterstützt“.
• Das Element verwendet standardmäßig display:block. Für contained braucht es Positionierung und Abmessungen. Die Beispiele enthalten display:block auch für Safari vor 16.4, wo das Element sonst inline bleibt. Siehe Design und Layout.
• Das Entfernen des Elements zerstört den Mount. Wird es erneut eingefügt, entsteht ein neues Panel mit neuer Sitzung.

Die vollständige Attributtabelle aller Produkte finden Sie unter Das kaleidr-map-Element.

Steuer-Handle

Kaleidr.mount gibt für alle Produkte ein Handle mit derselben Struktur zurück. Für Chat gilt:

Mitglied	Bei Chat	Verhalten
product	'chat'	Schreibgeschützt.
setTheme(theme)	Unterstützt	Akzeptiert ein Objekt mit benutzerdefinierten CSS-Eigenschaften oder eine entsprechende JSON-Zeichenfolge. Ergänzt vorhandene Werte. Einem Schlüsselnamen ohne führendes -- wird dieses Präfix hinzugefügt. Ungültiger JSON-Text oder ein Array wird mit Warnung ignoriert.
destroy()	Unterstützt	Entfernt das Panel, seine Ortskarten, Marker und Route und beendet die Sitzungserneuerung. Mehrmaliger Aufruf ist sicher.
setCamera(camera)	Nicht unterstützt	Protokolliert eine Warnung und bewirkt nichts. Verwenden Sie die API Ihrer Kartenbibliothek für Kamerabewegungen.
setStyle(style)	Nicht unterstützt	Protokolliert eine Warnung und bewirkt nichts.

handle.setTheme({ '--highlight-color': '#0ea5e9' });
handle.destroy();

Aufrufe vor dem vollständigen Laden des Panels werden zwischengespeichert und bei Bereitschaft angewendet. Ein vorheriges destroy() bricht den Mount ab.

Das Handle hat weder ein ready-Promise noch eine on()-Methode oder ein map-Mitglied. Nachrichten lassen sich darüber weder senden noch Unterhaltungen auslesen. Ist die Aktivierungssteuerung beim Mount ausgeschaltet, ist das Handle ein inaktiver Platzhalter: Alle Methoden bleiben wirkungslos, und eine Konsolenwarnung nennt den blockierenden Schalter.

Nicht unterstützte Methoden protokollieren:

[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. See the handle matrix at https://docs.kaleidr.com/sdk/kaleidr-map-element#handle-matrix.

Die Übersicht für alle vier Produkte finden Sie unter Das kaleidr-map-Element.

Verhalten des Panels nach dem Mount

• Es zeigt eine Eingabezeile mit „Ask Kaleidr“ oder Ihrem placeholder. Die erste Frage erweitert sie zu einem Chatfenster.
• Jede Frage wird mit dem bisherigen Gespräch, dessen Kennung, dem Zoomfaktor der verbundenen Karte und dem Sprachkennzeichen gesendet: Ihrem lang, dem der Webseite oder en. Welche Daten die Seite verlassen listet alle Anfragen.
• In Antworten genannte Orte erscheinen als Ergebniskarten und Marker auf der verbundenen Karte. Die Kamera fliegt zu einem Ort oder rahmt mehrere Orte ein.
• Ein Mount zeigt jeweils eine Unterhaltung an, und jede hat eine eigene Kennung. Beim Schließen des Chatfensters werden Unterhaltung und Marker gelöscht; die nächste Frage startet eine neue Unterhaltung mit neuer Kennung. Minimieren erhält die bisherige Unterhaltung; eine neue Frage eröffnet eine andere, und beim Wiederherstellen wird die minimierte Unterhaltung unter ihrer früheren Kennung fortgeführt. Nach einem Neuladen beginnt alles von vorn. Nichts bleibt gespeichert.

Sitzungsaustausch

Ihr veröffentlichbarer Schlüssel wird nie für Fragen eingesetzt. Vor der ersten Anfrage des Panels tauscht das SDK den Schlüssel gegen ein kurzlebiges Sitzungstoken und übergibt dem Panel nur dieses Token.

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
x-api-key: kld_pk_live_…
content-type: application/json

{"product":"chat"}

{ "session_token": "kld_sess_live_…", "expires_in": 900, "product": "chat", "basemap_style_id": null }

Verhalten	Einzelheiten
Bindung	Die Sitzung gilt für das Produkt chat vom Ursprung aus, der sie angefordert hat.
Erneuerung	Das SDK fordert 90 Sekunden vor Ablauf eine neue Sitzung an, außerdem wenn ein Hintergrund-Tab mit abgelaufener oder fast abgelaufener Sitzung wieder aktiv wird.
Fehlgeschlagene Erneuerung	Wiederholung alle 30 Sekunden, solange das Panel gemountet bleibt.
Fehlgeschlagener erster Austausch	Der Mount schlägt fehl. Ein Fehler wird protokolliert, nichts wird angezeigt und es gibt keinen neuen Versuch. Mounten Sie erneut.
Ohne Schlüssel, mit shareId	Der Austausch erfolgt über POST …/b2b/v1/sdk/share-sessions mit dem Body {"share_id":"…"}. Die Sitzung dauert 300 Sekunden. Wird die Erneuerung mit 401, 403 oder 404 abgelehnt, sendet das SDK bis zum Neuladen keine weiteren Anfragen.

Authentifizierung und Berechtigungen erläutert Schlüssel, Sitzungen und Berechtigungen ausführlich.

Lebenszyklus in einer Single-Page-App

• Rufen Sie handle.destroy() auf, wenn die Ansicht mit der Karte entfernt wird. Zerstören Sie das Panel vor der Karte, damit es seine Marker entfernen kann.
• Mounten Sie erneut, wenn die Ansicht zurückkehrt. Dadurch entstehen ein neuer Sitzungsaustausch und eine neue Unterhaltung.
• destroy() lässt das Stylesheet des Panels und die Theme-Eigenschaften in :root im Dokument. Siehe Was destroy() entfernt und belässt.
• Wenn Sie das Kartenobjekt ersetzen, etwa durch Neuerstellung der Karte, zerstören Sie das Panel und mounten es mit dem neuen Objekt neu. Das Panel behält die ursprünglich übergebene Objektreferenz.

Frameworks erläutert Mount- und Cleanup-Muster für React, Next.js und Vue.

Fehler

Das SDK meldet einen fehlgeschlagenen Mount mit genau einem Konsolenfehler, ohne den Grund des Servers zu wiederholen. Bei HTTP-Fehlern öffnen Sie die Anfrage im Netzwerk-Tab und lesen den JSON-Body. Bei 403 und 404 steht der Fehlercode in detail, bei 429 in error, zusammen mit einem Hinweistext in detail.

Beim Mount

Konsole	Netzwerk	Ursache
[kaleidr:chat] mount target not found: <selector>	Keine Anfrage	Kein Element stimmt mit dem Selektor überein.
[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …	Keine Anfrage	Es wurde ein Serverschlüssel übergeben.
[kaleidr:chat] [kaleidr] failed to load <url>	Anfrage für chat.js fehlgeschlagen	Das Bundle wurde blockiert oder das CDN war nicht erreichbar.
CORS-Fehler, gefolgt von einem Fehler mit [kaleidr:chat]	POST …/sdk/sessions durch CORS blockiert	Der Schlüssel ist unbekannt, widerrufen oder abgelaufen oder der Seitenursprung steht nicht in seiner Liste zulässiger Ursprünge. Die API sendet CORS-Header nur für zulässige Ursprünge, daher versteckt der Browser Status und Body.
[kaleidr:chat] kaleidr session exchange failed (403)	403 insufficient_scope	Dem Schlüssel fehlt die Berechtigung ai.
Dasselbe	403 product_not_allowed	Der Schlüssel ist auf Produkte ohne chat begrenzt.
Dasselbe	403 tier_capability_not_allowed	Der aktuelle Tarif der Organisation erlaubt diese Funktion nicht.
[kaleidr:chat] kaleidr session exchange failed (429)	429 rate_limited	Mehr als 30 Sitzungsanfragen für diesen Schlüssel in einer Minute.
[kaleidr:chat] kaleidr session exchange failed (404)	404 sessions_disabled	Der Sitzungsaustausch ist plattformseitig deaktiviert. Ursache ist nicht Ihr Schlüssel.
[kaleidr:chat] kaleidr session exchange failed (503)	503 sessions_not_configured	Plattformfehler. Laden Sie die Seite neu.
[kaleidr:chat] kaleidr session exchange failed (403) oder (404) bei Mount mit shareId ohne Schlüssel	403 chat_disabled, 403 origin_not_allowed oder 404 not_found	Die veröffentlichte Karte hat Chat verweigert. Siehe Kaleidr AI auf einer veröffentlichten Karte.
[kaleidr] embed is disabled — … (Warnung)	Keine Anfrage	Die Aktivierungssperre ist eingeschaltet. Die Meldung nennt den Schalter.
[kaleidr] theme string must be JSON … (Warnung)	Nicht zutreffend	Der Wert theme ist eine Zeichenfolge ohne gültiges JSON. Das Panel mountet ohne das Design.

Während der Panel-Nutzung

Fehler werden Besuchern im Panel als Zeile innerhalb der Unterhaltung angezeigt. Ihr Code wird nicht benachrichtigt.

Anzeige für Besucher	Status	Ursache
"Sorry — that didn't go through. Please try again."	401	Die Sitzung ist ungültig: Schlüssel widerrufen oder abgelaufen, Ursprung aus der Zulassungsliste entfernt oder beim Mount keine Zugangsdaten übergeben.
Dasselbe	5xx oder Netzwerkfehler	Vorübergehender Fehler.
"You've reached your usage limit for now." mit Zeitpunkt der Rücksetzung, falls bekannt	429 quota_exceeded	Das KI-Guthaben der Organisation ist erschöpft oder das monatliche Schlüssellimit erreicht.
Dasselbe	429 rate_limited	Anfragelimit des Schlüssels. Alle Besucher einer Seite teilen sich denselben Schlüssel.
Dasselbe	429 visitor_limit_reached	Nur schlüsselloser Chat: Minuten- oder Tageslimit dieses Besuchers.

Fehler enthält den vollständigen Katalog; Kontingente und Ratenbegrenzungen erklärt die Grenzen.

Verwandte Seiten

• Funktionen und Grenzen
• Unterstützte Karten
• Design und Layout
• kaleidr.js und Das kaleidr-map-Element