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

Documentation Index

Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Web SDK とは

Web SDK（@oneinbox/web-sdk）は OneInbox の フロントエンドブラウザ音声ライブラリです。アクティブな Web 通話 セッションにユーザーのブラウザを接続します。 Web 通話は 作成しません。先にバックエンドで POST /v1/calls/web で Web 通話を作成 — Web 通話 ガイドを参照。

​
必要な値

値取得元
server_urlWeb 通話 レスポンス（例: wss://voice.oneinbox.ai）
participant_token同上 — このセッション用の短期トークン
バックエンドが Web 通話を作成し、これらの値をフロントに返します。Web SDK に OneInbox API キーは不要です。

​
アーキテクチャ

ユーザーが「AI と話す」をクリック
        │
        ▼
 自社フロントエンド
 └── POST /api/start-call  ──►  自社バックエンド
                                      │
                            POST /v1/calls/web   ← Web 通話（API）
                                      │
                                      ▼
                               server_url + participant_token
                                      │
        ◄─────────────────────────────┘
        │
        ▼
 Web SDK がブラウザで接続
        │
        ▼
 エージェントとのライブ会話

​
Web SDK が担うもの

  • server_url と participant_token での接続
  • ブラウザのマイクアクセスと音声ストリーミング
  • 通話状態（接続中、アクティブ、終了）
  • UI からの切断 / 通話終了
担わないもの:
  • エージェントや LLM モデルの作成
  • POST /v1/calls/web の呼び出し（バックエンドの役割）
  • API キーの保存または使用
1

1. バックエンド — Web 通話トークンの中継

サーバーが Web 通話 を作成し、フロントに必要な値のみ返します:
// server.js (Node.js / Express)
const express = require('express');
const app = express();
app.use(express.json());

app.post('/api/start-call', async (req, res) => {
  try {
    const response = await fetch('https://api.oneinbox.ai/v1/calls/web', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.ONEINBOX_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        agent_id: process.env.ONEINBOX_AGENT_ID,
        variables: {
          customer_name: req.body.customerName || 'Guest'
        }
      })
    });

    if (!response.ok) {
      throw new Error(`OneInbox API error: ${response.status}`);
    }

    const { id: call_id, server_url, participant_token } = await response.json();
    res.json({ call_id, server_url, participant_token });
  } catch (error) {
    console.error('Failed to start call:', error);
    res.status(500).json({ error: 'Failed to start call' });
  }
});

app.listen(3000);
2

2. フロントエンド — インストールと接続

npm install @oneinbox/web-sdk

import { useState, useRef } from 'react';
import { OneinboxCall } from '@oneinbox/web-sdk';

export default function VoiceWidget({ customerName }) {
  const [status, setStatus] = useState('idle');
  const callRef = useRef(null);

  async function startCall() {
    setStatus('connecting');
    try {
      const res = await fetch('/api/start-call', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ customerName })
      });
      const { server_url, participant_token } = await res.json();

      const call = new OneinboxCall({
        serverUrl: server_url,
        token: participant_token,
        onStateChange: (state) => setStatus(state),
        onEnded: () => {
          setStatus('ended');
          callRef.current = null;
        }
      });

      await call.connect();
      callRef.current = call;
      setStatus('active');
    } catch (error) {
      console.error('Call failed:', error);
      setStatus('idle');
    }
  }

  async function endCall() {
    await callRef.current?.disconnect();
    setStatus('ended');
  }

  if (status === 'idle') {
    return <button onClick={startCall}>Talk to AI</button>;
  }
  if (status === 'connecting') return <p>Connecting...</p>;
  if (status === 'active') {
    return (
      <div>
        <span>Connected</span>
        <button onClick={endCall}>End call</button>
      </div>
    );
  }
  return <p>Call ended.</p>;
}

​
他パスとの比較

パス内容場所
Web 通話バックエンド API セッションWeb 通話 ガイド
Web SDKそのセッション用ブラウザクライアントこのページ
電話通話テレフォニーキャリア経由 PSTN電話通話 ガイド

​
トラブルシューティング

問題対処
OneInbox から 401Web 通話作成時のバックエンド API キーを確認
Web SDK が接続できないバックエンドから新しい server_url と participant_token を取得
音声が出ないブラウザのマイク許可；本番は HTTPS
フロントに API キーWeb 通話はバックエンドでのみ作成

​
次のステップ