Adicionar o Kaleidr Chat a um mapa MapLibre

Ao final deste guia, sua página terá um mapa MapLibre GL JS com um painel de chat integrado. O visitante faz uma pergunta, a resposta aparece progressivamente no painel, os lugares são marcados no mapa e a câmera se move para mostrá-los. Funciona em todos os planos, inclusive Free, com uma chave publicável. As perguntas consomem os créditos de IA da sua organização.

O painel funciona com qualquer estilo já usado pelo mapa. Ele não muda o estilo nem a fonte dos blocos.

Antes de começar

Uma chave publicável do Kaleidr (kld_pk_live_…) de kaleidr.com/api-keys, com escopo ai para Chat. Consulte Obter uma chave de API.
A origem da página deve ser permitida pela chave, caso haja restrições. Para testes locais, adicione http://localhost:8080.
Uma URL de estilo MapLibre. O exemplo usa o estilo público de demonstração do MapLibre; em produção, use o seu.
MapLibre GL JS carregado por script, expondo window.maplibregl. Se importar via npm, consulte Tornar a biblioteca global.
Um servidor HTTP, como npx serve ou python -m http.server 8080. Abrir direto do disco não funciona.
Se o site tiver uma Política de Segurança de Conteúdo, permita os hosts de Política de Segurança de Conteúdo.

Etapa 1: organizar o mapa e a camada de chat

Coloque o mapa e o destino de montagem do chat em um único contêiner posicionado. A camada de chat fica sobre o mapa, mas permite a passagem de eventos do ponteiro.

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

Resultado esperado: nada ainda, apenas um bloco vazio de 520 px de altura. Temas e layout explica cada declaração.

Etapa 2: carregar MapLibre GL JS e criar o mapa

Carregue a folha de estilos no cabeçalho e o script antes do seu código. As duas URLs devem apontar para a mesma versão.

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
<script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
<script>
  const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json', // your own style here
    center: [-0.12, 51.5],
    zoom: 11,
  });
</script>

Resultado esperado: um mapa que pode ser movido e ampliado. O estilo de demonstração mostra países simplificados com pouco detalhe urbano, mas os pinos e a câmera funcionam normalmente.

Etapa 3: carregar `kaleidr.js`

Adicione o carregador Kaleidr após o script MapLibre e antes do código que monta o painel.

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

Resultado esperado: nenhuma mudança visual. No console, Kaleidr.version retorna uma string de versão.

Etapa 4: montar o painel de chat

Passe sua chave e o objeto do mapa ativo.

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

Não é necessário aguardar o evento load do mapa. Kaleidr.mount retorna imediatamente; o painel aparece quando o bundle de chat termina de carregar e a chave é trocada por uma sessão.

Resultado esperado: uma barra de entrada «Ask Kaleidr» no canto superior esquerdo do mapa.

A página completa

Salve como index.html, substitua a chave e sirva a pasta por 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 MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-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://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,
      });

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

Como funciona

Visitante	Painel	Seu mapa MapLibre
Envia uma pergunta	Abre uma janela de chat; a resposta é exibida gradualmente como texto.	Ainda não há mudança.
Aguarda	Mostra um cartão para cada lugar citado na resposta.	Um marcador aparece assim que cada lugar é localizado. Para um lugar, a câmera voa até ele; para vários, enquadra todos com margem para não ficarem atrás do painel.
Clica em um marcador ou resultado	Abre um cartão de local com descrição, fotos e ferramenta de rotas.	Clicar em um resultado move a câmera para o lugar.
Solicita direções	Mostra distância e duração da rota.	Uma linha da rota é desenhada e enquadrada.
Faz outra pergunta	Continua a mesma conversa.	Novos marcadores são adicionados; os anteriores permanecem.
Fecha o chat	Volta à barra de entrada e encerra a conversa.	Marcadores e rota são removidos.

Detalhes específicos do MapLibre GL JS:

Os pinos são objetos Marker do MapLibre com um elemento HTML e não interferem nos marcadores que você já adicionou.
A rota é desenhada com fontes e camadas que o painel adiciona ao estilo e depois remove. Suas fontes e camadas não são alteradas.
A sessão é renovada automaticamente enquanto o painel estiver montado. Você não precisa gerenciar tokens.

Verificar se funcionou

Na página

A barra Ask Kaleidr aparece sobre o canto superior esquerdo do mapa.
Digite Show me three museums in London e pressione Enter. O texto aparece progressivamente, três marcadores são exibidos e o mapa os enquadra.

No console

