ウェブウィジェット

コード内の window.SingChat などはウィジェットと API の技術的な名前です。記載どおりにそのまま使ってください。

Web ウィジェットは、cs.askais.com から配信される 1 つのスクリプト widget.js です。ページにチャットの起動ボタンを追加し、チャットウィンドウを Shadow DOM の中に描画するため、サイトのスタイルとウィジェットのスタイルが干渉しません。

サイトに追加する

チャットを表示するすべてのページで、</body> の直前にこのコードを貼り付けます。App ID は 設定 → 受信トレイにあります。

<script src="https://cs.askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://cs.askais.com"
  async></script>

自分のサイトでは data-base-url が必須です。これがないと、ウィジェットは cs.askais.com ではなく、あなたのドメイン上でサーバーを探してしまいます。

⚠️ widget.js は cs.askais.com から読み込む

widget.js をダウンロードしたり、自分のコードにバンドルしたりしないでください。cs.askais.com から読み込めば、常に最新版が動きます。コピーは古いまま固定され、修正や新機能がいっさい反映されません。

スクリプトの属性

設定はすべて、script タグの data- 属性で行います：

• data-app-id — 必須。受信トレイの App ID。
• data-base-url — 自分のサイトでは必須。常に https://cs.askais.com。
• data-locale — 任意。ウィジェットの言語を固定します（例：ja、zh-Hant）。省略すると、訪問者のデバイスの言語に従い、次にページの lang に従います。
• data-external-id — ログイン中のユーザーを表す、あなたのシステム上の ID。
• data-email — ユーザーのメールアドレス。チームに表示されます。
• data-name — ユーザーの名前。チームに表示されます。
• data-avatar-url — ユーザーのプロフィール画像へのリンク。
• data-hmac — 本人確認の署名。下記を参照してください。
• data-attrs — 追加情報を JSON で指定します（例：{"plan":"Pro"}）。訪問者のプロフィールでチームに表示されます。無効な JSON は無視されます。

data-embed、data-platform、data-app-version、data-device-model は、アプリ内チャットのページが設定します。 アプリ内チャット（WebView）を参照してください。

ログイン中の訪問者

ログイン中のユーザーについては、その情報を script タグに追加します。チームは誰と話しているかがわかり、ユーザーがほかのデバイスに移ってもチャットが引き継がれます：

<script src="https://cs.askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://cs.askais.com"
  data-external-id="user_123"
  data-email="[email protected]"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

data-external-id がない場合、ウィジェットはブラウザごとに匿名 ID を割り当て、ブラウザのローカルストレージに保存します。そのため、同じブラウザならページを再読み込みしてもチャット履歴が残ります。受信トレイにチャット前フォームがある場合、匿名の訪問者はチャットを始める前にフォームに入力します。

本人確認（HMAC）

• hmac は、受信トレイのシークレットキーを鍵とした externalId の HMAC-SHA256 を、小文字の 16 進数で表したものです。
• サーバー上で計算してください。シークレットキーをページやアプリに含めてはいけません。
• シークレットキーは、受信トレイを作成したときに一度表示され、設定 → 受信トレイでローテーションしたとき（その受信トレイの ⋮ メニュー → シークレットキーをローテーション）にもう一度表示されます。sk_ プレフィックスを含むキー全体を使ってください。ローテーションすると、古い署名はすべて無効になります。
• data-external-id は必ず data-hmac と一緒に送り、署名するのはその値そのものにしてください。ウィジェットは必ず外部 ID を送る（渡さなければ匿名 ID を自動生成する）ため、メールアドレスだけに対する署名では誰も本人確認されません。
• 署名が間違っていても、なくても、チャットが止まることはありません。訪問者は会話を続けられますが、「未確認」として扱われます。未確認の情報はページが渡したとおりに使われるため、ページを書き換えられる人なら誰でも別人になりすませます。これを防ぐには「本人確認を必須にする」をオンにします。未確認の訪問者は匿名の訪問者として扱われ、以前の会話は見えなくなります。

Node.js の例：

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

JavaScript からウィジェットを起動する

ページがユーザーを特定できたタイミングなど、ウィジェットを自分で起動したい場合は、data-app-id なしでスクリプトを読み込み、読み込み後に window.SingChat.start() を呼び出します：

<script src="https://cs.askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://cs.askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "[email protected]",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

スクリプトが提供するメソッドは start() だけです。ウィジェットを開く、閉じる、イベントを受け取るためのメソッドはありません。訪問者は起動ボタンからウィジェットを開きます。

見た目と動作

• 設定 → 受信トレイで受信トレイを展開：メインカラーと文字色、位置（右下または左下）、バブルのサイズ、明るい背景または暗い背景、ウィンドウのタイトルとサブタイトルを、ライブプレビューを見ながら設定できます。
• チャット前フォーム（同じ場所）：チャットを始める前に、匿名の訪問者にメールアドレス、名前、電話番号、会社名を尋ねます。
• 許可するオリジン（同じ場所）：この受信トレイのウィジェットを読み込める Web サイト。リストが空の場合は、どのサイトでも読み込めます。
• ウィジェットのブランド表示（同じ場所）：チャット下部の「Powered by」の行。これを非表示にしたり、自社名を表示したりできるかは、プランによって異なります。
• AI のウェルカムメッセージは AI エージェント、クリックできる FAQ バブルは 設定 → よくある質問、記事は Help Center で設定します。

セキュリティ

• App ID は公開情報なので、HTML に記載しても安全です。
• 受信トレイのシークレットキーは、サーバーだけに置いてください。
• ページがユーザーを特定できるときは、必ず本人確認（HMAC）を使ってください。
• 「許可するオリジン」を自社のドメインだけに限定して、ほかのサイトでウィジェットを読み込めないようにしてください。