Référence Chat

product: 'chat' monte le panneau Kaleidr Chat dans votre page. Le panneau s’exécute dans votre document, et non dans une iframe. Il s’attache à un objet carte que vous lui transmettez, à un élément Viewer ou Tile de Kaleidr que vous désignez, ou à aucune carte pour un panneau de discussion seul.

Cette page sert de référence. Pour créer votre première page, commencez par un guide : Mapbox, MapLibre, Google Maps ou Leaflet.

Prérequis

Offre	Free ou supérieure
Identifiant	Une clé publiable (kld_pk_live_…), ou l’identifiant d’une carte Studio publiée avec Control Tower activé
Portée	ai, présente par défaut dans toute nouvelle clé
Origine autorisée	L’origine de la page, si la clé définit des origines autorisées
Chargeur	https://cdn.kaleidr.com/embed/v1/kaleidr.js
Bibliothèque cartographique	Facultative. Voir Cartes prises en charge.

Montage minimal

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) accepte un sélecteur CSS ou un élément comme target. Il renvoie de façon synchrone une poignée de contrôle et ne lève pas d’exception si le montage échoue. Le module Chat se charge et la clé est échangée en arrière-plan ; si l’une de ces opérations échoue, une erreur est inscrite dans la console et rien ne s’affiche. Seul un montage sans objet d’options lève une exception : Kaleidr.mount('#chat') déclenche une TypeError.

Options de montage

Toutes les options sont lues une seule fois au montage. Pour en modifier une, appelez destroy() puis remontez le produit. Seul le thème fait exception : setTheme permet de le mettre à jour.

Option	Type	Valeur par défaut	Obligatoire	Comportement dans Chat
product	'chat'	Aucune	Oui	Sélectionne le produit Chat.
publishableKey	chaîne	Aucune	Oui, sauf si shareId est fourni	Votre clé kld_pk_…. Le SDK l’échange contre un jeton de session avant toute requête du panneau. Une clé serveur kld_sk_… est refusée dans le navigateur, avec une erreur console et sans requête.
shareId	chaîne	Aucune	Oui, sauf si publishableKey est fourni	L’identifiant d’une carte Studio publiée dont Control Tower est activé dans sa tuile Kaleidr AI. Utilisé uniquement en l’absence de clé. Les questions sont facturées au propriétaire de la carte. La visionneuse de la carte publiée affiche déjà ce panneau. Voir Kaleidr AI sur une carte publiée.
map	Objet carte actif	Aucune	Non	La carte sur laquelle l’assistant place des repères et déplace la vue. La bibliothèque est reconnue à partir de l’objet. À omettre pour un panneau sans carte.
mapTarget	sélecteur CSS	Aucune	Non	Élément Viewer ou Tile <kaleidr-map> de la même page que le panneau doit piloter. Ignoré si map est fourni.
contained	booléen	false	Non	true ancre le panneau dans la cible de montage, qui doit être positionnée et dimensionnée. false l’ajoute à document.body comme fenêtre fixe en haut à gauche de la fenêtre du navigateur.
lang	chaîne	Le <html lang> de la page si sa balise de langue est valide, sinon l’anglais	Non	Langue des réponses, indiquée par une balise BCP 47 comme en, ko ou pt-BR. Voir Langue.
title	chaîne	Un titre tiré de la conversation	Non	Titre affiché dans l’en-tête du panneau. Voir Titre et texte indicatif.
placeholder	chaîne	Ask Kaleidr	Non	Texte indicatif du champ de saisie.
theme	objet ou chaîne JSON représentant un objet	Aucune	Non	Propriétés CSS personnalisées à appliquer, par exemple { '--highlight-color': '#7c3aed' }. Elles sont définies sur :root et s’appliquent à toute la page.
enabled	booléen	Aucune	Non	Contrôle d’activation propre à ce montage. false suspend le montage. Voir kaleidr.js.
apiBase	URL	https://api.kaleidr.com/inference-api	Non	API utilisée pour l’échange de session et les questions. Le chemin /inference-api est obligatoire.
base	URL	https://cdn.kaleidr.com	Non	Origine de chargement du module Chat. Seule l’origine est utilisée ; seules celles du CDN Kaleidr (https://cdn.kaleidr.com), du chargeur kaleidr.js ou de la page sont acceptées. Voir Remplacement de la base.
apiKey	chaîne	Aucune	Non	Ancien alias de publishableKey, déconseillé.

