Referência do Chat

product: 'chat' monta o painel do Kaleidr Chat na sua página. O painel é executado no próprio documento, não em um iframe. Ele se conecta a um objeto de mapa fornecido por você, a um elemento Viewer ou Tile da Kaleidr indicado na página, ou funciona sem mapa, como painel somente de chat.

Esta página é uma referência para consulta. Para criar sua primeira página, comece com um guia: Mapbox, MapLibre, Google Maps ou Leaflet.

Requisitos

Plano	Free ou superior
Credencial	Uma chave publicável (kld_pk_live_…), ou o ID de um mapa publicado no Studio com Control Tower ativado
Escopo	ai, presente em todas as novas chaves por padrão
Origem permitida	A origem da página, caso a chave tenha uma lista de origens permitidas
Carregador	https://cdn.kaleidr.com/embed/v1/kaleidr.js
Biblioteca de mapas	Opcional. Consulte Mapas compatíveis.

Montagem mínima

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) recebe um seletor CSS ou um elemento como target. Retorna um controlador de forma síncrona e não lança exceção quando a montagem falha. O pacote do Chat é carregado e a chave é trocada em segundo plano; caso um deles falhe, uma mensagem de erro é registrada no console e nada é renderizado. A única chamada que lança exceção é uma montagem sem objeto de opções: Kaleidr.mount('#chat') gera um TypeError.

Opções de montagem

Todas as opções são lidas uma vez, durante a montagem. Para alterar uma delas, chame destroy() e monte novamente. A única exceção é o tema, que pode ser atualizado com setTheme.

Opção	Tipo	Padrão	Obrigatória	Comportamento no Chat
product	'chat'	Nenhum	Sim	Seleciona o produto Chat.
publishableKey	string	Nenhum	Sim, a menos que shareId seja informado	Sua chave kld_pk_…. O SDK a troca por um token de sessão antes de o painel fazer qualquer solicitação. Uma chave de servidor kld_sk_… é rejeitada no navegador, com erro no console e sem enviar a solicitação.
shareId	string	Nenhum	Sim, a menos que publishableKey seja informado	ID de um mapa publicado no Studio com Control Tower ativado no bloco Kaleidr AI dele. Usado apenas quando nenhuma chave é fornecida. O proprietário do mapa paga pelas perguntas. O próprio visualizador do mapa publicado já mostra esse painel. Consulte Kaleidr AI em um mapa publicado.
map	Objeto de mapa ativo	Nenhum	Não	O mapa em que o assistente coloca marcadores e movimenta a câmera. A biblioteca é identificada pelo objeto. Omita para um painel sem mapa.
mapTarget	seletor CSS	Nenhum	Não	Elemento Viewer ou Tile <kaleidr-map> na mesma página que o painel deve controlar. Ignorado se map for fornecido.
contained	booleano	false	Não	true fixa o painel dentro do alvo da montagem, que precisa ter posição e dimensões definidas. false o adiciona a document.body como janela fixa no canto superior esquerdo da área visível.
lang	string	O <html lang> da página, se for uma tag de idioma bem formada; caso contrário, inglês	Não	Idioma das respostas, como tag BCP 47, por exemplo en, ko ou pt-BR. Consulte Idioma.
title	string	Título obtido da conversa	Não	Título no cabeçalho da janela de Chat. Consulte Título e placeholder.
placeholder	string	Ask Kaleidr	Não	Texto de exemplo no campo de entrada.
theme	objeto ou string JSON de um objeto	Nenhum	Não	Propriedades CSS personalizadas, por exemplo { '--highlight-color': '#7c3aed' }. São aplicadas a :root e afetam toda a página.
enabled	booleano	Nenhum	Não	Controle de ativação específico da montagem. false mantém esta montagem suspensa. Consulte kaleidr.js.
apiBase	URL	https://api.kaleidr.com/inference-api	Não	API utilizada na troca de sessão e nas perguntas. Precisa incluir o caminho /inference-api.
base	URL	https://cdn.kaleidr.com	Não	Origem de onde o pacote do Chat é carregado. Somente a origem é considerada, e apenas o CDN da Kaleidr (https://cdn.kaleidr.com), a origem de carregamento de kaleidr.js ou a origem da própria página são aceitos. Consulte Substituição da base.
apiKey	string	Nenhum	Não	Alias obsoleto de publishableKey.