Nenhum erro ou aviso contém [kaleidr.

Na guia Network

Requisição	Resultado esperado
`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, com corpo JSON como no exemplo seguinte
`POST https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream` (após uma pergunta)	200, `content-type: text/event-stream`

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

Se não funcionar

O SDK registra uma mensagem breve sem repetir o motivo do servidor. Se uma requisição falhar, abra-a em Network e leia a resposta JSON. Um 403 ou 404 traz o código em detail; um 429 o traz em error, com uma frase em detail.

Sintoma	Causa	Solução
Sem painel; erro CORS em `…/sdk/sessions` e erro `[kaleidr:chat]`	A chave é desconhecida, revogada ou a origem não é permitida. A API envia cabeçalhos CORS apenas a origens aceitas.	Confira a chave e adicione a origem exata, incluindo esquema e porta, em kaleidr.com/api-keys.
`[kaleidr:chat] kaleidr session exchange failed (403)`	Chave válida, mas sem autorização para Chat. `detail` pode ser `insufficient_scope` (sem `ai`), `product_not_allowed` (outros produtos) ou `tier_capability_not_allowed`.	Use uma chave com `ai` e acesso ao produto `chat`.
`[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	Uma chave de servidor foi fornecida; nenhuma requisição foi feita.	Use uma chave publicável (`kld_pk_live_…`). Revogue a chave de servidor se ela foi exposta em uma página pública.
`[kaleidr:chat] mount target not found: #chat`	O seletor não encontra o elemento alvo.	Execute `mount` quando o elemento existir ou passe o próprio elemento. `mount`
`[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	O bundle foi bloqueado, geralmente por uma política de conteúdo ou bloqueador de anúncios.	Permita `https://cdn.kaleidr.com` em `script-src`.
`Kaleidr is not defined`	Seu código rodou antes de `kaleidr.js` carregar, por exemplo devido a `async` ou `defer`.	Carregue `kaleidr.js` normalmente antes do código ou execute o código no evento `load` do script.
`[kaleidr] embed is disabled — …`	Uma condição de habilitação está impedindo as montagens.	A mensagem identifica o controle responsável. Consulte kaleidr.js.
O painel aparece no canto da janela, não sobre o mapa	Falta `contained` ou `#chat` não está posicionado.	Adicione `contained: true` e os estilos da etapa 1.
O painel responde, mas não aparecem pinos nem a câmera se move	O objeto passado em `map` não foi reconhecido.	Passe a instância `maplibregl.Map`. Veja Mapas compatíveis.
A câmera voa até um lugar, mas não há pinos nem enquadramento de vários	`window.maplibregl` não existe. Mover para um lugar só precisa do objeto de mapa; marcadores e enquadramento exigem o global.	Se MapLibre foi importado via npm, defina `window.maplibregl` antes de montar. Veja Importações npm.
O painel sempre mostra «Sorry — that didn't go through. Please try again.»	A sessão se tornou inválida porque a chave foi revogada ou as origens permitidas mudaram.	Verifique a chave e recarregue a página.
O painel mostra «You've reached your usage limit for now.»	HTTP 429: créditos de IA esgotados ou limite de taxa da chave atingido. Todos os visitantes compartilham o limite da mesma chave.	Consulte Cotas e limites de taxa.
O mapa não pode ser arrastado	A camada de chat está interceptando a interação.	Adicione `pointer-events:none` a `#chat`.

Mais sintomas estão em Resolução de problemas.

Limitações

Sua página não recebe callbacks nem eventos do painel; não pode reagir por código a perguntas, respostas ou cliques nos pinos.
O assistente não enxerga suas camadas, marcadores nem a área visível do mapa. Somente o nível de zoom acompanha cada pergunta.
Você não pode transmitir suas instruções ou dados próprios ao assistente por meio do painel.
O idioma das respostas, o título e o placeholder são opções de montagem (lang, title, placeholder): consulte Referência de Chat. Os demais rótulos permanecem em inglês.
handle.setCamera() não faz nada em uma montagem de Chat e registra um aviso. Mova a câmera pela API do MapLibre.
Em aplicativos de página única, chame handle.destroy() quando a visualização sair e monte novamente quando ela voltar.
O painel de chat não fornece um mapa base. Para exibir um mapa base Kaleidr, use Tile em seu próprio elemento; o chat pode controlá-lo por map-target.

A lista completa está em Recursos e limitações.

Próximos passos

Temas e layout: adapte o painel ao site.
Referência de Chat: todas as opções, o handle e os erros.
Checklist de produção: o que verificar antes de lançar.
Frameworks: montagem com React, Next.js e Vue.

Antes de começar​

Etapa 1: organizar o mapa e a camada de chat​

Etapa 2: carregar MapLibre GL JS e criar o mapa​

Etapa 3: carregar kaleidr.js​

Etapa 4: montar o painel de chat​

A página completa​

Como funciona​

Verificar se funcionou​

Se não funcionar​

Limitações​

Próximos passos​