Options ignorées par Chat

center, zoom, pitch, bearing, styleId, viewerBase et tileBase sont acceptés mais ignorés dans un montage Chat. Le panneau ne définit pas de caméra initiale : la carte conserve la vue choisie.

Options inexistantes

Il n’existe aucune option pour imposer une bibliothèque cartographique, activer la voix ou fournir un callback. Voir Fonctions actuellement indisponibles.

Langue

lang définit la langue des réponses du panneau. Il est envoyé avec chaque question.

Paramètre transmis	Langue utilisée
lang: 'ko' ou lang="ko" sur l’élément	Cette balise, telle quelle.
Aucun lang sur une page avec <html lang="fr">	Langue de la page, si la balise est correctement formée.
Aucun lang, et aucun <html lang> valide sur la page	Anglais.

• Valeurs acceptées : balises de langue BCP 47, comme en, ko, ja, pt-BR, zh-Hant. Au-delà de 35 caractères, l’API refuse la balise et chaque question échoue avec 422 lang_too_long.
• La langue de la page n’est reprise que si sa balise est valide : deux ou trois lettres, éventuellement suivies d’au maximum trois sous-balises séparées par des tirets, comprenant une à huit lettres ou chiffres. Une variable de modèle non remplacée est ignorée au profit de l’anglais ; un <html lang> défectueux ne fait donc pas échouer Chat.
• Un lang explicite est toujours prioritaire sur la langue de la page.
• lang ne traduit ni le titre ni le texte indicatif. Leurs valeurs par défaut sont en anglais. Définissez title et placeholder dans la même langue que lang.

Titre et texte indicatif

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 remplace le texte de saisie, « Ask Kaleidr » par défaut.
• title est le titre de la fenêtre de discussion. Cette fenêtre et son en-tête apparaissent au début d’une conversation ; l’en-tête affiche ensuite le titre fourni pour toutes les conversations. Sans title, il affiche en version abrégée la première question du visiteur. Une discussion réduite affiche son propre titre, issu de la première question du visiteur, que vous fournissiez title ou non.
• Sur l’élément, l’attribut de titre est chat-title, pas title. L’attribut HTML title correspond à l’infobulle du navigateur et apparaît au survol de tout le contenu de l’élément.

Identifiant utilisé

Paramètre transmis	Résultat
publishableKey	La clé est échangée contre une session. Si shareId est aussi fourni, il est ignoré.
shareId seul	La carte publiée est échangée contre une session.
Aucun des deux	Le panneau s’affiche, mais toutes les questions échouent. Aucune erreur n’est consignée au montage.

Carte utilisée

Paramètre transmis	Résultat
map	Cet objet carte. mapTarget est ignoré s’il est également fourni.
mapTarget seul	Élément Viewer ou Tile de Kaleidr correspondant au sélecteur. Le sélecteur est résolu à chaque besoin ; l’élément peut donc être monté après le panneau.
Aucun, ou un objet ou sélecteur non reconnu	Discussion seule : ni repères, ni mouvement de caméra, ni itinéraire. Aucun message console.

Attributs de l’élément

<kaleidr-map product="chat"> est la forme déclarative. L’élément lui-même sert de cible de montage.

<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	Option définie	Remarques
product="chat"	product	Obligatoire.
publishable-key	publishableKey
share-id	shareId
map-target	mapTarget	Sélecteur CSS.
contained	contained	Un attribut sans valeur vaut true. contained="false" vaut false.
lang	lang	Balise BCP 47. Voir Langue.
chat-title	title	Titre de l’en-tête, et non title, qui désigne l’infobulle HTML.
placeholder	placeholder	Texte indicatif du champ.
theme	theme	Chaîne JSON. La modifier après le montage applique la nouvelle valeur.
flag	enabled	flag="false" suspend le montage.
api-base	apiBase
base	base
api-key	apiKey	Ancien alias de publishable-key.

Précisions sur la forme déclarative :

