自社システムへの組み込み

SotaAgents は自社が所有するページの中で、フローティングバブルまたはインラインパネルとして動作します。ユーザーは自社のシステムにサインインしたままで、SotaAgents のログイン画面を見ることはありません。ユーザーが誰であるかは自社のバックエンドが保証し、プラットフォームはユーザーの入力ではなくその署名を信頼します。

2 つの組み込み方式#

本ページは後者を扱います。前者はワークスペースを参照してください。

始める前に#

• Console → 組織 → API Keys で発行する API key と secret。secret は一度しか表示されません — API キーを参照。
• embed を使う全員が、あらかじめ組織の有効なメンバーである必要があります。just-in-time のアカウント作成は行いません。未知のユーザーは作成されずに拒否されます。先に招待するか、SSO でプロビジョニングしてください。
• 自社で管理するバックエンド。secret はサーバー側で署名に使うものであり、ブラウザーに渡してはいけません。

handshake の流れ#

バックエンドの責務#

3 つあり、最初の 2 つが統合で最も間違えやすい箇所です。

リクエストへの署名#

手順はどの言語でも同じです。5 行の canonical string を組み立て、API secret で HMAC-SHA256 し、v1=<小文字 hex> として送ります。5 行は method、path、Unix タイムスタンプ（秒）、nonce、リクエストボディの SHA-256 で、\n で連結し、末尾に改行は付けません。

POST
/api/embed/auth/tickets
1786800000
3f1c9a7e-5b02-4d6f-9a11-0c8e2d4b7f30
9b2a4c1d8e3f5a70b6c9d2e4f8a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f3a5

import { createHash, createHmac, randomUUID } from 'node:crypto';

const body = JSON.stringify({ externalUserId, email, name }); // serialize ONCE
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomUUID();
const bodyHash = createHash('sha256').update(body, 'utf8').digest('hex');

const canonical = ['POST', PATH, timestamp, nonce, bodyHash].join('\n');
const signature = 'v1=' + createHmac('sha256', apiSecret).update(canonical).digest('hex');

import hashlib, hmac, json, time, uuid

body = json.dumps({"externalUserId": external_user_id, "email": email})  # serialize ONCE
timestamp = str(int(time.time()))
nonce = str(uuid.uuid4())
body_hash = hashlib.sha256(body.encode("utf-8")).hexdigest()

canonical = "\n".join(["POST", PATH, timestamp, nonce, body_hash])
signature = "v1=" + hmac.new(
    api_secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256
).hexdigest()

String body = objectMapper.writeValueAsString(payload); // serialize ONCE
String timestamp = String.valueOf(Instant.now().getEpochSecond());
String nonce = UUID.randomUUID().toString();
String bodyHash = HexFormat.of().formatHex(
    MessageDigest.getInstance("SHA-256").digest(body.getBytes(StandardCharsets.UTF_8)));

