Ajouter Kaleidr Chat à une carte Mapbox

À la fin du guide, votre page contient une carte Mapbox GL JS avec un panneau de chat intégré. Le visiteur pose une question : la réponse s’affiche progressivement, les lieux apparaissent sous forme de marqueurs sur la carte et la caméra se déplace pour les montrer. Compatible avec toutes les offres, dont Free, à l’aide d’une clé publiable. Les questions consomment les crédits IA de votre organisation.

Avant de commencer

Une clé publiable Kaleidr (kld_pk_live_…) disponible sur kaleidr.com/api-keys. Les nouvelles clés comportent la portée ai nécessaire à Chat. Voir Obtenir une clé API.
L’origine de votre page parmi les origines autorisées de la clé, si elles sont limitées. Pour un test local, ajoutez par exemple http://localhost:8080.
Un jeton d’accès Mapbox (pk.…) issu de votre compte Mapbox. Mapbox facture la carte et Kaleidr les questions : les deux sont indépendants.
Mapbox GL JS chargé par balise script, afin que window.mapboxgl existe. Si vous importez Mapbox via npm, lisez Rendre une bibliothèque npm accessible globalement.
Un serveur HTTP, par exemple npx serve ou python -m http.server 8080. L’ouverture depuis le disque ne fonctionne pas.
Si le site applique une Content Security Policy, autorisez les hôtes de la page Content Security Policy.

Étape 1 : disposer la carte et la couche de chat

Placez la carte et la cible de montage du chat dans un même conteneur positionné. La couche du chat se superpose à la carte tout en laissant passer les événements de pointeur.

<div id="mapHost" style="position:relative; height:520px">
  <div id="map" style="position:absolute; inset:0; z-index:0"></div>
  <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
</div>

Résultat attendu : rien encore, seulement un bloc vide de 520 px. Thèmes et disposition explique chaque déclaration.

Étape 2 : charger Mapbox GL JS et créer la carte

Chargez la feuille de style dans l’en-tête et le script avant votre code. La feuille de style est indispensable : sans elle, la carte ne s’affiche pas correctement.

<link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.css" />
<script src="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.js"></script>
<script>
  mapboxgl.accessToken = 'pk.…';
  const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12',
    center: [-0.12, 51.5],
    zoom: 11,
  });
</script>

Résultat attendu : une carte Mapbox du centre de Londres, déplaçable et zoomable.

Étape 3 : charger `kaleidr.js`

Ajoutez le chargeur après le script Mapbox et avant le code qui monte le panneau.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

Résultat attendu : aucune modification visible. Dans la console, Kaleidr.version renvoie une chaîne de version.

Étape 4 : monter le panneau de chat

Fournissez votre clé et l’objet de carte actif.

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,
  contained: true,
});

Il n’est pas nécessaire d’attendre l’événement load de la carte. Kaleidr.mount renvoie immédiatement ; le panneau apparaît une fois le module de chat chargé et la clé échangée contre une session.

Résultat attendu : une barre de saisie « Ask Kaleidr » en haut à gauche de la carte.

Page complète

Enregistrez sous index.html, remplacez les deux clés et servez le dossier en HTTP.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on Mapbox</title>
    <link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.css" />
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; z-index: 0; }
      #chat { position: absolute; inset: 0; z-index: 1; pointer-events: none; }
    </style>
  </head>
  <body>
    <div id="mapHost">
      <div id="map"></div>
      <div id="chat"></div>
    </div>

    <script src="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.js"></script>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      mapboxgl.accessToken = 'pk.…';

      const map = new mapboxgl.Map({
        container: 'map',
        style: 'mapbox://styles/mapbox/streets-v12',
        center: [-0.12, 51.5],
        zoom: 11,
      });

      const handle = Kaleidr.mount('#chat', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,
        contained: true,
      });
    </script>
  </body>
</html>

Fonctionnement

Visiteur	Panneau	Carte Mapbox
Envoie une question	Ouvre une fenêtre de chat ; le texte de réponse arrive progressivement.	Rien pour le moment.
Attend	Affiche une fiche pour chaque lieu cité.	Un marqueur apparaît dès qu’un lieu est localisé. Pour un lieu, la caméra s’y déplace ; pour plusieurs, elle ajuste le cadrage en évitant le panneau.
Clique sur un marqueur ou résultat	Ouvre une fiche avec présentation, photos et outil d’itinéraire.	Cliquer sur un résultat déplace la caméra vers ce lieu.
Demande un itinéraire	Affiche la distance et la durée du trajet.	Trace et cadre la ligne de l’itinéraire.
Pose une autre question	Ajoute la question à la même conversation.	Ajoute de nouveaux marqueurs ; les précédents restent.
Ferme le chat	Revient à la barre de saisie ; la conversation se termine.	Les marqueurs et l’itinéraire sont retirés.

Particularités de Mapbox GL JS :

Les épingles sont des objets Marker de Mapbox utilisant un élément HTML, distincts des marqueurs que vous avez ajoutés.
L’itinéraire est dessiné avec des sources et couches ajoutées au style par le panneau puis supprimées. Vos propres sources et couches ne sont pas modifiées.
La session est renouvelée automatiquement tant que le panneau reste monté. Vous ne gérez aucun jeton.

Vérifier le fonctionnement

Sur la page