• Elle ne peut recevoir aucun objet carte actif. Il n’existe pas d’attribut map. Pour raccorder votre propre carte Mapbox, MapLibre, Google ou Leaflet, utilisez Kaleidr.mount. L’élément peut piloter un Viewer ou un Tile grâce à map-target, ou fonctionner sans carte.
• Les attributs sont lus une fois, à la connexion de l’élément. Seul theme est appliqué lors de ses modifications ultérieures. Changer ensuite share-id, publishable-key, map-target, contained, lang, chat-title, placeholder ou flag ne produit aucun effet : retirez puis réinsérez un nouvel élément.
• Les attributs de caméra ne servent à rien. center, zoom, pitch et bearing sont ignorés au montage de Chat ; les modifier ensuite déclenche un avertissement « non pris en charge ».
• L’élément est display:block par défaut. Avec contained, donnez-lui une position et des dimensions. Les exemples conservent display:block dans le style pour Safari avant 16.4, où l’élément demeure en ligne sauf indication contraire. Voir Thème et mise en page.
• Retirer l’élément détruit le montage. Le réinsérer crée un panneau et une session neufs.

Le tableau complet des attributs des quatre produits se trouve dans L’élément kaleidr-map.

Poignée de contrôle

Kaleidr.mount renvoie une poignée ayant la même structure pour tous les produits. Pour Chat :

Membre	Sur Chat	Comportement
product	'chat'	Lecture seule.
setTheme(theme)	Pris en charge	Reçoit un objet de propriétés CSS personnalisées ou sa représentation JSON. Ajoute les valeurs aux paramètres existants. Un nom sans préfixe -- le reçoit automatiquement. Une chaîne JSON invalide ou un tableau est ignoré avec un avertissement.
destroy()	Pris en charge	Supprime le panneau, ses cartes de lieux, ses repères et son tracé d’itinéraire ; arrête le renouvellement de session. Peut être rappelé sans risque.
setCamera(camera)	Non pris en charge	Affiche un avertissement et ne fait rien. Utilisez l’API de votre bibliothèque pour déplacer la carte.
setStyle(style)	Non pris en charge	Affiche un avertissement et ne fait rien.

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

Les appels effectués avant le chargement du panneau sont mis en attente puis appliqués lorsqu’il est prêt. Un destroy() avant la fin du chargement annule le montage.

La poignée n’a ni promesse ready, ni méthode on(), ni membre map, ni moyen d’envoyer un message ou de lire la conversation. Si le contrôle d’activation est désactivé au montage, la poignée est un objet inerte : toutes ses méthodes sont sans effet et un avertissement console indique le contrôle qui bloque le montage.

Les méthodes non prises en charge affichent :

[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.

La matrice des quatre produits se trouve dans L’élément kaleidr-map.

Comportement du panneau après le montage

• Il affiche une barre de saisie indiquant « Ask Kaleidr », ou votre placeholder. La première question l’agrandit en fenêtre de discussion.
• Chaque question est envoyée avec l’historique de la conversation, son identifiant, le niveau de zoom de la carte si elle est attachée et la balise de langue : votre lang, celui de la page, ou en. La page Données quittant la page recense toutes les requêtes.
• Les lieux cités dans une réponse deviennent des fiches de résultats et des repères sur la carte associée. La caméra se déplace vers un lieu ou cadre plusieurs lieux.
• Chaque montage affiche une conversation à la fois, dotée de son propre identifiant. Fermer la fenêtre efface la conversation et ses repères ; la question suivante crée une nouvelle conversation et un nouvel identifiant. Réduire une conversation la conserve dans cet état ; la question suivante en ouvre une autre, et restaurer la conversation réduite la reprend avec son ancien identifiant. Un rechargement recommence à zéro. Aucune donnée n’est conservée.

Échange de session

Votre clé publiable n’est jamais utilisée pour poser des questions. Avant la première requête du panneau, le SDK l’échange contre un jeton de session à durée limitée et ne transmet que ce jeton au panneau.

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 }

Comportement	Précisions
Liaison	La session est valide pour le produit chat, depuis l’origine qui l’a demandée.
Renouvellement	Le SDK demande une nouvelle session 90 secondes avant l’expiration de la session en cours, ou lorsqu’un onglet revient au premier plan avec une session expirée ou presque expirée.
Échec du renouvellement	Nouvelle tentative toutes les 30 secondes tant que le panneau reste monté.
Échec du premier échange	Le montage échoue. Une erreur est consignée, rien ne s’affiche et aucune nouvelle tentative n’a lieu. Remontez pour réessayer.
Sans clé, avec shareId	Échange par POST …/b2b/v1/sdk/share-sessions, avec le corps {"share_id":"…"}. La session dure 300 secondes. Si un renouvellement est refusé avec 401, 403 ou 404, le SDK cesse de demander jusqu’au rechargement de la page.