String canonical = String.join("\n", "POST", PATH, timestamp, nonce, bodyHash);

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(apiSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String signature = "v1=" + HexFormat.of().formatHex(
    mac.doFinal(canonical.getBytes(StandardCharsets.UTF_8)));

var body = JsonSerializer.Serialize(payload); // serialize ONCE
var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
var nonce = Guid.NewGuid().ToString();
var bodyHash = Convert.ToHexString(
    SHA256.HashData(Encoding.UTF8.GetBytes(body))).ToLowerInvariant();

var canonical = string.Join("\n", "POST", Path, timestamp, nonce, bodyHash);

using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = "v1=" + Convert.ToHexString(
    hmac.ComputeHash(Encoding.UTF8.GetBytes(canonical))).ToLowerInvariant();

body, err := json.Marshal(payload) // serialize ONCE
timestamp := strconv.FormatInt(time.Now().Unix(), 10)
nonce := uuid.NewString()
sum := sha256.Sum256(body)
bodyHash := hex.EncodeToString(sum[:])

canonical := strings.Join([]string{"POST", path, timestamp, nonce, bodyHash}, "\n")

mac := hmac.New(sha256.New, []byte(apiSecret))
mac.Write([]byte(canonical))
signature := "v1=" + hex.EncodeToString(mac.Sum(nil))

$body = json_encode($payload); // serialize ONCE
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$bodyHash = hash('sha256', $body);

$canonical = implode("\n", ['POST', $path, $timestamp, $nonce, $bodyHash]);
$signature = 'v1=' . hash_hmac('sha256', $canonical, $apiSecret);

実際に送られるリクエスト#

どの言語で署名しても、SotaAgents が受け取るのはこの形です。timestamp と nonce のヘッダーは canonical string に入れたものと同じ値である必要があります。nonce は一度だけ受け付けられ、再送は 5 分間拒否されます。

POST https://app.sotaagents.ai/api/embed/auth/tickets
content-type: application/json
x-sota-key: sota_ek_...
x-sota-timestamp: 1786800000
x-sota-nonce: 3f1c9a7e-5b02-4d6f-9a11-0c8e2d4b7f30
x-sota-signature: v1=4d5e...

{"externalUserId":"e-1042","email":"an.tran@company.com"}

SotaAgents は 201 と共通エンベロープ { success: true, data: { ticket, expiresAt }, timestamp } を返します。エンベロープを外してください。内側の data をブラウザーに返します。SDK は最上位の ticket を読むため、エンベロープのままでは不正な ticket と見なされ、通信は 200 なのにパネルが永久に表示されない状態になります。エラー応答は包まれません。{ statusCode, code, message } がそのまま返るので、code は最上位から読んでください。ticket の有効期間は 60 秒で、交換は 1 回だけです。

レート制限。ticket の発行は API key ごとに毎分 60 リクエスト、送信元 IP ごとに毎分 120 リクエストまでです。iframe 内での ticket 交換は毎分 10 回までで、エンドユーザーの IP と ticket の両方を単位に数えます。超過すると Retry-After 付きの 429 が返ります。汎用の 4xx にまとめず、そのまま SDK に渡してください。SDK が backoff して再試行します。バックエンド全体が 1 つの送信元 IP を共有し、1 つのオフィス NAT の背後にいる全員が交換の枠を共有するため、サインインのピークをこの数値と突き合わせ、足りない場合は公開前にご相談ください。

フロントエンドの責務#

<script src="https://app.sotaagents.ai/embed/sdk.js"></script> を読み込んで初期化します。重要な点は 2 つ。ticket 取得の呼び出しに自社セッション cookie を付けること、そしてサインアウト時に先に SotaAgents セッションを失効させることです。

以下のサンプルの origin は例です。tenant ごとの embed origin は SotaAgents 担当から受け取ってください。production と staging では異なります。この origin、SDK スクリプトの URL、ticket API のベース URL は、コードではなく設定に置いてください。HTTPS でない embedUrl は SDK が拒否します。

const embed = window.SotaEmbedSDK.createSotaEmbed({
  embedUrl: 'https://app.sotaagents.ai/embed',
  mode: 'bubble',
  getTicket: async () => {
    const response = await fetch('/api/sota/embed-ticket', {
      method: 'POST',
      credentials: 'include',
    });
    if (!response.ok) {
      // Status rides along so the SDK can fast-fail a 401 or 409 instead of
      // retrying a permanent failure four times.
      throw Object.assign(new Error('ticket_failed'), { status: response.status });
    }
    return response.json(); // { ticket, expiresAt }
  },
});

// On sign-out: revoke the SotaAgents session BEFORE clearing your own.
const revoked = await embed.logout();
if (!revoked) console.warn('SotaAgents session may still be active');
await fetch('/api/logout', { method: 'POST', credentials: 'include' });

自社ブランドに合わせる#

ここにある項目はすべて任意で、既定値はいずれも SotaAgents 標準のままです。何も設定しなければ見た目は今と変わりません。設定すれば、チャットは当社ではなく貴社の名前をまといます。

createSotaEmbed({
  embedUrl: 'https://app.sotaagents.ai/embed',
  getTicket,

  // Inside the iframe
  language: 'vi',                  // 'en' | 'vi' | 'ja'
  branding: {
    logoUrl: 'https://intranet.acme.com/logo.svg',
    showUser: false,
    greeting: 'How can the Acme assistant help?',
    placeholder: 'Ask about policies, invoices, anything',
  },

  // The bubble chrome, drawn on your own page
  mode: 'bubble',
  title: 'Acme Assistant',
  primaryColor: '#0b5cff',
  position: 'bottom-left',
  width: 420,
  height: 640,
  openOnLoad: false,
});

2 つの設置形態。mode が取る値はちょうど 2 つです。既定は 'bubble' で、SDK が自社ページ上に独自のランチャーとパネルを描画し、container は無視されます。'inline' は指定した要素に iframe を直接置きます。ランチャーもパネルもなく、container が必須で、無い場合は生成時に例外を投げます。見積もりに関わる違いがもう 1 つあります。bubble は iframe を遅延生成し、最初のクリックまで作らないため、誰かがチャットを開くまで認証は走りません。inline は読み込み時に生成するため、ticket エンドポイントの不具合はすぐ表面化し、ページ表示ごとに ticket を 1 枚消費します。

チャット内部。 これらはサインイン後に届くのではなく iframe の URL に乗るため、ユーザーが最初に見るフレームからすでに貴社仕様です。SotaAgents のロゴが一瞬見えてから差し替わることはありません。

greeting と placeholder は 120 文字で切り詰められます。一文には十分で、入力欄を画面外へ押し出すには短い長さです。

bubble の外枠。 SDK が iframe の外側、貴社ページ上に描画するランチャーとパネルです。title を除き mode: 'inline' では無視され、サイズは渡した container が、周囲の見た目は貴社ページが決めます。

iframe 自体に関わるものがもう 2 つあります。allowMicrophone は既定でオフで、音声入力に必要です。sandbox は既定の allow-scripts allow-same-origin allow-forms allow-popups を置き換えます。ここは HTML の慣習とは逆で、sandbox: '' は最も厳しい設定ではなく、属性そのものを取り除きます。iframe の分離もろとも失われます。厳しくしたい場合は、より狭いトークンの並びを渡してください。空文字列は決して渡さないでください。理由がない限りどちらも触らないでください。

サードパーティ cookie#

embed が自社ポータルと別サイトで動く場合、そのセッション cookie はサードパーティ cookie になります。

フォールバックでも動作しますが、数分ごとに再認証が走ります。reverse proxy で自社サイトのサブドメイン（例: ai.example.com）から embed を配信すると cookie が first-party になり、どのブラウザーでもこの問題がなくなります。その際の注意は 2 点。proxy に Set-Cookie を書き換えさせないこと、そしてチャット応答は stream されるためバッファリングを無効にすることです。

公開前チェック#

• secret は secret manager にあり、source control にはない。
• 対象ユーザー全員が組織の有効なメンバーである。
• ticket エンドポイントは identity をセッションからのみ読む。
• セッションを終了する全経路で、自社サインアウトの前に logout() が実行される。
• Workspace の credit 配分が十分である（組み込み会話も通常の会話と同じく credit を消費します）。
• embed を frame できるオリジンを自社ドメインに限定するよう、サポートに依頼する。