WebSocket | ElevenLabs Documentation

このドキュメントは、ElevenLabs WebSocket APIを直接統合するデベロッパー向けです。より簡単に利用するには、 ElevenLabsが提供する公式SDKの使用をご検討ください。

ElevenAgents WebSocket APIを使用すると、AIエージェントとのリアルタイムでインタラクティブな音声会話を実現できます。WebSocket接続を確立することで、オーディオ入力を送信し、オーディオ応答をリアルタイムで受信でき、自然な会話体験を作成できます。

エンドポイント：wss://api.elevenlabs.io/v1/convai/conversation?agent_id={agent_id}

認証

エージェントIDを使用する

パブリックエージェントでは、追加の認証なしでWebSocket URL内のagent_idを直接使用できます。

wss://api.elevenlabs.io/v1/convai/conversation?agent_id=<your-agent-id>

署名付きURLを使用する

プライベートエージェント、または認可が必要な会話では、サーバーから署名付きURLを取得します。サーバーはAPIキーを使用してElevenLabs APIと安全に通信します。

cURLを使用した例

リクエスト：

curl -X GET "https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=<your-agent-id>" \
     -H "xi-api-key: <your-api-key>"

レスポンス：

{
  "signed_url": "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=<your-agent-id>&token=<token>"
}

ElevenLabs APIキーをクライアント側に公開しないでください。

WebSocketイベント

クライアントからサーバーへのイベント

クライアントからサーバーへは、次のイベントを送信できます。

コンテキスト更新

会話の状態を更新するために、会話を中断しないコンテキスト情報を送信します。これにより、進行中の会話フローを妨げずに追加のコンテキストを提供できます。

{
  "type": "contextual_update",
  "text": "User clicked on pricing page"
}

ユースケース：

ユーザーのステータスや設定を更新する
環境コンテキストを提供する
背景情報を追加する
ユーザーインターフェースの操作を追跡する

主なポイント：

現在の会話フローを中断しない
更新は会話履歴内のツール呼び出しとして組み込まれる
自然な対話を損なわずにコンテキストを維持できる

コンテキスト更新は非同期で処理され、サーバーからの直接的な応答は必要ありません。

WebSocket APIリファレンス

詳細なメッセージ構造、パラメータ、例については、ElevenLabs Agents WebSocket APIリファレンスを参照してください。

Next.js実装例

この例では、ElevenLabs WebSocket APIを使用して、Next.jsでWebSocketベースの会話エージェントクライアントを実装する方法を示します。

この例ではマイク入力の処理にvoice-streamパッケージを使用していますが、オーディオのキャプチャとエンコードは独自に実装できます。ここでは、ElevenLabs APIとのWebSocket接続とイベント処理を示すことに焦点を当てています。

必要な依存関係をインストールする

まず、必要なパッケージをインストールします。

npm install voice-stream

voice-streamパッケージはマイクへのアクセスとオーディオストリーミングを処理し、ElevenLabs APIで必要なbase64形式にオーディオを自動的にエンコードします。

この例ではスタイリングにTailwind CSSを使用しています。Next.jsプロジェクトにTailwindを追加するには：

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

続いて、Next.js向けTailwind CSS公式セットアップガイドに従ってください。

または、className属性を独自のCSSスタイルに置き換えることもできます。

WebSocket型を作成する

WebSocketイベントの型を定義します。

app/types/websocket.ts

type BaseEvent = {
  type: string;
};
type UserTranscriptEvent = BaseEvent & {
  type: "user_transcript";
  user_transcription_event: {
    user_transcript: string;
  };
};
type AgentResponseEvent = BaseEvent & {
  type: "agent_response";
  agent_response_event: {
    agent_response: string;
  };
};
type AgentResponseCorrectionEvent = BaseEvent & {
  type: "agent_response_correction";
  agent_response_correction_event: {
    original_agent_response: string;
    corrected_agent_response: string;
  };
};
type AudioResponseEvent = BaseEvent & {
  type: "audio";
  audio_event: {
    audio_base_64: string;
    event_id: number;
    alignment: {
      chars: string[];
      char_durations_ms: number[];
      char_start_times_ms: number[];
    };
  };
};
type InterruptionEvent = BaseEvent & {
  type: "interruption";
  interruption_event: {
    reason: string;
  };
};
type PingEvent = BaseEvent & {
  type: "ping";
  ping_event: {
    event_id: number;
    ping_ms?: number;
  };
};
type AgentChatResponsePartEvent = BaseEvent & {
  type: "agent_chat_response_part";
  text_response_part: {
    type: "start" | "delta" | "stop";
    text: string;
    event_id: number;
    response_id: string;
  };
};
export type ElevenLabsWebSocketEvent =
  | UserTranscriptEvent
  | AgentResponseEvent
  | AgentResponseCorrectionEvent
  | AudioResponseEvent
  | InterruptionEvent
  | PingEvent
  | AgentChatResponsePartEvent;

WebSocketフックを作成する

WebSocket接続を管理するカスタムフックを作成します。

app/hooks/useAgentConversation.ts

