Chat リファレンス

product: 'chat' は Kaleidr Chat パネルをページにマウントします。パネルは iframe 内ではなく、ページのドキュメント内で動作します。渡された地図オブジェクト、指定された Kaleidr Viewer または Tile 要素に接続でき、地図を使用しないチャット専用パネルとしても動作します。

このページは機能のリファレンスです。最初のページを作成する場合は、Mapbox、MapLibre、Google Maps、Leaflet のガイドから始めてください。

要件

項目	内容
プラン	Free 以上
認証情報	公開可能キー（kld_pk_live_…）、または Control Tower がオンの公開済み Studio マップの ID
スコープ	ai。新しいキーにはデフォルトで付与されます。
許可されたオリジン	キーに許可オリジンが設定されている場合、ページのオリジンが含まれること。
ローダー	https://cdn.kaleidr.com/embed/v1/kaleidr.js
地図ライブラリ	任意。対応地図を参照してください。

最小構成のマウント

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) は、target として CSS セレクターまたは要素を受け取ります。ハンドルを同期的に返し、マウントに失敗しても例外をスローしません。Chat バンドルの読み込みとキーのセッション交換はバックグラウンドで行われ、どちらかが失敗するとコンソールにエラーが 1 件記録され、何も表示されません。唯一例外をスローするのはオプションオブジェクトがない場合で、Kaleidr.mount('#chat') は TypeError になります。

マウントオプション

すべてのオプションはマウント時に 1 回だけ読み込まれます。変更するには destroy() を呼び出してマウントし直してください。例外はテーマのみで、setTheme から更新できます。

オプション	型	デフォルト	必須	Chat での動作
product	'chat'	なし	はい	Chat 製品を選択します。
publishableKey	文字列	なし	shareId がなければ必須	kld_pk_… キー。SDK はパネルがリクエストを送る前にセッショントークンへ交換します。kld_sk_… サーバーキーはブラウザーで拒否され、コンソールにエラーが出ますがリクエストは送信しません。
shareId	文字列	なし	publishableKey がなければ必須	Kaleidr AI タイルで Control Tower がオンの公開済み Studio マップの ID。キーがない場合にのみ使用します。質問の費用はマップ所有者が負担します。公開マップ自身のビューアーにはすでにこのパネルが表示されます。公開地図で Kaleidr AI を使うを参照してください。
map	実行中の地図オブジェクト	なし	いいえ	アシスタントがピンを表示し、表示位置を動かす地図。オブジェクトからライブラリを認識します。チャット専用では省略します。
mapTarget	CSS セレクター	なし	いいえ	同じページ内の、パネルが操作する Viewer または Tile の <kaleidr-map> 要素。map があれば無視されます。
contained	真偽値	false	いいえ	true はパネルをマウント先の内側に配置します。対象には位置指定とサイズが必要です。false は document.body に追加し、ビューポート左上に固定ウィンドウとして表示します。
lang	文字列	ページの <html lang> が適切な言語タグならその値、それ以外は英語	いいえ	回答に使用する言語。en、ko、pt-BR などの BCP 47 タグで指定します。言語を参照してください。
title	文字列	会話から生成されるタイトル	いいえ	チャットウィンドウのヘッダーに表示するタイトル。タイトルとプレースホルダーを参照してください。
placeholder	文字列	Ask Kaleidr	いいえ	入力欄のプレースホルダー文字列。
theme	オブジェクトまたはその JSON 文字列	なし	いいえ	適用する CSS カスタムプロパティ。例：{ '--highlight-color': '#7c3aed' }。:root に設定され、ページ全体に影響します。
enabled	真偽値	なし	いいえ	マウント単位の有効化制御です。false はマウントを保留します。kaleidr.jsを参照してください。
apiBase	URL	https://api.kaleidr.com/inference-api	いいえ	セッション交換と質問の送信先 API。/inference-api パスが必須です。
base	URL	https://cdn.kaleidr.com	いいえ	Chat バンドルの取得元オリジン。オリジンだけを使用し、Kaleidr CDN（https://cdn.kaleidr.com）、kaleidr.js を取得したオリジン、またはページ自身のオリジンだけを許可します。ベースの上書きを参照してください。
apiKey	文字列	なし	いいえ	publishableKey の非推奨エイリアス。