Opções ignoradas pelo Chat

center, zoom, pitch, bearing, styleId, viewerBase e tileBase são aceitos, mas ignorados ao montar o Chat. O painel não define uma câmera inicial; o mapa mantém a visualização que você configurou.

Opções que não existem

Não existe opção para impor uma biblioteca de mapas, habilitar voz ou informar callbacks. Consulte Indisponível atualmente.

Idioma

lang define o idioma em que o painel responde. Ele é enviado com cada pergunta.

O que você informa	Idioma utilizado
lang: 'ko' ou lang="ko" no elemento	Essa tag, exatamente como foi informada.
Sem lang, em uma página com <html lang="fr">	O idioma da página, se a tag estiver bem formada.
Sem lang, em uma página sem <html lang> ou com uma tag inválida	Inglês.

• Valores aceitos: tags de idioma BCP 47: en, ko, ja, pt-BR, zh-Hant. A API rejeita tags com mais de 35 caracteres, e todas as perguntas passam a falhar com 422 lang_too_long.
• O idioma da página só é usado quando está bem formado: duas ou três letras, seguidas opcionalmente de até três subtags separadas por hífen, de um a oito caracteres alfanuméricos. Um placeholder de modelo não processado é ignorado e o inglês é usado, de modo que um <html lang> incorreto não interrompe o Chat.
• Um lang informado explicitamente sempre tem prioridade sobre o idioma da página.
• lang não traduz o título nem o placeholder. Os valores padrão são em inglês. Configure title e placeholder no mesmo idioma de lang.

Título e placeholder

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 substitui o texto do campo, que por padrão é “Ask Kaleidr”.
• title é o título da janela de Chat. A janela e seu cabeçalho aparecem quando uma conversa começa; a partir daí, o cabeçalho mostra seu título em todas as conversas. Sem title, o cabeçalho apresenta, abreviada, a primeira pergunta do visitante. Um chat minimizado mostra o título da sua própria conversa, derivado da primeira pergunta, independentemente de você ter informado title.
• No elemento, o atributo do título é chat-title, não title. Em HTML, title representa a dica exibida pelo navegador ao passar o cursor e aparece sobre o conteúdo do elemento.

Qual credencial é usada

O que você informa	Resultado
publishableKey	A chave é trocada por uma sessão. Se shareId também for informado, será ignorado.
Apenas shareId	O mapa publicado é trocado por uma sessão.
Nenhum dos dois	O painel aparece, mas todas as perguntas falham. Nenhum erro é registrado na montagem.

Qual mapa é usado

O que você informa	Resultado
map	Esse objeto de mapa. mapTarget é ignorado se também for informado.
Apenas mapTarget	O elemento Viewer ou Tile da Kaleidr que corresponde ao seletor. O seletor é resolvido a cada vez que o mapa é necessário; portanto, o elemento pode ser montado após o painel.
Nenhum, ou objeto/seletor não reconhecido	Somente chat: sem marcadores, movimentos de câmera ou rotas. Nada é registrado.

Atributos do elemento

<kaleidr-map product="chat"> é a forma declarativa. O próprio elemento é o alvo da montagem.

<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	Opção definida	Observações
product="chat"	product	Obrigatório.
publishable-key	publishableKey
share-id	shareId
map-target	mapTarget	Seletor CSS.
contained	contained	O atributo sem valor significa true. contained="false" significa false.
lang	lang	Tag BCP 47. Consulte Idioma.
chat-title	title	Título do cabeçalho. Não title, que é a dica de ferramenta do HTML.
placeholder	placeholder	Texto de exemplo do campo.
theme	theme	String JSON. A alteração após a montagem aplica o novo valor.
flag	enabled	flag="false" suspende a montagem.
api-base	apiBase
base	base
api-key	apiKey	Alias obsoleto de publishable-key.

Observações sobre a forma declarativa:

