Referencia de Chat

product: 'chat' monta el panel de Kaleidr Chat en tu página. El panel se ejecuta dentro de tu documento, no en un iframe. Se conecta a un objeto de mapa que le proporciones, a un elemento Viewer o Tile de Kaleidr que señales, o a ningún mapa para funcionar como panel de chat independiente.

Esta página es una referencia de consulta. Para crear tu primera página, empieza por una guía: Mapbox, MapLibre, Google Maps o Leaflet.

Requisitos

Plan	Free o superior
Credencial	Una clave publicable (kld_pk_live_…), o el identificador de un mapa publicado desde Studio con Control Tower activado
Permiso	ai, incluido de forma predeterminada en cada clave nueva
Origen permitido	El origen de la página, si la clave tiene una lista de orígenes permitidos
Cargador	https://cdn.kaleidr.com/embed/v1/kaleidr.js
Biblioteca de mapas	Opcional. Consulta Mapas compatibles.

Montaje mínimo

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) acepta como target un selector CSS o un elemento. Devuelve sincrónicamente un controlador y no lanza una excepción si falla el montaje. El paquete de Chat se carga y la clave se intercambia en segundo plano; si falla cualquiera de las dos operaciones, se registra un error en la consola y no se muestra nada. La única llamada que lanza una excepción es un montaje sin objeto de opciones: Kaleidr.mount('#chat') produce un TypeError.

Opciones de montaje

Todas las opciones se leen una sola vez durante el montaje. Para cambiar una, llama a destroy() y vuelve a montar. La única excepción es el tema, que puede actualizarse mediante setTheme.

Opción	Tipo	Valor predeterminado	Obligatorio	Comportamiento en Chat
product	'chat'	Ninguno	Sí	Selecciona el producto Chat.
publishableKey	cadena	Ninguno	Sí, salvo que se indique shareId	Tu clave kld_pk_…. El SDK la intercambia por un token de sesión antes de que el panel envíe solicitudes. Una clave de servidor kld_sk_… se rechaza en el navegador, con un error de consola y sin solicitud.
shareId	cadena	Ninguno	Sí, salvo que se indique publishableKey	El identificador de un mapa publicado desde Studio con Control Tower activado en su mosaico Kaleidr AI. Solo se utiliza si no se proporciona una clave. El propietario del mapa paga las consultas. El propio visor del mapa publicado ya muestra este panel. Consulta Kaleidr AI en un mapa publicado.
map	Objeto de mapa activo	Ninguno	No	El mapa en el que el asistente coloca marcadores y mueve la vista. La biblioteca se identifica a partir del objeto. Omítelo para un panel de Chat sin mapa.
mapTarget	selector CSS	Ninguno	No	Un elemento Viewer o Tile <kaleidr-map> de la misma página que controlará el panel. Se ignora si se proporciona map.
contained	booleano	false	No	true acopla el panel dentro del destino del montaje, que debe tener posición y dimensiones definidas. false lo agrega a document.body como ventana fija en la esquina superior izquierda del área visible.
lang	cadena	El valor de <html lang> de la página, si es una etiqueta de idioma válida; de lo contrario, inglés	No	Idioma de las respuestas del panel, como etiqueta BCP 47 (en, ko o pt-BR). Consulta Idioma.
title	cadena	Título tomado de la conversación	No	Título del encabezado de Chat. Consulta Título y texto indicativo.
placeholder	cadena	Ask Kaleidr	No	Texto indicativo del campo de entrada.
theme	objeto o cadena JSON que represente un objeto	Ninguno	No	Propiedades CSS personalizadas, por ejemplo { '--highlight-color': '#7c3aed' }. Se escriben en :root y afectan a toda la página.
enabled	booleano	Ninguno	No	Control de habilitación de este montaje. false lo mantiene inactivo. Consulta kaleidr.js.
apiBase	URL	https://api.kaleidr.com/inference-api	No	API a la que se envían el intercambio de sesión y las consultas. Debe incluir la ruta /inference-api.
base	URL	https://cdn.kaleidr.com	No	Origen desde el que se carga el paquete de Chat. Solo se utiliza el origen y se aceptan únicamente el CDN de Kaleidr (https://cdn.kaleidr.com), el origen desde el que se cargó kaleidr.js o el propio origen de la página. Consulta La sustitución de base.
apiKey	cadena	Ninguno	No	Alias obsoleto de publishableKey.