Chat が使用しないオプション

Chat のマウントでは center、zoom、pitch、bearing、styleId、viewerBase、tileBase を受け取っても無視します。パネルは初期カメラを設定しないため、地図には指定済みの表示状態が保持されます。

存在しないオプション

地図ライブラリの強制指定、音声機能、コールバックを設定するオプションはありません。現在利用できない機能を参照してください。

言語

lang はパネルの回答言語を設定します。すべての質問とともに送信されます。

指定した値	使用される言語
lang: 'ko' または要素の lang="ko"	指定した言語タグをそのまま使用します。
lang なしで <html lang="fr"> があるページ	タグの形式が正しければページの言語を使用します。
lang なしで <html lang> がない、または形式が正しくないページ	英語。

• 許容値： en、ko、ja、pt-BR、zh-Hant などの BCP 47 言語タグ。35 文字を超えると API が拒否し、すべての質問が 422 lang_too_long で失敗します。
• ページの言語は形式が正しい場合だけ採用します： 2～3 文字のアルファベットに、ハイフン区切りの 1～8 文字の英数字サブタグを最大 3 個追加できます。展開されていないテンプレートのプレースホルダーは無視して英語を使用するため、不正な <html lang> でも Chat 自体は壊れません。
• 明示した lang が常に優先されます。
• lang はタイトルやプレースホルダーを翻訳しません。 デフォルトは英語です。title と placeholder は lang と同じ言語で設定してください。

タイトルとプレースホルダー

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 は、デフォルトの「Ask Kaleidr」という入力欄の文字列を置き換えます。
• title はチャットウィンドウのタイトルです。会話を開始するとウィンドウとヘッダーが表示され、以降のすべての会話で指定したタイトルがヘッダーに表示されます。title がない場合は、訪問者の最初の質問を短くした文字列を表示します。最小化されたチャットは title の有無にかかわらず、最初の質問から付けられたその会話自身のタイトルを表示します。
• 要素で使うタイトル属性は chat-title であり、title ではありません。HTML の title はブラウザーのホバーツールチップで、要素全体の上に表示されます。

使用する認証情報

指定した値	結果
publishableKey	キーをセッションに交換します。shareId もあれば無視します。
shareId のみ	公開マップを使ってセッションを取得します。
どちらもなし	パネルは表示されますが、質問はすべて失敗します。マウント時にはエラーを記録しません。

使用する地図

指定した値	結果
map	指定した地図オブジェクト。mapTarget もある場合は無視します。
mapTarget のみ	セレクターに一致する Kaleidr Viewer または Tile 要素。地図が必要になるたびにセレクターを解決するため、パネルの後から地図要素をマウントできます。
どちらもなし、または認識できないオブジェクトやセレクター	チャット専用となり、ピン、カメラ移動、ルートは表示されません。ログも出ません。

要素の属性

<kaleidr-map product="chat"> は宣言的な記述方法です。要素自体がマウント先になります。

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

属性	対応するオプション	注記
product="chat"	product	必須です。
publishable-key	publishableKey
share-id	shareId
map-target	mapTarget	CSS セレクター。
contained	contained	値のない属性は true。contained="false" は false。
lang	lang	BCP 47 タグ。言語を参照。
chat-title	title	ヘッダータイトル。HTML ツールチップ用の title ではありません。
placeholder	placeholder	入力欄のプレースホルダー。
theme	theme	JSON 文字列。マウント後に変更すると新しい値が適用されます。
flag	enabled	flag="false" はマウントを保留します。
api-base	apiBase
base	base
api-key	apiKey	publishable-key の非推奨エイリアス。

要素方式についての注意点：

