チャットウィジェットガイド

01チャット ID

チャットボットはひとつの ID で識別されます。チャットページの「ホーム」タブにある「サイト用コード」のスニペット内、コピーボタンの横で確認できます。

識別するのはチャットボットだけです。アカウントも API キーも、サイト上のログインもありません。

公開して問題ありません。 ページの HTML に置かれ、誰でも読めます。できるのはチャットボットに質問することだけで、しかも許可したウェブサイト上だけです。

02ウェブサイトに設置する

どのページでも、閉じ body タグの直前に2行を追加します。

<script src="https://www.obbo.me/obbochat.js" async></script>
<div data-obbo-chat="YOUR_CHAT_ID"></div>

スクリプトはページごとに一度読み込まれ、隅にチャットバブルを表示します。サイトのテンプレートに入れれば全ページで有効になります。

まず自分のサイトを許可してください。チャットボットが回答するのは、Brand Center のチャットページの「名前とあいさつ」タブに記載したウェブサイトだけです（最初は Brand Center 自身のウェブサイト）。テスト用のコピーなど、チャットを表示するほかのウェブサイトもすべて追加してください。それ以外のサイトでは丁寧にお断りし、どのサイトが試みたかはチャットページに表示されます。

ページ読み込み後にマークアップを追加する場合 スクリプトが探すのはページ準備完了時の一度だけです。シングルページアプリ、タグマネージャー、同意バナーなどで後からチャットを挿入する場合は、その後に ObboChat.mount() を呼んでください。

03見た目

チャットボットの「外観」設定で見た目を決めてコードをコピーすると、これらの属性とスタイル値が自動で書き込まれます。必須なのはチャット ID だけで、ほかは手で編集することもできます。

<script src="https://www.obbo.me/obbochat.js" async></script>
<div data-obbo-chat="YOUR_CHAT_ID"
     data-obbo-title="Acme Help"
     data-obbo-position="left"
     data-obbo-launcher="Ask us a question"
     style="--obbo-accent: #0f766e; --obbo-accent-text: #ecfdf5; --obbo-bottom: 96px"></div>

見た目を変えたら、コードをもう一度コピーしてください。 見た目はコードに含まれているため、置き換えるまでサイトは以前の見た目のままです。

色

「色」の表では 6 つの色を設定します。ブランド、チャットボットの回答、チャットウィンドウのそれぞれについて、背景と文字の色です。ブランドは、チャットボタン、送信ボタン、おすすめの質問、訪問者のメッセージなど、訪問者がタップしたり送ったりするものすべてです。チャットウィンドウはタイトル、入力欄、リンク、注記で、線は文字色を薄くしたものです。枠をタップすると色の選択画面が開きます。「ウェブサイトに合わせる」はブランドカラーを設定し、ロゴの色など、ホームページで見つかった色をどの選択画面でも一番上に表示します。

「開始」でライトかダークを選ぶと、「自動」の色がすべて決まります。「自動」の文字は、背景の上で読みやすい白か黒になります。文字の枠には読みやすさが表示され、読みにくい色を選ぶと選択画面で「自動」に戻せます。

カスタムスタイル

ウィジェットの色・大きさ・距離は、それぞれ専用のスタイル値を読み込みます。チャットの div やサイト独自のスタイルシートで設定すると、コード内の値より優先されます。

[data-obbo-chat] {
  --obbo-accent: #0f766e;
  --obbo-assistant-text: #1f2937;
  --obbo-font: "Inter", sans-serif;
  --obbo-radius: 0;
  --obbo-bottom: 96px;
}

変わらないもの

パネル自身の言葉（あいさつ、送信ボタン、評価の依頼）は現在は英語で、レイアウトはこちらで決めています。マークアップをすべて自分で作りたい場合は、下のヘッドレスエンジンで独自の画面を作ってください。チャットボットは同じまま、HTML と CSS はあなたのものです。

回答の言語はひとつです。 チャットボットは、訪問者がどの言語で書いても、あなたのBrand Centerの言語で回答します。翻訳ではなく、会社自身の言葉で話すためです。

04独自のインターフェースを作る