• Não pode receber um objeto de mapa ativo. Não existe atributo para map. Para conectar seus próprios mapas Mapbox, MapLibre, Google ou Leaflet, chame Kaleidr.mount. A forma de elemento controla um Viewer ou Tile da Kaleidr por map-target, ou funciona só como Chat.
• Os atributos são lidos uma vez quando o elemento é conectado. Apenas theme é aplicado quando alterado posteriormente. Modificar share-id, publishable-key, map-target, contained, lang, chat-title, placeholder ou flag depois não tem efeito; remova e insira um novo elemento.
• Os atributos de câmera não têm efeito. center, zoom, pitch e bearing são ignorados ao montar o Chat, e alterá-los posteriormente registra um aviso de recurso não suportado.
• O elemento usa display:block por padrão. Com contained, dê a ele posição e tamanho. Os exemplos mantêm display:block no estilo para versões do Safari anteriores à 16.4, em que o elemento permanece inline a menos que seja especificado de outra forma. Consulte Temas e layout.
• Remover o elemento destrói a montagem. Inserir novamente cria um novo painel com uma nova sessão.

A tabela completa de atributos de todos os produtos está em O elemento kaleidr-map.

Controlador

Kaleidr.mount retorna a mesma estrutura de controlador para todos os produtos. No Chat:

Membro	No Chat	Comportamento
product	'chat'	Somente leitura.
setTheme(theme)	Suportado	Aceita um objeto de propriedades CSS personalizadas ou uma string JSON. Acrescenta os novos valores aos já definidos. Uma chave sem -- recebe esse prefixo. Strings inválidas ou arrays são ignorados com um aviso.
destroy()	Suportado	Remove o painel, os cartões de lugares, os marcadores e a linha da rota, e interrompe a renovação da sessão. Pode ser chamado mais de uma vez.
setCamera(camera)	Não suportado	Registra um aviso e não faz nada. Use a API da sua biblioteca de mapas para mover o mapa.
setStyle(style)	Não suportado	Registra um aviso e não faz nada.

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

Chamadas feitas antes do carregamento do painel são enfileiradas e aplicadas quando ele fica pronto. Um destroy() antes do carregamento cancela a montagem.

O controlador não tem promessa ready, método on(), membro map nem maneira de enviar uma mensagem ou ler a conversa. Se a ativação estiver desabilitada na montagem, o controlador será um objeto inerte: os métodos não fazem nada, e um aviso no console identifica o controle que suspendeu a montagem.

Os métodos não suportados registram:

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

A matriz de todos os quatro produtos está em O elemento kaleidr-map.

O que o painel faz após a montagem

• Renderiza uma barra de entrada com “Ask Kaleidr” ou seu placeholder. A primeira pergunta a expande para uma janela de Chat.
• Cada pergunta é enviada com o histórico da conversa, o ID dessa conversa, o nível de zoom do mapa conectado e a tag de idioma: seu lang, o da página ou en. O que sai da página lista cada solicitação.
• Os lugares mencionados em uma resposta viram cartões de resultado e marcadores no mapa conectado. A câmera se desloca para um lugar ou enquadra vários lugares.
• Uma montagem exibe uma conversa de cada vez, e cada conversa tem seu próprio ID. Fechar a janela limpa a conversa e os marcadores; a próxima pergunta inicia uma nova conversa com outro ID. Minimizar o Chat preserva a conversa minimizada; a pergunta seguinte inicia uma nova, e restaurar a minimizada continua a conversa com o ID anterior. Recarregar a página recomeça tudo. Nada é persistido.

Troca de sessão

Sua chave publicável nunca é usada para fazer perguntas. Antes de qualquer solicitação do painel, o SDK troca a chave por um token de sessão de curta duração e entrega somente esse token ao painel.

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 }

Comportamento	Detalhe
Vinculação	A sessão é válida para o produto chat a partir da origem que a solicitou.
Renovação	O SDK solicita uma nova sessão 90 segundos antes do vencimento, ou quando uma aba em segundo plano volta a ficar visível com uma sessão vencida ou quase vencida.
Renovação malsucedida	Repetida a cada 30 segundos enquanto o painel permanece montado.
Primeira troca malsucedida	A montagem falha. Um erro é registrado, nada aparece e não há nova tentativa. Monte novamente para tentar de novo.
Sem chave, com shareId	A troca usa POST …/b2b/v1/sdk/share-sessions com o corpo {"share_id":"…"}. A sessão dura 300 segundos. Se a renovação for recusada com 401, 403 ou 404, o SDK deixa de solicitar até a página ser recarregada.