• 実行中の地図オブジェクトは受け取れません。 map 属性はありません。独自の Mapbox、MapLibre、Google、Leaflet の地図と連携する場合は Kaleidr.mount を呼び出してください。要素方式は map-target で Kaleidr Viewer/Tile を操作するか、チャットだけを実行します。
• 属性は要素が接続される際に一度だけ読み込まれます。 あとから変更して適用されるのは theme だけです。share-id、publishable-key、map-target、contained、lang、chat-title、placeholder、flag をあとから変更しても効果はありません。要素を削除し、新しい要素を挿入してください。
• カメラ属性は効きません。 Chat マウント時の center、zoom、pitch、bearing は無視され、その後の変更では「非対応」の警告が出ます。
• 要素はデフォルトで display:block です。 contained では位置とサイズを指定してください。サンプルでは Safari 16.4 より前の環境に対応するためスタイルにも display:block を記述しています。古い Safari では明示しないとインライン要素のままです。テーマとレイアウトを参照してください。
• 要素を削除するとマウントも破棄されます。 再挿入すると新しいパネルとセッションになります。

すべての製品の属性一覧は kaleidr-map 要素にあります。

操作ハンドル

Kaleidr.mount はどの製品でも同じ構造のハンドルを返します。Chat では次のとおりです。

メンバー	Chat での対応	動作
product	'chat'	読み取り専用。
setTheme(theme)	対応	CSS カスタムプロパティのオブジェクトまたは JSON 文字列を受け取り、既存の設定に追加します。キーに -- がなければ補われます。JSON でない文字列や配列は警告とともに無視します。
destroy()	対応	パネル、場所カード、ピン、ルート線を削除し、セッションの更新を停止します。複数回呼び出しても安全です。
setCamera(camera)	非対応	警告を記録するだけです。地図の移動には地図ライブラリ自身の API を使ってください。
setStyle(style)	非対応	警告を記録し、何もしません。

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

パネルの読み込み前に呼び出した操作はキューに入り、準備できた時点で実行されます。読み込み前に destroy() を呼び出すとマウントがキャンセルされます。

ハンドルには ready Promise、on() メソッド、map メンバーがなく、メッセージの送信や会話の読み取りもできません。マウント時に有効化制御がオフなら、ハンドルは機能しない代替オブジェクトになります。すべてのメソッドは何もせず、どの制御がマウントを保留したかを示す警告が 1 件出ます。

対応していないメソッドは次をログに記録します：

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

4 製品すべての一覧は kaleidr-map 要素を参照してください。

マウント後のパネルの動作

• 「Ask Kaleidr」または設定した placeholder を含む入力バーを表示します。最初の質問でチャットウィンドウに展開されます。
• 質問とともにそれまでの会話、その ID、地図を接続している場合のズームレベル、言語タグを送信します。言語は指定した lang、ページの言語、en の順です。ページから送信される情報に全リクエストの一覧があります。
• 回答に登場する場所は結果カードと、接続先の地図上のピンになります。カメラは 1 か所に移動するか、複数の場所を収めます。
• 1 つのマウントで一度に表示できる会話は 1 件で、会話ごとに固有の ID があります。チャットウィンドウを閉じると会話とピンが消え、次の質問で新しい ID の会話が始まります。最小化では会話を保持します。その間に新しく質問すると別の会話が始まり、最小化したものを再表示すると以前の ID のまま続けられます。ページの再読み込みですべて最初からになります。永続保存はされません。

セッション交換

公開可能キーを質問の送信に直接使うことはありません。パネルが最初のリクエストを送る前に、SDK がキーを短期セッショントークンに交換し、パネルにはトークンだけを渡します。

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 }

動作	詳細
バインド	セッションは要求元のオリジンからの chat 製品にのみ有効です。
更新	SDK は現在のセッションが切れる 90 秒前に新しいセッションを要求します。またバックグラウンドのタブが再び表示されたとき、セッションが期限切れまたは期限間近なら再要求します。
更新に失敗	パネルがマウントされている間、30 秒ごとに再試行します。
初回交換に失敗	マウントが失敗し、エラーを 1 件記録して何も表示しません。自動再試行はありません。再度マウントしてください。
キーなしで shareId を使用	POST …/b2b/v1/sdk/share-sessions に本文 {"share_id":"…"} を送信します。セッションは 300 秒です。更新が 401、403、404 で拒否されると、ページを再読み込みするまで SDK は要求を停止します。

認証とスコープに、キー、セッション、スコープの詳細があります。

シングルページアプリでのライフサイクル