バブルは省略できます。同じスクリプトがヘッドレスエンジンを公開しており、質問の送信、会話状態の購読、サイト独自の表示が可能です。

<script src="https://www.obbo.me/obbochat.js" async></script>
<script>
  addEventListener('load', function () {
    var chat = ObboChat.createChat({ widgetId: 'YOUR_CHAT_ID' });
    chat.subscribe(function (state) {
      // state.turns is the conversation; state.busy while answering.
    });
    chat.ask('What do you sell?');
  });
</script>

チャットボットごとにエンジンは1つです。バブルが行うこと（これまでの会話、見積もり用の写真、ログイン中の訪問者）はすべて購読した state に届くので、独自パネルでも失われるものはありません。

05費用見積もり

設定した質問と価格にもとづいて、チャットボットは会話の中で金額を提示できます。

チャットボットに費用見積もり機能がある場合、費用を尋ねた訪問者は、作業を数語で説明するか写真を追加するよう案内されます。写真はあなた自身の見積もり質問に沿って読み取られ（規模の区分、数量、計測値のおおよその範囲）、分かった内容は訪問者に表示され、確定する前に確認または修正できます。写真だけで価格が決まることはなく、数値は常に訪問者が確定し、訪問者の言葉が写真より優先されます。

訪問者が受け取るもの

通貨に合わせた項目別の価格帯で、作業の各部分が1行ずつ表示されます（ご希望なら、合計額とその根拠だけの表示も可能です）。各見積もりの下には御社の文が表示されます。これはあくまで概算で、正式な見積書ではありません。計算は御社の価格に基づき、価格が設定されていない部分は「別途見積もり」として表示されます。

設定すること

チャットページの料金の見積もりで行う5つの短いステップです。コードは一切不要です：

1. サイトをスキャン：チャットボットが既に把握しているページから料金・追加料金・条件を読み取り、金額を左右する質問を提案します。
2. 価格表：すべての価格を1枚のシートで管理します。セルを直接変更するか、ダウンロードしてExcelやGoogle Sheetsで編集し、再度アップロードできます。自動で算出された価格は、確認するまで「見積もり」と表示されます。
3. あなたの見積もり：訪問者に表示されるとおりの見積もり例です。どの行でも変更・削除・追加でき、訪問者に各項目を表示するか、合計額とその根拠だけを表示するかを選べます。
4. 質問：訪問者への質問を、設定した順に尋ねます。形式は1つ選択、複数選択、数値、日付、はい／いいえ、文章、写真から選べます。各質問には、回答が金額にどう影響するかが表示されます。
5. 料金と制限：追加料金と上限、各見積もりの下に表示する文、ご自身で見積もりたい案件の規模、そして見積もり機能をオンにするスイッチです。

金額はあなたのものです。 自動で算出された価格はすべて価格表で「見積もり」と表示され、お客様との会話の各見積もりには、御社の価格ではなく一般的な相場に基づく割合が示されます。納得できない価格帯が隠れることはありません。

見積もりの行き先

すべての見積もりはお客様との会話に、作成の元になった回答とともに表示されます。各回答には、訪問者の文章・写真・検索のどれから読み取ったかが示され、連絡先を残した場合はその情報も表示されます。完成した見積もりをメールで受け取ることもできます。

写真は90日間保存され、そこから1枚ずつ削除できます。どの質問でも尋ねていない内容が写真に写っていた場合は、各見積もりにその点も記録されます。

作るものはありません。 バブルもヘッドレスエンジンも見積もりに対応しており、独自画面では会話の state に各見積もりが届きます。ここで作るものはありません。

サイトに「見積もりを依頼」リンクを置く

チャットを設置したページなら、どのボタンやリンクからでもチャットを見積もりから開けます。好きな場所に貼り付けて、サイトの他の部分と同じスタイルを付けてください。チャットページの「コードを取得」にコピー用のものがあります。

<a href="#get-estimate" data-obbo-estimate>Get an estimate</a>

このリンクは他の場所からも使えます。別のページ、メール、広告、SNS の投稿などです。チャットを設置したページのアドレスの末尾に #get-estimate を付けると、そのページを開いたときにチャットが見積もりから始まります。

