Skip to main content

Chat

Kaleidr Chat is a chat panel that you add to a page that already shows a map. A visitor types a question ("Where can I get breakfast near the Tate Modern?"), the answer streams into the panel, and the places in that answer appear as pins on your map while the camera moves to show them.

The panel runs in your page, not in an iframe. You load one script, call Kaleidr.mount with your publishable key and your live map object, and the panel attaches to that map. You keep your map library, your style, your layers and your own controls.

What the visitor experiences​

  1. An input bar that reads Ask Kaleidr sits over the top-left corner of the map.
  2. The visitor sends a question. The bar expands into a chat window and the answer streams in as text.
  3. Each place named in the answer becomes a result card in the chat and a pin on the map. One place makes the camera fly to it; several places make the camera fit all of them.
  4. Clicking a pin or a result opens a place card with a short overview, photos, directions and a box for a follow-up question about that place.
  5. Asking for directions draws a route line on the map and frames it.
  6. Pins from earlier questions stay on the map for the rest of the conversation, on every supported map and on a Kaleidr viewer or tile element. Closing the chat window ends the conversation and removes its pins and its route.

On a viewport 768 px wide or narrower, the panel is laid out as a bottom sheet instead of a floating window.

What it does to your map​

It doesIt does not
Add and remove its own pinsRead, change or remove your layers, sources or markers
Move the camera to a place, or fit it to severalSend your layers, your markers or the visible area to Kaleidr
Draw a route line, and remove it againCall back into your code when something happens
Read the current zoom level, and send it with each question. On Mapbox GL JS and MapLibre GL JS it also reads the camera and your style's label font, in the page only, to place and letter its pinsTake over your map's controls or gestures

The exact behavior differs a little by map library, because each library offers different camera and drawing calls. Supported maps has the matrix, and Capabilities and limits lists every request the panel makes and what each one carries.

What it needs​

RequirementValue
PlanFree and up. Questions spend your organization's AI credits.
KeyA publishable key, kld_pk_live_…, from kaleidr.com/api-keys.
Scopeai. Every new key carries it by default.
Allowed originIf the key lists allowed origins, the page's origin must be one of them.
Map libraryMapbox GL JS, MapLibre GL JS, Google Maps JavaScript API or Leaflet, loaded as a page global before the mount.
PageServed over HTTP or HTTPS. A file opened from disk is not a usable origin.
Content Security PolicyIf your site sets one, allow the hosts on the Content Security Policy page.

Get an API key walks through creating the key and setting its allowed origins.

Three ways to run it​

You haveYou passResult
Your own Mapbox, MapLibre, Google or Leaflet mappublishableKey and mapThe panel drives your map. This is the common case.
A map published from Kaleidr StudioNothing: embed the map, with Control Tower on in its Kaleidr AI tileThe map carries the panel, and the map's owner pays for the questions. See Kaleidr AI on a published map.
No mappublishableKey onlyA chat-only panel: answers and place cards, no pins and no camera moves.

The smallest working page​

This page shows a MapLibre map with the chat panel docked inside it. Replace the key, save the file, and serve it from an origin the key allows, for example http://localhost:8080.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
  </head>
  <body>
    <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>

    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json',
        center: [-0.12, 51.5],
        zoom: 11,
      });

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

contained: true docks the panel inside #chat. Without it the panel is a fixed window at the top-left of the browser viewport, wherever the map is on the page. Theming and layout explains both layouts.

What it does not do​

State these limits to your team before you build on the panel:

  • No callbacks or events. Your code is not told when a visitor asks a question, when an answer arrives or when a pin is clicked.
  • No way to pass your own context. You cannot give the assistant system instructions, a persona, a list of your stores or the contents of your layers through the panel. Answering from your organization's uploaded data is a separate, plan-gated feature: see Your data.
  • No native mobile SDK. The panel is for web pages.

What you can set: the language of the answers, the panel's header title and its input placeholder, with the lang, title and placeholder options. With no lang, the panel uses your page's <html lang>. See the Chat reference.

The complete list is on Capabilities and limits. If you need full control over the conversation and the interface, call the HTTP API from your backend instead: see the Server quickstart.

Where to go next​