• 地図を含む画面が削除されるときに handle.destroy() を呼び出してください。ピンを消せるよう、地図より先にパネルを破棄します。
• 画面に戻ったら再マウントしてください。新しいセッション交換と会話が始まります。
• destroy() 後も、パネルのスタイルシートと :root に設定したテーマプロパティは残ります。destroy() が削除するもの・残すものを参照してください。
• 地図オブジェクトを入れ替える場合（地図を作り直す場合など）は、パネルを破棄して新しいオブジェクトでマウントし直します。パネルは渡された元のオブジェクトを保持しています。

フレームワーク統合では React、Next.js、Vue でのマウントとクリーンアップのパターンを紹介しています。

エラー

SDK はマウント失敗をコンソールエラー 1 件で報告し、サーバーが返す理由を繰り返しません。HTTP エラーの場合はブラウザーの Network タブでリクエストを開き、JSON 本文を確認してください。403 と 404 のコードは detail に、429 のコードは error にあり、説明文は detail にあります。

マウント時

コンソール	ネットワーク	原因
[kaleidr:chat] mount target not found: <selector>	リクエストなし	セレクターに一致する要素がありません。
[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …	リクエストなし	サーバーキーが渡されました。
[kaleidr:chat] [kaleidr] failed to load <url>	chat.js の要求失敗	バンドルがブロックされたか、CDN に接続できませんでした。
CORS エラーに続いて [kaleidr:chat] を含むエラー	POST …/sdk/sessions が CORS でブロック	キーが不明・失効・期限切れ、またはページのオリジンがキーの許可リストにありません。API は許可されたオリジンにのみ CORS ヘッダーを送信するため、ブラウザーはステータスと本文を隠します。
[kaleidr:chat] kaleidr session exchange failed (403)	403 insufficient_scope	キーに ai スコープがありません。
同じ表示	403 product_not_allowed	キーが chat を含まない製品に制限されています。
同じ表示	403 tier_capability_not_allowed	組織の現在のプランでは、この機能を利用できません。
[kaleidr:chat] kaleidr session exchange failed (429)	429 rate_limited	このキーによるセッション要求が 1 分間に 30 件を超えています。
[kaleidr:chat] kaleidr session exchange failed (404)	404 sessions_disabled	プラットフォームでセッション交換が停止されています。キーの問題ではありません。
[kaleidr:chat] kaleidr session exchange failed (503)	503 sessions_not_configured	プラットフォーム障害です。ページを再読み込みしてください。
キーなしで shareId を使ったマウント時の [kaleidr:chat] kaleidr session exchange failed (403) または (404)	403 chat_disabled、403 origin_not_allowed または 404 not_found	公開マップが Chat を拒否しました。公開地図で Kaleidr AI を使うを参照してください。
[kaleidr] embed is disabled — …（警告）	リクエストなし	有効化制御がオフです。メッセージで該当する制御を特定できます。
[kaleidr] theme string must be JSON …（警告）	該当なし	theme の値が JSON ではない文字列です。テーマを適用せずパネルがマウントされます。

パネル使用中

パネルは会話内に 1 行を追加して利用者にエラーを表示します。利用者のコードに通知はありません。

利用者に表示される内容	ステータス	原因
"Sorry — that didn't go through. Please try again."	401	セッションが無効です。キーが失効・期限切れ、許可オリジンから現在のオリジンが削除された、またはマウント時に認証情報がありませんでした。
同じ表示	5xx またはネットワーク障害	一時的な障害。
"You've reached your usage limit for now."、判明していればリセット時刻も表示	429 quota_exceeded	組織の AI クレジットが尽きたか、このキーの月間上限に達しています。
同じ表示	429 rate_limited	キーのリクエスト頻度制限です。同じページの訪問者は 1 つのキーを共有します。
同じ表示	429 visitor_limit_reached	キーを使わない Chat のみ：この訪問者の 1 分あたりまたは 1 日あたりの上限です。

エラーに全コードの一覧があり、クォータとレート制限で制限を説明しています。

関連ページ

• 機能と制限
• 対応地図
• テーマとレイアウト
• kaleidr.js と kaleidr-map 要素