Opciones que Chat no utiliza

center, zoom, pitch, bearing, styleId, viewerBase y tileBase se aceptan, pero se ignoran en un montaje de Chat. El panel no establece una cámara inicial; el mapa conserva la vista que le hayas asignado.

Opciones inexistentes

No hay ninguna opción para forzar una biblioteca de mapas, activar voz ni registrar callbacks. Consulta Funciones no disponibles actualmente.

Idioma

lang establece el idioma en el que responde el panel. Se envía con cada pregunta.

Lo que proporcionas	Idioma utilizado
lang: 'ko', o lang="ko" en el elemento	Esa etiqueta, tal como se indicó.
Sin lang, en una página con <html lang="fr">	El idioma de la página, si la etiqueta tiene un formato válido.
Sin lang, en una página sin <html lang>, o con una etiqueta inválida	Inglés.

• Valores admitidos: etiquetas de idioma BCP 47: en, ko, ja, pt-BR, zh-Hant. La API rechaza las etiquetas de más de 35 caracteres y, desde entonces, cada pregunta falla con 422 lang_too_long.
• El idioma de la página solo se reutiliza cuando tiene formato válido: dos o tres letras, seguidas opcionalmente por hasta tres subetiquetas separadas por guiones de entre uno y ocho caracteres alfanuméricos. Los marcadores de plantilla sin procesar se ignoran y se usa inglés, por lo que un <html lang> erróneo no rompe Chat.
• Un lang explícito siempre prevalece sobre el idioma de la página.
• lang no traduce el título ni el texto indicativo. Sus valores predeterminados están en inglés. Define title y placeholder en el mismo idioma que lang.

Título y texto indicativo

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 sustituye el texto del campo de entrada, cuyo valor predeterminado es "Ask Kaleidr".
• title es el título de la ventana de Chat. La ventana y su encabezado aparecen al iniciar una conversación; desde entonces, muestran tu título en todas las conversaciones. Si no se proporciona title, el encabezado muestra, abreviada, la primera pregunta del visitante. Un chat minimizado muestra el título de su propia conversación, derivado de la primera pregunta del visitante, tanto si proporcionas title como si no.
• En el elemento, el atributo del título es chat-title, no title. El atributo HTML title muestra la información emergente del navegador sobre todo lo que contiene el elemento.

Qué credencial se utiliza

Lo que proporcionas	Resultado
publishableKey	La clave se intercambia por una sesión. Si también se proporciona shareId, se ignora.
Solo shareId	El mapa publicado se intercambia por una sesión.
Ninguno de los dos	El panel aparece, pero todas las preguntas fallan. No se registra ningún error durante el montaje.

Qué mapa se utiliza

Lo que proporcionas	Resultado
map	Ese objeto de mapa. Si también se indica mapTarget, se ignora.
Solo mapTarget	El elemento Viewer o Tile de Kaleidr que coincide con el selector. El selector se resuelve cuando se necesita el mapa, por lo que el elemento puede montarse después del panel.
Ninguno, o un objeto o selector no reconocido	Solo Chat: sin marcadores, movimientos de cámara ni rutas. No se registra nada.

Atributos del elemento

<kaleidr-map product="chat"> es la forma declarativa. El propio elemento es el destino del montaje.

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

Atributo	Opción que establece	Notas
product="chat"	product	Obligatorio.
publishable-key	publishableKey
share-id	shareId
map-target	mapTarget	Selector CSS.
contained	contained	Un atributo sin valor equivale a true. contained="false" equivale a false.
lang	lang	Etiqueta BCP 47. Consulta Idioma.
chat-title	title	Título del encabezado. No title, que es la información emergente HTML.
placeholder	placeholder	Texto indicativo del campo.
theme	theme	Cadena JSON. Cambiarla después del montaje aplica el nuevo valor.
flag	enabled	flag="false" mantiene inactivo el montaje.
api-base	apiBase
base	base
api-key	apiKey	Alias obsoleto de publishable-key.

Aspectos importantes de la forma de elemento:

• No admite un objeto de mapa activo. No existe un atributo para map. Para conectar tu propio mapa de Mapbox, MapLibre, Google o Leaflet, llama a Kaleidr.mount. La forma de elemento controla un Viewer o Tile mediante map-target, o funciona como Chat independiente.
• Los atributos se leen una sola vez, cuando el elemento se conecta. Solo theme se aplica cuando cambia posteriormente. Cambiar share-id, publishable-key, map-target, contained, lang, chat-title, placeholder o flag después no surte efecto; retira el elemento e inserta otro.
• Los atributos de cámara no tienen efecto. center, zoom, pitch y bearing se ignoran en el montaje de Chat, y modificarlos después registra una advertencia de "no compatible".
• El elemento usa display:block de forma predeterminada. Para contained, asígnale posición y tamaño. Los ejemplos mantienen display:block en el estilo para Safari anterior a 16.4, donde el elemento sigue siendo en línea salvo que se indique lo contrario. Consulta Temas y diseño.
• Retirar el elemento destruye el montaje. Insertarlo de nuevo monta otro panel con una nueva sesión.

La tabla completa de atributos para todos los productos está en El elemento kaleidr-map.

Controlador

Kaleidr.mount devuelve el mismo tipo de controlador para todos los productos. En Chat:

Miembro	En Chat	Comportamiento
product	'chat'	Solo lectura.
setTheme(theme)	Compatible	Acepta un objeto de propiedades CSS personalizadas o una cadena JSON que lo represente. Añade los valores a los existentes. Si una clave no empieza por --, se le añade ese prefijo. Una cadena que no sea JSON o un arreglo se ignora con una advertencia.
destroy()	Compatible	Elimina el panel, las tarjetas de lugares, los marcadores y la línea de ruta, y detiene la renovación de sesión. Se puede llamar varias veces.
setCamera(camera)	No compatible	Registra una advertencia y no hace nada. Mueve el mapa mediante la API de tu biblioteca de mapas.
setStyle(style)	No compatible	Registra una advertencia y no hace nada.

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

Las llamadas realizadas antes de que el panel termine de cargar se ponen en cola y se aplican cuando esté listo. Un destroy() ejecutado antes de que cargue cancela el montaje.

El controlador no tiene promesa ready, método on(), miembro map ni forma de enviar mensajes o leer la conversación. Si el control de habilitación está desactivado al montar, el controlador es un objeto inerte: ningún método hace nada y una advertencia en consola indica qué control bloquea el montaje.

Los métodos no compatibles registran:

[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 matriz de los cuatro productos se encuentra en El elemento kaleidr-map.

Qué hace el panel después del montaje

• Muestra una barra de entrada con "Ask Kaleidr" o con el texto que hayas establecido en placeholder. La primera pregunta la expande a una ventana de Chat.
• Cada pregunta se envía junto con el historial de esa conversación, su identificador, el nivel de zoom del mapa si está conectado y la etiqueta de idioma: tu lang, el de la página o en. Qué datos salen de la página enumera todas las solicitudes.
• Los lugares de una respuesta se convierten en tarjetas de resultados y marcadores en el mapa conectado. La cámara se desplaza hacia un lugar o encuadra varios.
• Un montaje muestra una conversación cada vez y cada conversación tiene su propio identificador. Cerrar la ventana borra la conversación y sus marcadores; la siguiente pregunta inicia una conversación nueva con otro identificador. Minimizar Chat conserva la conversación minimizada; la siguiente pregunta inicia otra y restaurar la minimizada la continúa con su identificador anterior. Al recargar la página se empieza de nuevo. No se guarda nada.

Intercambio de sesión

Tu clave publicable nunca se utiliza para enviar preguntas. Antes de que el panel realice cualquier solicitud, el SDK intercambia la clave por un token de sesión de corta duración y entrega únicamente ese token al panel.

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 }

Comportamiento	Detalle
Vinculación	La sesión es válida para el producto chat, desde el origen que la solicitó.
Renovación	El SDK solicita una nueva sesión 90 segundos antes de que caduque la actual y cuando una pestaña en segundo plano vuelve a primer plano con una sesión caducada o casi caducada.
Renovación fallida	Se reintenta cada 30 segundos mientras el panel esté montado.
Primer intercambio fallido	El montaje falla. Se registra un error, no se muestra nada y no hay reintento. Vuelve a montar para intentarlo de nuevo.
Sin clave, con shareId	El intercambio es POST …/b2b/v1/sdk/share-sessions, con el cuerpo {"share_id":"…"}. La sesión dura 300 segundos. Si se rechaza una renovación con 401, 403 o 404, el SDK deja de intentarlo hasta que se recarga la página.