La barre Ask Kaleidr apparaît en haut à gauche de la carte.
Saisissez Show me three museums in London, puis appuyez sur Entrée. Le texte apparaît progressivement, trois marqueurs s’affichent et la carte les cadre tous.

Dans la console

Aucune erreur ni aucun avertissement ne contient [kaleidr.

Dans l’onglet Réseau

Requête	Résultat attendu
`GET https://cdn.kaleidr.com/embed/v1/kaleidr.js`	200
`GET https://cdn.kaleidr.com/embed/v1/chat.js`	200
`POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions`	200, avec un corps JSON semblable à l’exemple ci-dessous
`POST https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream` (après une question)	200, `content-type: text/event-stream`

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

En cas de problème

Le SDK affiche un message bref sans recopier le motif renvoyé par le serveur. Si une requête échoue, ouvrez-la dans Réseau pour lire sa réponse JSON. Un 403 ou 404 place son code dans detail. Un 429 place son code dans error, accompagné d’une phrase dans detail.

Symptôme	Cause	Correction
Panneau absent, erreur CORS sur `…/sdk/sessions` puis erreur `[kaleidr:chat]`	Clé inconnue ou révoquée, ou origine non autorisée. L’API n’envoie les en-têtes CORS qu’aux origines admises.	Vérifiez la clé et ajoutez l’origine exacte (schéma et port compris) sur kaleidr.com/api-keys.
`[kaleidr:chat] kaleidr session exchange failed (403)`	Clé valide, mais non autorisée pour Chat. `detail` vaut `insufficient_scope` (portée `ai` absente), `product_not_allowed` (autres produits seulement) ou `tier_capability_not_allowed`.	Utilisez une clé avec `ai` qui autorise `chat`.
`[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	Vous avez passé une clé serveur ; aucune requête n’a été envoyée.	Utilisez une clé publiable (`kld_pk_live_…`). Révoquez la clé serveur si elle a été exposée publiquement.
`[kaleidr:chat] mount target not found: #chat`	Le sélecteur ne trouve aucun élément.	Appelez `mount` après la création de l’élément ou passez l’élément lui-même. `mount`
`[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	Module bloqué, généralement par la CSP ou un bloqueur de publicités.	Autorisez `https://cdn.kaleidr.com` dans `script-src`.
`Kaleidr is not defined`	Votre code a été exécuté avant `kaleidr.js`, par exemple à cause de `async` ou `defer`.	Chargez `kaleidr.js` sans ces attributs avant votre code, ou déclenchez le code à l’événement `load`.
`[kaleidr] embed is disabled — …`	Le contrôle d’activation bloque les montages.	Le message indique quel contrôle a été activé. Voir kaleidr.js.
Le panneau apparaît en haut à gauche de la fenêtre, pas sur la carte	`contained` manque ou `#chat` n’est pas positionné.	Ajoutez `contained: true` et les styles de l’étape 1.
Le panneau répond, mais aucun marqueur ni déplacement	L’objet passé dans `map` n’est pas reconnu.	Passez directement l’instance `mapboxgl.Map`. Voir Cartes prises en charge.
La caméra se déplace vers un lieu, mais pas de marqueurs ni de cadrage multiple	`window.mapboxgl` n’existe pas. Un déplacement simple n’utilise que l’objet de carte ; les marqueurs et le cadrage nécessitent le global.	Si Mapbox est importé avec npm, définissez `window.mapboxgl` avant le montage. Voir Imports npm.
Le panneau dit toujours « Sorry — that didn't go through. Please try again. »	Session devenue invalide : clé révoquée ou origines autorisées modifiées.	Vérifiez la clé et rechargez la page.
Le panneau dit « You've reached your usage limit for now. »	Erreur 429 : crédits IA épuisés ou limite du débit atteinte. Tous les visiteurs utilisent la même limite de clé.	Voir Quotas et limitations de débit.
La carte ne se laisse plus déplacer	La couche de chat intercepte les événements.	Ajoutez `pointer-events:none` à `#chat`.

D’autres cas figurent sur la page Dépannage.

Limites

Votre page ne reçoit ni callback ni événement du panneau et ne peut réagir par code à une question, une réponse ou un clic sur un marqueur.
L’assistant ne voit pas vos couches, vos marqueurs ni la zone affichée. Seul le niveau de zoom accompagne la question.
Vous ne pouvez pas transmettre vos instructions ou données propres à l’assistant par le panneau.
La langue des réponses, le titre et le texte indicatif sont définis au montage (lang, title, placeholder) : voir Référence Chat. Les autres libellés restent en anglais.
handle.setCamera() n’a aucun effet sur un montage Chat et affiche un avertissement. Déplacez la caméra avec l’API de Mapbox.
Dans une application monopage, appelez handle.destroy() lorsque la vue cartographique disparaît, puis remontez-la au retour.

La liste complète se trouve dans Capacités et limites.

Étapes suivantes

Thèmes et disposition : assortissez le panneau à votre site.
Référence Chat : toutes les options, le handle et les erreurs.
Liste de vérification de production : contrôles avant mise en ligne.
Frameworks : montage sous React, Next.js et Vue.

Avant de commencer​

Étape 1 : disposer la carte et la couche de chat​

Étape 2 : charger Mapbox GL JS et créer la carte​

Étape 3 : charger kaleidr.js​

Étape 4 : monter le panneau de chat​

Page complète​

Fonctionnement​

Vérifier le fonctionnement​

En cas de problème​

Limites​

Étapes suivantes​