Autenticação e escopos descreve chaves, sessões e escopos em detalhes.

Ciclo de vida em um aplicativo de página única

• Chame handle.destroy() quando a visualização que contém o mapa for removida. Destrua o painel antes de remover o mapa, para que seus marcadores possam ser retirados.
• Monte novamente quando a visualização retornar. Isso gera uma nova troca de sessão e uma nova conversa.
• destroy() deixa no documento a folha de estilos do painel e as propriedades de tema em :root. Consulte O que destroy() remove e mantém.
• Se substituir o objeto de mapa (por exemplo, recriando o mapa), destrua o painel e monte novamente com o novo objeto. O painel mantém a referência ao objeto originalmente fornecido.

Frameworks mostra os padrões de montagem e limpeza para React, Next.js e Vue.

Erros

O SDK relata uma montagem malsucedida com um único erro no console, sem repetir a causa informada pelo servidor. Para falhas HTTP, abra a solicitação na aba Network e leia o corpo JSON. Um 403 ou 404 traz o código no campo detail. Um 429 traz o código em error, com uma descrição em detail.

Na montagem

Console	Rede	Causa
[kaleidr:chat] mount target not found: <selector>	Nenhuma solicitação	O seletor não correspondeu a nenhum elemento.
[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …	Nenhuma solicitação	Foi passada uma chave de servidor.
[kaleidr:chat] [kaleidr] failed to load <url>	Falhou a solicitação de chat.js	O pacote foi bloqueado ou o CDN estava indisponível.
Erro CORS, seguido de erro com [kaleidr:chat]	POST …/sdk/sessions bloqueado por CORS	A chave é desconhecida, revogada ou expirada, ou a origem da página não está na lista de origens permitidas. A API só envia cabeçalhos CORS a origens admitidas, de modo que o navegador oculta o status e o corpo.
[kaleidr:chat] kaleidr session exchange failed (403)	403 insufficient_scope	A chave não tem o escopo ai.
O mesmo	403 product_not_allowed	A chave está restrita a produtos que não incluem chat.
O mesmo	403 tier_capability_not_allowed	O plano da organização não permite esse recurso no momento.
[kaleidr:chat] kaleidr session exchange failed (429)	429 rate_limited	Mais de 30 solicitações de sessão com a chave em um minuto.
[kaleidr:chat] kaleidr session exchange failed (404)	404 sessions_disabled	A troca de sessão está desativada na plataforma. Não é culpa da sua chave.
[kaleidr:chat] kaleidr session exchange failed (503)	503 sessions_not_configured	Falha na plataforma. Recarregue e tente de novo.
[kaleidr:chat] kaleidr session exchange failed (403) ou (404) em montagem com shareId e sem chave	403 chat_disabled, 403 origin_not_allowed ou 404 not_found	O mapa publicado recusou o chat. Consulte Kaleidr AI em um mapa publicado.
[kaleidr] embed is disabled — … (aviso)	Nenhuma solicitação	O controle de ativação está desligado. A mensagem indica qual controle o bloqueou.
[kaleidr] theme string must be JSON … (aviso)	Não se aplica	O valor theme era uma string que não contém JSON. O painel é montado sem aplicá-la.

Durante o uso do painel

O painel mostra as falhas ao visitante como uma linha na conversa. Seu código não recebe notificação.

O que o visitante vê	Status	Causa
"Sorry — that didn't go through. Please try again."	401	A sessão deixou de ser válida: a chave foi revogada ou expirou, a origem foi removida das origens permitidas, ou nenhuma credencial foi fornecida na montagem.
O mesmo	5xx ou falha de rede	Falha transitória.
"You've reached your usage limit for now." com horário de reinício, quando conhecido	429 quota_exceeded	Os créditos de IA da organização acabaram ou o limite mensal da chave foi atingido.
O mesmo	429 rate_limited	Limite de taxa da chave. Todos os visitantes da página compartilham essa chave.
O mesmo	429 visitor_limit_reached	Somente chat sem chave: o visitante atingiu o limite por minuto ou por dia.

Erros contém o catálogo completo, e Cotas e limites de taxa explica os limites.

Páginas relacionadas

• Recursos e limites
• Mapas compatíveis
• Temas e layout
• kaleidr.js e O elemento kaleidr-map