独自のボタン。 任意の要素に data-obbo-estimate を付けるか、独自のコードから ObboChat.startEstimate() を呼び出してください。見積もりの途中の訪問者はやり直さずにその続きに戻り、見積もり機能が公開されていないチャットボットは開くだけです。

06ログイン中の訪問者をチャットに伝える

訪問者が誰であるかはあなたのサーバーが保証し、チャットボットはその人自身の情報をふまえて回答します。

訪問者があなたのサイトにログインする場合、チャットはあなたのサイトが共有すると決めた情報をもとに、その訪問者自身のアカウントに関する質問（「注文はどこ？」など）に答えられます。Brand Center のチャットページで「ログイン中の訪問者」をオンにすると、訪問者キーを取得できます。

訪問者キーはサーバー側の秘密情報です。訪問者キーはサーバーだけに置いてください。ウェブページ、アプリ、コードリポジトリには絶対に入れないでください。漏れた場合はチャットページでキーを交換し、古いキーをすぐに停止してください。

全体の流れ

トークンの中身

訪問者キーをシークレットとして、HS256 の JWT として署名します。どの JWT ライブラリでも可能です。Node の例:

// Your server (Node + Express). npm install jsonwebtoken
import jwt from 'jsonwebtoken';

app.post('/chat-token', (req, res) => {
  res.set('Cache-Control', 'no-store');
  const user = req.user; // your own sign-in
  if (!user) return res.json({ token: null });
  const token = jwt.sign(
    {
      sub: String(user.id),
      name: user.firstName,
      account: { orders: recentOrdersFor(user) }, // whatever you choose to share
    },
    OBBO_VISITOR_KEY, // from your server's secret settings
    { algorithm: 'HS256', expiresIn: '10m' },
  );
  res.json({ token });
});

Python の例:

# Your server (Python + Flask). pip install PyJWT
import time
import jwt

@app.post("/chat-token")
def chat_token():
    user = current_user()  # your own sign-in
    if user is None:
        return {"token": None}
    now = int(time.time())
    claims = {
        "sub": str(user.id),
        "name": user.first_name,
        "account": {"orders": recent_orders_for(user)},  # whatever you choose to share
        "iat": now,
        "exp": now + 600,
    }
    return {"token": jwt.encode(claims, OBBO_VISITOR_KEY, algorithm="HS256")}

ページ側

サーバーからトークンを取得する関数をチャットに渡します。チャットがこの関数を呼ぶのは、質問が送られ、有効なトークンを持っていないときだけです。ページを読み込んだだけでは呼びません。

<script>
  addEventListener('load', function () {
    ObboChat.identify(async function () {
      const res = await fetch('/chat-token', { method: 'POST' });
      return (await res.json()).token;
    });
  });
  // When the visitor signs out: ObboChat.identify(null);
</script>

サイトが Cookie で訪問者をログインさせている場合は、属性 1 つで同じことができます。チャットはあなたのサイト上のそのアドレスに POST を送ります。そのルートは POST のみを受け付け、あなた自身のログインを確認し、CORS ヘッダーを送らず、誰もログインしていないときは null のトークンを返すようにしてください。

<script src="https://www.obbo.me/obbochat.js" async></script>
<div data-obbo-chat="YOUR_CHAT_ID" data-obbo-identity-url="/chat-token"></div>

訪問者がログアウトしたら ObboChat.identify(null) を呼んでください。チャットはその会話をすぐに消去するので、同じコンピューターを使う次の人は最初から始められます。

動作の確認

チャットの各返信は、トークンがどうなったかをページに伝えます。visitor.status は signed_in、anonymous、refused のいずれかで、拒否されたトークンには理由が付きます。Brand Center のチャットページでも、最後に受け付けたトークンと拒否したトークンを確認できます。

公開前に試せます。 チャットページの「お試し」タブで「ログイン中のお客様」を選び、名前と、サイトが送るはずのアカウント情報を入力すると、あなたのキーで署名した本物のトークンでテストチャットが質問します。検証も実際の訪問者とまったく同じです。

保存するもの。アカウント情報は各回答の作成のために AI プロバイダーへ送られます。会話やログには保存されませんが、回答に含まれることがあります。

