Capabilities and limits

This page is the precise account of the chat panel that Kaleidr.mount adds to your page: what the assistant can do, what leaves the page on each kind of request, what the panel changes in your document, and what it cannot do today. Read it before you design a product around the panel.

Everything here describes the panel loaded through kaleidr.js. If you call the HTTP API from your own backend you control the request yourself; see the Server quickstart.

What the assistant can do

• Answer questions about places in running text, streamed as it is written.
• Name places as structured results. Each place in an answer becomes a result card in the chat.
• Put those places on your map as pins, as soon as each one has coordinates.
• Move the camera: fly to a single place, or fit the view to several.
• Open a place card when the visitor clicks a pin or a result. The card shows an overview written for that place, photos, a directions tool and a box for follow-up questions about that place.
• Draw a route between two points for driving, walking, cycling or transit, and frame it.
• Keep a conversation. Follow-up questions are sent with the earlier turns, so "which of those is open late?" works.

A place the assistant cannot locate still appears as a result card. It gets no pin and does not move the camera.

What it can do on each map library

	Pins	Fly to a place	Fit several places	Route line
Mapbox GL JS	Yes	Yes, animated	Yes, padded to keep results clear of the panel	Yes
MapLibre GL JS	Yes	Yes, animated	Yes, padded to keep results clear of the panel	Yes
Google Maps JavaScript API	Yes	Yes, as a pan followed by a zoom change	Yes, with a fixed margin	Yes
Leaflet	Yes	Yes, animated	Yes, with a fixed margin	Yes
Kaleidr viewer or tile element	Yes	Yes	Yes, padded to keep results clear of the panel	Yes
No map	No	No	No	No

On Google Maps and Leaflet the fit uses the same margin on every side, so a result can land underneath the panel. Supported maps covers each library in detail, including Apple MapKit JS and Naver Maps.

What it adds to your map

• Pins are HTML elements placed with the library's own marker mechanism. They are the panel's own; it never touches markers you created.
• Routes on Mapbox GL JS and MapLibre GL JS are drawn with sources and layers the panel adds to your style and removes again. On Google Maps and Leaflet a route is two polylines, a white casing under a colored line.
• Camera moves use the library's standard calls (flyTo, fitBounds, panTo, setZoom). Your own code can move the camera at any time; the panel does not lock it.

Pins add up over a conversation: each answer adds its places to the ones already on the map. This is the same on a Kaleidr viewer or tile element, where a place the assistant sends again with different coordinates moves its pin instead of adding a second one. Closing the chat window, or destroying the panel, removes the chat's pins, its route and anything else it drew.

The panel reads the map's camera (center, zoom and bounds) and listens for zoom and move events so it can restyle its pins and reposition an open place card. On Mapbox GL JS and MapLibre GL JS it also looks through your style's layers for the label font, so that its pins match the map. All of this stays in the page: of what it reads from your map, only the zoom level is sent. It does not read your sources or your features.

What leaves the page

Every request in this table goes to https://api.kaleidr.com over HTTPS and carries the session token in an Authorization header. As with any request a browser makes, Kaleidr also sees the page's origin and the visitor's IP address. Images the panel loads from other hosts are listed below.

When	What is sent
The panel mounts	Your publishable key and the product name chat, once, to obtain a session token. The key is not sent again until the session is renewed.
The visitor sends a question	The whole conversation so far (the visitor's messages and the assistant's replies), a random id for the conversation, the map's current zoom level when a map is attached, and a language tag: your lang option, else the page's <html lang>, else en.
A place card opens	The place's name, category, address and coordinates, to write the overview and fetch details.
Photos load for a result or a place card	The place's name, category and coordinates, the language tag, and any identifier the answer itself supplied for that place.
The visitor asks a follow-up inside a place card	The question, plus that place's name, type, address and coordinates.
The visitor types in the From or To field of Directions	The text typed, the travel mode, and the coordinates of the place the card is about, to rank matches.
The visitor types a place into "Somewhere else…" under a suggestion	The text typed.
The visitor requests directions	The travel mode, and the start and end points as coordinates with a label. The start is the address the visitor picked in the From field; nothing is sent until one is picked.

Apart from what the visitor types, every value in that table is something Kaleidr produced earlier in the same conversation: a place it named, with the coordinates it returned.

With no map attached, the Directions button on a place card does not open the directions tool. It opens Google Maps in a new tab, with the place's coordinates in the address, and sends nothing to Kaleidr.

What is never sent

• Your map's layers, sources or features.
• Markers you added.
• The visible area: the map's center and bounds are not sent. Only the zoom level is.
• Your map style, access tokens or map library keys.
• The visitor's device location. The panel does not ask the browser for it.
• Page content, the page URL beyond the origin the browser attaches, cookies, or anything about the signed-in user of your site.

Because the visible area is not sent, the assistant does not know which part of the world your map is showing. A question that depends on the view ("what is around here?") has no location to work from. A question that names a place ("coffee near Borough Market") does.

What the page loads from elsewhere