'use client';
import { useCallback, useEffect, useRef, useState } from 'react';
import { useVoiceStream } from 'voice-stream';
import type { ElevenLabsWebSocketEvent } from '../types/websocket';
const sendMessage = (websocket: WebSocket, request: object) => {
  if (websocket.readyState !== WebSocket.OPEN) {
    return;
  }
  websocket.send(JSON.stringify(request));
};
export const useAgentConversation = () => {
  const websocketRef = useRef<WebSocket>(null);
  const [isConnected, setIsConnected] = useState<boolean>(false);
  const { startStreaming, stopStreaming } = useVoiceStream({
    onAudioChunked: (audioData) => {
      if (!websocketRef.current) return;
      sendMessage(websocketRef.current, {
        user_audio_chunk: audioData,
      });
    },
  });
  const startConversation = useCallback(async () => {
    if (isConnected) return;
    const websocket = new WebSocket("wss://api.elevenlabs.io/v1/convai/conversation");
    websocket.onopen = async () => {
      setIsConnected(true);
      sendMessage(websocket, {
        type: "conversation_initiation_client_data",
      });
      await startStreaming();
    };
    websocket.onmessage = async (event) => {
      const data = JSON.parse(event.data) as ElevenLabsWebSocketEvent;
      // Handle ping events to keep connection alive
      if (data.type === "ping") {
        setTimeout(() => {
          sendMessage(websocket, {
            type: "pong",
            event_id: data.ping_event.event_id,
          });
        }, data.ping_event.ping_ms);
      }
      if (data.type === "user_transcript") {
        const { user_transcription_event } = data;
        console.log("User transcript", user_transcription_event.user_transcript);
      }
      if (data.type === "agent_response") {
        const { agent_response_event } = data;
        console.log("Agent response", agent_response_event.agent_response);
      }
      if (data.type === "agent_response_correction") {
        const { agent_response_correction_event } = data;
        console.log("Agent response correction", agent_response_correction_event.corrected_agent_response);
      }
      if (data.type === "interruption") {
        // Handle interruption
      }
      if (data.type === "audio") {
        const { audio_event } = data;
        // Implement your own audio playback system here
        // Note: You'll need to handle audio queuing to prevent overlapping
        // as the WebSocket sends audio events in chunks
      }
      if (data.type === "agent_chat_response_part") {
        const { text_response_part } = data;
        const { type: partType, text, response_id } = text_response_part;
        // Handle the agent's response text as it is generated. Enable
        // agent_chat_response_part in the agent's client_events to receive
        // this during voice conversations.
        console.log("Chat response part:", partType, text, response_id);
      }
    };
    websocketRef.current = websocket;
    websocket.onclose = async () => {
      websocketRef.current = null;
      setIsConnected(false);
      stopStreaming();
    };
  }, [startStreaming, isConnected, stopStreaming]);
  const stopConversation = useCallback(async () => {
    if (!websocketRef.current) return;
    websocketRef.current.close();
  }, []);
  useEffect(() => {
    return () => {
      if (websocketRef.current) {
        websocketRef.current.close();
      }
    };
  }, []);
  return {
    startConversation,
    stopConversation,
    isConnected,
  };
};

会話コンポーネントを作成する

WebSocketフックを使用するコンポーネントを作成します。

app/components/Conversation.tsx

'use client';
import { useCallback } from 'react';
import { useAgentConversation } from '../hooks/useAgentConversation';
export function Conversation() {
  const { startConversation, stopConversation, isConnected } = useAgentConversation();
  const handleStart = useCallback(async () => {
    try {
      await navigator.mediaDevices.getUserMedia({ audio: true });
      await startConversation();
    } catch (error) {
      console.error('Failed to start conversation:', error);
    }
  }, [startConversation]);
  return (
    <div className="flex flex-col items-center gap-4">
      <div className="flex gap-2">
        <button
          onClick={handleStart}
          disabled={isConnected}
          className="px-4 py-2 bg-blue-500 text-white rounded disabled:bg-gray-300"
        >
          Start Conversation
        </button>
        <button
          onClick={stopConversation}
          disabled={!isConnected}
          className="px-4 py-2 bg-red-500 text-white rounded disabled:bg-gray-300"
        >
          Stop Conversation
        </button>
      </div>
      <div className="flex flex-col items-center">
        <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
      </div>
    </div>
  );
}

次のステップ

オーディオ再生：Web Audio APIまたはライブラリを使用して、独自のオーディオ再生システムを実装します。WebSocketはオーディオイベントをチャンク単位で送信するため、重複を防ぐオーディオキューイングを必ず処理してください。
エラー処理：再試行ロジックとエラー回復の仕組みを追加する
UIフィードバック：音声アクティビティと接続ステータスの視覚的なインジケーターを追加する

レイテンシー管理

スムーズな会話を実現するため、以下の戦略を実装してください。

**アダプティブバッファリング：**ネットワーク状況に応じてオーディオバッファリングを調整します。
**ジッターバッファ：**パケット到着時間のばらつきを平滑化するためにジッターバッファを実装します。
**Ping-Pongモニタリング：**pingおよびpongイベントを使用して往復時間を測定し、それに応じて調整します。

セキュリティのベストプラクティス

APIキーを定期的にローテーションし、環境変数に保存します。
不正利用を防ぐためにレート制限を実装します。
マイクへのアクセスをユーザーに求める際は、その意図を明確に説明します。
最適化されたチャンク化：レイテンシーと効率のバランスを取るため、オーディオチャンクの長さを調整します。

認証