07アカウントに関する質問に答える

「注文はどこですか？」に、自社システムから答えます。

お客様のサーバー上の 1 つのエンドポイントに問い合わせることで、訪問者自身のアカウントに関する質問（注文の状況、支払いが完了したかなど）にチャットが答えられます。当社がお客様のシステムに接続することはなく、鍵も保持しません。1 つの質問に必要な内容を記述して送るだけで、何を返すかはお客様が決めます。

1. ログイン中の訪問者を有効にします（第6節）。チャットボットが問い合わせられるのは、あなたのサイトが名前を示した相手だけです。
2. サーバーにエンドポイントを1つ作ります。GET はカタログを返し、POST はそこから作られた1件のリクエストに答えます。
3. チャットページの「名前とあいさつ」タブで「開発者向け」を開き、「アカウントに関する質問」で、そのアドレスを「データエンドポイント」に貼り、「エンドポイントに接続」を押します。回答できる内容がすぐに読み取られます。
4. 「オンにする」を押します。以後そのパネルに、問い合わせ回数、エンドポイントの所要時間、直近の問題がわかりやすい言葉で表示されます。

すべての回答をトークンの範囲に限定してください。すべての応答を、お客様自身の鍵で検証した訪問者トークンの sub に限定し、リクエストの他の部分が示す識別子は無視してください。これにより、ある訪問者に別の訪問者のデータが表示されることが原理的に起こりません。

データを記述する

エンドポイントへの GET はカタログを返します。返せるデータの種類と各項目のフィールドです。だからこそ、訪問者がしそうな質問を列挙する必要はありません。質問された時点で、チャットがカタログと照合します。

// GET https://your-site.com/obbo-chat/data
// Describe the data you have. You never list the questions your visitors
// might ask — the chat matches a question to one of these itself.
{
  "version": 1,
  "resources": [{
    "name": "orders",
    "title": "Orders",
    "description": "Orders on this customer's account, newest first.",
    "scope": "visitor",
    "fields": [
      {"name": "status", "type": "string", "description": "Where it stands.",
       "values": ["paid", "shipped", "delivered"]},
      {"name": "ship_date", "type": "date", "description": "When it shipped."},
      {"name": "tracking", "type": "string", "description": "Carrier tracking link."}
    ],
    "filters": [{"field": "status", "ops": ["eq"]}],
    "default_request": {"fields": ["status", "ship_date", "tracking"], "limit": 10},
    "max_limit": 25
  }]
}

1 件のリクエストに答える

POST では、あなたのカタログから作られた構造化リクエストと、あなたのサーバーが署名した訪問者トークンが届きます。中身はすべてカタログ由来で、カタログに記載のないリクエストが送られることはありません。

// POST https://your-site.com/obbo-chat/data
// "Where is my order?" becomes this. Operators are only:
// eq, neq, gte, lte, contains, in. There is no SQL and no free text.
{
  "version": 1,
  "visitor_token": "<the token YOUR server signed for this visitor>",
  "request": {
    "resource": "orders",
    "filters": [{"field": "status", "op": "eq", "value": "shipped"}],
    "fields": ["status", "ship_date", "tracking"],
    "limit": 10
  },
  "request_id": "chat_9f2c41b8"
}

その部分だけを返してください。応答は 64 KB 未満に収めてください。

// Answer with that slice, and nothing else.
{
  "version": 1,
  "resource": "orders",
  "items": [
    {"status": "shipped", "ship_date": "2026-09-14",
     "tracking": "https://carrier.example/track/4471"}
  ],
  "item_count": 1,
  "truncated": false
}

リクエストの検証

確認は2つ、この順番で。リクエストが訪問者キーで署名されているか、そして誰についてかです。どちらも訪問者トークンの署名に使っているキーと同じものを使うので、新たに入れるものはありません。GET と POST の両方が署名され、GET は空のボディに対する署名です。

X-Chat-Data-Signature: t=1760000000,v1=4b1f…9c   // hex, 64 chars
X-Chat-Key-Version: 3

signature = HMAC_SHA256(
  your_visitor_key,
  "<t>.<METHOD> <path and query>." + <raw request body>
).hex()