• kaleidr.js and the chat bundle, from https://cdn.kaleidr.com.
• Place photos, as ordinary image requests to third-party image hosts. Those hosts see the visitor's IP address and your page as the referrer, as with any embedded image. The set of hosts varies by place, so a strict img-src policy has to be widened as you observe them.
• Site icons for links. For each link an answer cites, and for a place's website on a place card, the browser loads a small icon from Google's favicon service at https://www.google.com, which redirects to an image on https://t0.gstatic.com through https://t3.gstatic.com. The request carries the address of the linked site (its scheme and host, not the page's path), and it is made when the link is shown, without a click. Google sees that address, the visitor's IP address and your page as the referrer.

Links in the panel, such as a place's website or a map provider's page, open in a new tab and only when the visitor clicks them.

The panel's font and icons are embedded in its stylesheet as data: URIs. The panel does not load a map library; it uses the one already on your page.

Page side effects

Mounting the panel changes your document in these ways:

Change	Detail
One <style data-kaleidr-geochat> element in <head>	The panel's whole stylesheet. It is added on the first mount and reused by later ones. Its rules target the panel's own class names. It also gives default values to a set of CSS custom properties on :root at zero specificity, registers a few @property names and declares one @font-face (Goli). See Theming and layout for what that means when your site uses the same property names.
CSS custom properties on :root	Only the ones you pass in theme or setTheme. They are written to document.documentElement.style, so they apply to the whole page.
One wrapper element inside your mount target	It has no layout of its own.
The panel itself	Inside the mount target when contained is set, otherwise appended to document.body. Place cards and minimized chats follow the same rule.
Elements on your map	The pins, and the route line while one is shown.
Classes on <body>	dragging-window, resizing-hovercard and kct-sheet-dragging, each only while the visitor drags or resizes a part of the panel. They are removed when the gesture ends.
One more custom property on :root	--kct-streetview-z, which the panel sets itself to keep its street-level view stacked with its other windows.
localStorage	Up to four small preference keys, written when the visitor uses the feature: the temperature unit (kaleidr.weather.units) and three keys whose names start with dockSlot that remember where minimized chats sit. No conversation text is stored.

The panel sets no cookies and does not persist the conversation. A page reload starts a new conversation.

Each conversation has its own id. A new one starts when the visitor closes or minimizes the chat, so the next question belongs to a new conversation. A minimized chat that the visitor restores continues under the id it had.

Because the stylesheet is injected at run time, a Content Security Policy needs style-src 'unsafe-inline'. The Content Security Policy page has the full list.

What destroy() removes and leaves

Removed	Left in place
The panel, its place cards and its minimized chats	The <style data-kaleidr-geochat> element
The wrapper element in your mount target	Any :root custom properties set through theme or setTheme
Its pins and its route line	The localStorage preference keys
The session renewal timer	The loaded kaleidr.js and chat bundle scripts

To clear a theme property after destroy(), remove it yourself:

document.documentElement.style.removeProperty('--highlight-color');

Removing a <kaleidr-map product="chat"> element from the document calls destroy() for you. Adding it back mounts a new panel with a new session and a new conversation.

Signals your code gets

None. Kaleidr.mount returns a handle immediately and does not throw for a failed mount. The one exception is a call with no options object, Kaleidr.mount('#chat'), which throws a TypeError. There is no ready promise, no on() method and no DOM event for a successful mount, a failed mount, a question or an answer.

What you can observe:

• The console. A failed mount logs one error that contains [kaleidr:chat].
• The Network tab. The session request and each question are ordinary fetch calls with a status code and, on failure, a JSON body that names the reason.
• The DOM. The panel is in the document once the bundle has loaded and the session request has succeeded.

Chat reference lists the console messages and status codes.

Not available today

• Callbacks, events or hooks to your code. Nothing tells your page that a visitor asked something, that an answer or a place arrived, that a pin was clicked or that the assistant moved the map. There is no analytics hook and no way to intercept or veto an action.
• Passing your own data, context or instructions into a turn. You cannot supply system instructions, a persona, tone, a list of your locations, the contents of your map layers or tool definitions. The panel sends what the table above lists and nothing else. Answering from data your organization uploaded is a separate feature with its own requirements: see Your data.
• Translated panel labels. You can set the language of the answers (lang), the header title (title, or chat-title on the element) and the input placeholder (placeholder): see the Chat reference. The panel's other labels, such as its buttons, are in English.
• Voice. The panel takes typed questions only.
• Driving the panel from code. The handle has setTheme and destroy. You cannot send a message, read the transcript, open or close the panel, or clear its pins programmatically.
• Restricting what the assistant talks about or does. There are no topic limits, no allowlist of map actions, and no setting that confines answers to a region or to your own data.
• Per-visitor identity. Every visitor of a page uses the same publishable key. The panel has no notion of your signed-in user, and no per-user permissions or history.
• Reading your map. The assistant cannot see your layers or markers, so it cannot answer "which of the stores on this map is closest?".
• Saved conversations. Transcripts are not stored in the page and are not available to you through the SDK.
• Native mobile. There is no iOS, Android, React Native or Flutter SDK. The panel runs in a web page.

For the controls you do have (which sites may use a key, revoking it, holding mounts until a visitor consents), see the Security model.

Related pages

• Supported maps
• Theming and layout
• Chat reference
• Quota and rate limits