Authentification et portées décrit précisément clés, sessions et portées.

Cycle de vie dans une application monopage

• Appelez handle.destroy() lorsque la vue contenant la carte est supprimée. Détruisez le panneau avant la carte pour lui laisser retirer ses repères.
• Remontez le panneau au retour de la vue. Cela crée un nouvel échange de session et une nouvelle conversation.
• destroy() laisse dans le document la feuille de style du panneau et les propriétés de thème définies sur :root. Voir Ce que destroy() retire et conserve.
• Si vous remplacez l’objet carte, par exemple en recréant la carte, détruisez le panneau puis remontez-le avec le nouvel objet. Le panneau conserve l’objet reçu au montage.

Frameworks présente les modèles de montage et nettoyage pour React, Next.js et Vue.

Erreurs

Le SDK signale un échec de montage par une unique erreur console, sans reprendre la raison donnée par le serveur. Pour une erreur HTTP, ouvrez la requête dans l’onglet Réseau et lisez le corps JSON. Une réponse 403 ou 404 contient son code dans detail. Une réponse 429 contient le code dans error, accompagné d’une phrase dans detail.

Au montage

Console	Réseau	Cause
[kaleidr:chat] mount target not found: <selector>	Aucune requête	Le sélecteur ne correspond à aucun élément.
[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …	Aucune requête	Une clé serveur a été fournie.
[kaleidr:chat] [kaleidr] failed to load <url>	Échec de la requête chat.js	Le module a été bloqué ou le CDN était inaccessible.
Erreur CORS, suivie d’une erreur contenant [kaleidr:chat]	POST …/sdk/sessions bloqué par CORS	La clé est inconnue, révoquée ou expirée, ou l’origine de la page n’est pas autorisée. L’API n’envoie des en-têtes CORS qu’aux origines admises ; le navigateur masque donc le statut et le corps.
[kaleidr:chat] kaleidr session exchange failed (403)	403 insufficient_scope	La clé n’a pas la portée ai.
Idem	403 product_not_allowed	La clé est limitée à des produits autres que chat.
Idem	403 tier_capability_not_allowed	L’offre de l’organisation ne permet pas cette fonction actuellement.
[kaleidr:chat] kaleidr session exchange failed (429)	429 rate_limited	Plus de 30 demandes de session pour cette clé en une minute.
[kaleidr:chat] kaleidr session exchange failed (404)	404 sessions_disabled	L’échange de session est désactivé sur la plateforme ; la clé n’y est pour rien.
[kaleidr:chat] kaleidr session exchange failed (503)	503 sessions_not_configured	Défaillance de la plateforme. Rechargez pour réessayer.
[kaleidr:chat] kaleidr session exchange failed (403) ou (404) avec shareId sans clé	403 chat_disabled, 403 origin_not_allowed ou 404 not_found	La carte publiée a refusé la discussion. Voir Kaleidr AI sur une carte publiée.
[kaleidr] embed is disabled — … (avertissement)	Aucune requête	Le contrôle d’activation est désactivé. Le message indique lequel.
[kaleidr] theme string must be JSON … (avertissement)	Sans objet	La valeur theme est une chaîne qui n’est pas du JSON. Le panneau se monte sans l’appliquer.

Pendant l’utilisation du panneau

Le panneau indique les échecs au visiteur sous forme d’une ligne dans la conversation. Votre code ne reçoit aucune notification.

Message vu par le visiteur	Statut	Cause
"Sorry — that didn't go through. Please try again."	401	La session n’est plus valide : clé révoquée ou expirée, origine supprimée des origines autorisées, ou absence d’identifiant au montage.
Idem	5xx ou erreur réseau	Défaillance temporaire.
"You've reached your usage limit for now." avec l’heure de remise à zéro si connue	429 quota_exceeded	Les crédits IA de l’organisation sont épuisés ou le plafond mensuel de la clé est atteint.
Idem	429 rate_limited	Limite de fréquence de la clé. Tous les visiteurs d’une page partagent la même clé.
Idem	429 visitor_limit_reached	Discussion sans clé uniquement : limite par minute ou par jour de ce visiteur.

Erreurs est le catalogue complet et Quotas et limites de fréquence explique les limites.

Pages associées

• Fonctionnalités et limites
• Cartes prises en charge
• Thèmes et disposition
• kaleidr.js et L’élément kaleidr-map