// GET  "1760000000.GET /obbo-chat/data."            + ""
// POST "1760000000.POST /obbo-chat/data."           + the bytes that arrived

const crypto = require('crypto');
const KEY = process.env.OBBO_VISITOR_KEY;   // the key from your chat page

// 1. Is this really from the chat service? The signature covers the method,
//    the path as sent, and the RAW body — so check before you parse.
function fromObbo(req, rawBody) {
  const fields = Object.fromEntries(
    (req.get('X-Chat-Data-Signature') || '').split(',').map(p => p.trim().split('='))
  );
  const t = Number(fields.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const mine = crypto.createHmac('sha256', KEY)
    .update(`${t}.${req.method} ${req.originalUrl}.`)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(mine), b = Buffer.from(fields.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// 2. Who is it about? From the token YOU signed — never from the body.
function visitorId(token) {
  const [head, payload, sig] = String(token || '').split('.');
  if (!head || !payload || !sig) return null;
  const mine = crypto.createHmac('sha256', KEY)
    .update(`${head}.${payload}`).digest('base64url');
  if (mine !== sig) return null;
  const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
  if (!claims.exp || Date.now() / 1000 > claims.exp) return null;
  return claims.sub;
}

// Your catalog. Signed too, over an empty body.
app.get('/obbo-chat/data', (req, res) => {
  if (!fromObbo(req, '')) return res.sendStatus(403);
  res.set('Cache-Control', 'no-store').json(CATALOG);
});

// One request. express.text keeps the raw bytes the signature covers;
// express.json would re-encode them and the check would fail.
app.post('/obbo-chat/data', express.text({ type: '*/*' }), async (req, res) => {
  if (!fromObbo(req, req.body)) return res.sendStatus(403);
  const body = JSON.parse(req.body);
  const customer = visitorId(body.visitor_token);
  if (!customer) return res.sendStatus(403);

  const asked = body.request || {};
  if (asked.resource !== 'orders') return res.sendStatus(422);   // not mine to answer

  // Scope EVERY query by `customer`. Ignore any id in the request body.
  const rows = await db.orders.findAll({
    where: { customer_id: customer, ...where(asked.filters) },
    limit: Math.min(asked.limit || 10, 25),
  });

  // Return the fields that were asked for, and never a field you did not
  // declare: everything you send is read out to the visitor.
  const items = rows.map(row => pick(row, asked.fields));
  res.set('Cache-Control', 'no-store')
     .json({ version: 1, resource: 'orders', items, item_count: items.length });
});

返すステータス

あなたが返すステータスが、そのままチャットページの表示になります。次のとおり使ってください。

5回連続で失敗すると問い合わせを止めます。 問い合わせは5分間停止し、チャットページに直近の理由とともに表示されます。再開は自動です。成功した問い合わせでカウントは0に戻りますが、「回答できる内容を読み取る」はエンドポイントの確認だけです。その間もチャットボットは他の質問に答え続けます。

遅いことは、無いことと同じです。送信したリクエストは 2.5 秒以内に応答がなければ、チャットはそれなしで回答します。エンドポイントが遅くても訪問者の質問が失敗することはありません。

08上限と所要時間

この仕様で定めた上限をまとめました。

09Content Security Policy

サイトで CSP を設定している場合は、この2つを許可してください。他は不要です。フレーム、フォント、当社の画像はありません。

コード内のスタイル値はウィジェットのスクリプトが適用するため、インラインスタイルを禁止するポリシーでも見た目は保たれます。ブラウザが style 属性について警告を表示することがありますが、問題ありません。

誰が識別されるか。ゲストが特定されることはありません。ブラウザ内のランダムなセッションキーが、1 人の訪問者の質問をダッシュボード上の 1 つの会話にまとめるだけです。ログイン中の訪問者は、あなたのサイトが送った ID と名前だけで識別されます。

10うまくいかないとき

11ご質問は？

ページのアドレス、チャット ID、実際にした質問をお知らせください。こちらでも同じものを確認します。お送りいただいた内容はすべて読んでいます： hello@obbo.me

Obbo のチャットボットについて