Autenticación y permisos explica en detalle las claves, las sesiones y los permisos.

Ciclo de vida en una aplicación de página única

• Llama a handle.destroy() cuando se retire la vista que contiene el mapa. Destruye el panel antes de retirar el mapa para que pueda quitar sus marcadores.
• Vuelve a montar cuando regrese la vista. Esto crea un nuevo intercambio de sesión y una conversación nueva.
• destroy() deja en el documento la hoja de estilos del panel y las propiedades de tema establecidas en :root. Consulta Qué elimina y qué conserva destroy().
• Si sustituyes el objeto de mapa (por ejemplo, porque recreas el mapa), destruye el panel y vuelve a montarlo con el nuevo objeto. El panel conserva la referencia al objeto original.

Frameworks muestra el patrón de montaje y limpieza para React, Next.js y Vue.

Errores

El SDK informa de un montaje fallido con un único error en consola y no repite el motivo del servidor. Para un fallo HTTP, abre la solicitud en la pestaña Network y consulta el cuerpo JSON. Los 403 y 404 llevan su código en detail. Los 429 lo llevan en error, acompañado de una frase en detail.

Durante el montaje

Consola	Red	Causa
[kaleidr:chat] mount target not found: <selector>	Sin solicitud	El selector no coincidió con ningún elemento.
[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …	Sin solicitud	Se proporcionó una clave de servidor.
[kaleidr:chat] [kaleidr] failed to load <url>	Falló la solicitud de chat.js	El paquete se bloqueó o el CDN no estaba disponible.
Un error CORS y después otro que contiene [kaleidr:chat]	POST …/sdk/sessions bloqueado por CORS	La clave es desconocida, está revocada o caducada, o el origen de la página no figura entre los orígenes permitidos. La API solo envía encabezados CORS a los orígenes admitidos, por lo que el navegador oculta el estado y el cuerpo.
[kaleidr:chat] kaleidr session exchange failed (403)	403 insufficient_scope	La clave no tiene el permiso ai.
Lo mismo	403 product_not_allowed	La clave está restringida a productos que no incluyen chat.
Lo mismo	403 tier_capability_not_allowed	El plan de la organización no permite actualmente esta función.
[kaleidr:chat] kaleidr session exchange failed (429)	429 rate_limited	Más de 30 solicitudes de sesión de esta clave en un minuto.
[kaleidr:chat] kaleidr session exchange failed (404)	404 sessions_disabled	El intercambio de sesiones está desactivado en la plataforma. No es un problema de tu clave.
[kaleidr:chat] kaleidr session exchange failed (503)	503 sessions_not_configured	Fallo de la plataforma. Recarga para reintentar.
[kaleidr:chat] kaleidr session exchange failed (403) o (404), en un montaje con shareId y sin clave	403 chat_disabled, 403 origin_not_allowed o 404 not_found	El mapa publicado ha rechazado el chat. Consulta Kaleidr AI en un mapa publicado.
[kaleidr] embed is disabled — … (advertencia)	Sin solicitud	El control de habilitación está desactivado. El mensaje identifica qué control lo causa.
[kaleidr] theme string must be JSON … (advertencia)	No corresponde	El valor de theme era una cadena que no contiene JSON. El panel se monta sin aplicarlo.

Mientras se utiliza el panel

El panel muestra los fallos al visitante como una línea de la conversación. Tu código no recibe ninguna notificación.

Lo que ve el visitante	Estado	Causa
"Sorry — that didn't go through. Please try again."	401	La sesión ya no es válida: la clave fue revocada o caducó, los orígenes permitidos ya no incluyen este origen o no se proporcionó ninguna credencial al montar.
Lo mismo	5xx o fallo de red	Error transitorio.
"You've reached your usage limit for now." con hora de restablecimiento, si se conoce	429 quota_exceeded	Se agotaron los créditos de IA de la organización o se alcanzó el límite mensual de la clave.
Lo mismo	429 rate_limited	Límite de frecuencia de la clave. Todos los visitantes de una página comparten una clave.
Lo mismo	429 visitor_limit_reached	Solo Chat sin clave: límite por minuto o por día de este visitante.

Errores es el catálogo completo; Cuotas y límites de frecuencia explica los límites.

Páginas relacionadas

• Capacidades y límites
• Mapas compatibles
• Temas y diseño
• kaleidr.js y El elemento kaleidr-map