メインコンテンツへスキップ

Web SDK とは

Web SDK はウェブサイトに埋め込む小さなコードです。訪問者が「今すぐ話す」ボタンをクリックすると、ブラウザ内でマイクを使って OneInbox エージェントとのライブ音声会話が始まります。 ライブチャットウィジェットの音声版と考えてください。 SDK が処理するもの:
  • ブラウザへのマイク許可のリクエスト
  • リアルタイムの音声ストリーミング(双方向)
  • 会話中のライブトランスクリプト表示
  • ミュート、ミュート解除、ハングアップ
チームがセットアップするもの:
  • OneInbox のエージェント(応答する AI)
  • 通話を開始するサイト上のボタンまたはウィジェット

クイックスタート — サイトへの最も簡単な追加方法

これが最速のパスです:公開可能なキー + Web SDK、バックエンド不要。
1

エージェントを作成する

通話に応答するエージェントを構築します — まだ作成していない場合は クイックスタート を参照してください。その idagt_…)を保存します。
2

公開可能なキーを作成する

OneInbox ダッシュボードSettings → Publishable KeysCreate key へ。このキーに許可するオリジンを入力します — 1 行に 1 つ:
入力内容使うタイミング
https://yoursite.comキーを特定のドメインに制限 — 他のオリジンからのリクエストは 403 ORIGIN_NOT_ALLOWED で拒否される
https://yoursite.com + https://staging.yoursite.com複数の特定ドメイン(本番 + ステージングなど)
* または空白すべてのオリジンを許可 — 開発中やドメインロックが不要な内部ツールに便利
キーをコピーします — oi_pk_live_… で始まります。
* を使用すると、どのウェブサイトでもあなたの公開可能なキーを使ってエージェントへの通話を開始できます。ローカルテストには問題ありませんが、本番稼働前に実際のドメインに制限してください。
3

Web SDK をインストールする

npm install @oneinbox/web-sdk
4

エージェントに接続する

公開可能なキーで SDK を初期化し、start() でエージェントの id を指定します:
import { OneInbox } from "@oneinbox/web-sdk";

const oi = new OneInbox("oi_pk_live_…");
await oi.start("agt_…");
5

サイトにボタンを追加する

start() の呼び出しを任意のボタンに接続します — 例えば「今すぐ話す」。訪問者がクリックすると、マイクを使ってブラウザ内でその場で通話が始まります。
以上です — サーバー不要、別途「通話を作成する」ステップも不要です。完全なイベント/コントロール API(ミュート、トランスクリプト、ハングアップなど)は以下の Vanilla サンプルReact サンプル にあります。

プロダクトへの組み込み方

訪問者が「通話する」をクリックすると:
  1. ウェブサイトがサーバーに問い合わせます:「この訪問者の通話を開始して」
  2. サーバーが OneInbox API 経由で通話を作成し、短命のアクセストークンを受け取ります
  3. Web SDK がそのトークンを使って訪問者のブラウザをエージェントに接続します
  4. 会話が始まります — ライブ、双方向の音声
サーバーが秘密の API キーを保持します。ブラウザは通話終了時に期限切れになる一時トークンのみを受け取ります — 訪問者に機密情報が漏洩しません。

2 つのパッケージ

パッケージ使うタイミング
@oneinbox/web-sdkプレーンな JavaScript または任意のフレームワーク
@oneinbox/web-sdk-reactReact アプリ — すぐに使えるフックを提供
どちらも同じことをします。React パッケージは React に使いやすいパターンでコアをラップしたものです。

インストール

# Vanilla JavaScript / 任意のフレームワーク
npm install @oneinbox/web-sdk

# React
npm install @oneinbox/web-sdk-react @oneinbox/web-sdk react
各パッケージは自己完結型です — SDK は音声接続を処理するのに必要なすべてをバンドルしているため、他のコンパニオンパッケージのインストールは不要です。

Vanilla サンプル

import { OneInbox } from "@oneinbox/web-sdk";

const oi = new OneInbox("oi_pk_live_…");

// 通話中に起きることに反応する
oi.on("call-start",  ()  => showCallUI());
oi.on("call-end",    ()  => showIdleUI());
oi.on("transcript",  (t) => appendTranscript(t.role, t.text));  // ライブキャプション
oi.on("error",       (e) => showError(e.message));

// 通話を開始 — 訪問者の名前を渡してエージェントに挨拶させる
await oi.start("agt_…", { variables: { customer_name: "Sama" } });

// 通話中
oi.setMuted(true);   // 訪問者のマイクをミュート
oi.setMuted(false);  // ミュート解除

await oi.stop();     // ハングアップ

リッスンできるイベント

イベント意味
call-start通話が接続されました — アクティブな通話 UI を表示
call-end通話が終了しました — アイドル状態に戻る
transcript新しい発話行が聞こえました — キャプションまたはチャットログを更新
speech-start / speech-end誰かが話し始めたまたは止めた — 発話インジケーターをアニメーション
volume-level訪問者のマイクの現在の音量(0〜1)— マイクレベルバーを駆動
error何かが間違っています — エラーメッセージを表示

コントロール

メソッド動作
oi.start(agentId, { variables })通話を開始
oi.stop()通話を終了
oi.setMuted(true / false)訪問者のマイクをミュートまたはミュート解除
oi.isMuted()マイクが現在ミュートされている場合 true を返す
oi.status現在の状態:idleconnectingactive、または ending

React サンプル

import { OneInboxProvider, useOneInbox } from "@oneinbox/web-sdk-react";

// アプリの最上位で一度ラップする
function App() {
  return (
    <OneInboxProvider publishableKey="oi_pk_live_…">
      <CallWidget agentId="agt_…" />
    </OneInboxProvider>
  );
}

// プロバイダー内のどこでもフックを使用
function CallWidget({ agentId }) {
  const { start, stop, status, transcripts, isAgentSpeaking, isMuted, setMuted } = useOneInbox();
  const active = status === "active";

  return (
    <div>
      <button onClick={() => (active ? stop() : start(agentId))}>
        {active ? "Hang up" : "Talk to us"}
      </button>

      {active && (
        <button onClick={() => setMuted(!isMuted)}>
          {isMuted ? "Unmute" : "Mute"}
        </button>
      )}

      <p>{isAgentSpeaking ? "Agent is speaking…" : status}</p>

      {transcripts.map((t, i) => (
        <p key={i}><b>{t.role}:</b> {t.text}</p>
      ))}
    </div>
  );
}
useOneInbox() は通話 UI の構築に必要なすべてを提供します:
内容
status現在の通話状態(idleconnectingactiveending
transcriptsこれまでの会話のすべての行
isAgentSpeakingエージェントが話している間 true
isMuted訪問者のマイクがミュートされている場合 true
volumeリアルタイムのマイクレベル(0〜1)
error最後のエラー(もしあれば)
start / stop / setMutedコントロール