React SDK

インストール

パッケージマネージャーを使用して、プロジェクトにパッケージをインストールします。

npm install @elevenlabs/react
# or
yarn add @elevenlabs/react
# or
pnpm install @elevenlabs/react

使用方法

エージェントに接続し、ユーザーが音声会話を開始・終了できる最小限の動作例を以下に示します：

import {
  ConversationProvider,
  useConversationControls,
  useConversationStatus,
} from "@elevenlabs/react";
function App() {
  return (
    <ConversationProvider>
      <Agent />
    </ConversationProvider>
  );
}
function Agent() {
  const { startSession, endSession } = useConversationControls();
  const { status } = useConversationStatus();
  if (status === "connected") {
    return <button onClick={endSession}>End</button>;
  }
  return (
    <button onClick={() => startSession({ agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6" })}>
      Start
    </button>
  );
}

以下のセクションで、各部分を詳しく説明します。

ConversationProvider

すべての会話フックはConversationProvider内で使用する必要があります。このプロバイダーでアプリ（または対象のサブツリー）をラップしてください。

import { ConversationProvider } from "@elevenlabs/react";
function App() {
  return (
    <ConversationProvider>
      <YourComponents />
    </ConversationProvider>
  );
}

プロバイダーのprops

プロバイダーは、コールバック、クライアントツール、オーバーライド、サーバーロケーションを含むuseConversationと同じオプションを受け取ります。そのため、各フックの利用側ではなくプロバイダーレベルで設定できます。

<ConversationProvider
  onConnect={() => console.log("Connected")}
  onDisconnect={() => console.log("Disconnected")}
  onError={(error) => console.error("Error:", error)}
  clientTools={{
    displayMessage: (parameters: { text: string }) => {
      alert(parameters.text);
      return "Message displayed";
    },
  }}
  serverLocation="eu-residency"
>
  <YourComponents />
</ConversationProvider>

制御されたミュート状態

プロバイダーは、制御されたミュート状態の管理用にisMutedとonMutedChange propsをサポートしています。これにより、ミュート状態を外部で永続化できます（例：セッション間）。

const [muted, setMuted] = useState(false);
<ConversationProvider isMuted={muted} onMutedChange={setMuted}>
  <YourComponents />
</ConversationProvider>;

useConversation

すべての粒度の細かいフックを単一の戻り値にまとめた便利なReactフックです。親要素にConversationProviderが必要です。

会話を初期化する

import { useConversation } from "@elevenlabs/react";
function MyComponent() {
  const conversation = useConversation();
  // ...
}

ElevenAgentsでは、音声会話にマイクへのアクセスが必要です。会話が始まる前に、アプリのUIで理由を説明し、アクセスを許可できるようにしてください。

// call after explaining to the user why the microphone access is needed
await navigator.mediaDevices.getUserMedia({ audio: true });

オプション

フックはオプション付きで初期化できます。これらはConversationProviderレベルでも渡せます。

const conversation = useConversation({
  /* options object */
});

オプションは次のとおりです：

• clientTools - エージェントが呼び出せるクライアントツールのオブジェクト定義。詳細は以下を参照してください。
• overrides - 会話設定のオーバーライド用オブジェクト定義。詳細は以下を参照してください。
• textOnly - 会話をテキストのみモードで実行するかどうか。詳細は以下を参照してください。
• serverLocation - サーバーロケーションを指定します（"us"、"eu-residency"、"in-residency"、"global"）。デフォルトは"us"です。

コールバックの概要

• onConnect - 会話接続が確立されたときに呼び出されるハンドラー。
• onDisconnect - 会話接続が終了したときに呼び出されるハンドラー。
• onMessage - 新しいメッセージを受信したときに呼び出されるハンドラー。ユーザー音声の暫定または確定の文字起こし、LLMが生成した応答、デバッグオプションが有効な場合のデバッグメッセージが含まれます。
• onError - エラーが発生したときに呼び出されるハンドラー。
• onAudio - オーディオデータを受信したときに呼び出されるハンドラー。
• onModeChange - 会話モード（話す／聞く）が変わったときに呼び出されるハンドラー。
• onStatusChange - 接続ステータスが変わったときに呼び出されるハンドラー。
• onCanSendFeedbackChange - フィードバックを送信できるかどうかが変わったときに呼び出されるハンドラー。
• onDebug - デバッグ情報が利用可能になったときに呼び出されるハンドラー。
• onUnhandledClientToolCall - 未処理のクライアントツール呼び出しが発生したときに呼び出されるハンドラー。
• onVadScore - 音声アクティビティ検出スコアが変わったときに呼び出されるハンドラー。
• onAudioAlignment - オーディオアラインメントデータを受信したときに呼び出されるハンドラー。エージェント音声の文字単位のタイミング情報を提供します。
• onAgentChatResponsePart - エージェントの応答テキストが生成される際に、start、delta、stopイベントとして呼び出されるハンドラー。テキストのみモードでは常に送信されます。音声会話では、エージェントのclient_events設定でagent_chat_response_partを有効にしてください。

クライアントツール

クライアントツールを使うと、エージェントがクライアント側の機能を呼び出せます。モーダルを開く、ユーザーに代わってAPI呼び出しを行うなど、クライアントでのアクションをトリガーできます。

クライアントツールの定義は関数のオブジェクトで、ElevenLabs UI内の設定と一致している必要があります。UIでは、さまざまなツールに名前と説明を付け、エージェントから渡されるパラメーターを設定できます。

const conversation = useConversation({
  clientTools: {
    displayMessage: (parameters: { text: string }) => {
      alert(parameters.text);
      return "Message displayed";
    },
  },
});

関数が値を返す場合、その値は応答としてエージェントに返されます。

エージェントが応答を待機して反応できるよう、ElevenLabs UIでツールが会話をブロックするよう明示的に設定する必要があります。そうしない場合、エージェントは成功したものとみなし、会話を続行します。

会話のオーバーライド

会話のさまざまな設定をオーバーライドし、他のユーザー操作に基づいて動的に設定できます。

さまざまな設定をオーバーライドできます。これらの設定は任意で、会話体験のカスタマイズに使用できます。

利用可能な設定は次のとおりです：

const conversation = useConversation({
  overrides: {
    agent: {
      prompt: {
        prompt: "My custom prompt",
      },
      firstMessage: "My custom first message",
      language: "en",
    },
    tts: {
      voiceId: "custom voice id",
    },
    conversation: {
      textOnly: true,
    },
  },
});

テキストのみ

エージェントがテキストのみモード、つまりオーディオメッセージを送受信しないように設定されている場合、このフラグを使用して軽量版の会話を利用できます。この場合、ユーザーにマイクの権限を求めることはなく、オーディオコンテキストも作成されません。

const conversation = useConversation({
  textOnly: true,
});

制御された状態

フックオプションを通じて、会話状態の特定の要素を直接制御できます：

const [micMuted, setMicMuted] = useState(false);
const conversation = useConversation({
  micMuted,
  // ... other options
});
// Update controlled state
setMicMuted(true); // This will automatically mute the microphone

データレジデンシー

接続するElevenLabsサーバーリージョンを指定できます。詳細はデータレジデンシーガイドを参照してください。

const conversation = useConversation({
  serverLocation: "eu-residency", // or "us", "in-residency", "global"
});

メソッド

startSession

startSessionメソッドは接続を確立し、マイクを使用してElevenLabs Agentsエージェントとの通信を開始します。このメソッドはオプションオブジェクトを受け取り、signedUrl、conversationToken、agentIdのいずれかが必須です。

エージェントIDはElevenLabs UIで取得できます。

会話をユーザーに紐付けるため、独自のエンドユーザーIDも渡すことをおすすめします。

const conversation = useConversation();
// For public agents, pass in the agent ID
const conversationId = await conversation.startSession({
  agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  userId: "user_9302xkm82nds93", // optional field
});

パブリックエージェント（認証が有効になっていないエージェント）の場合、必要なのはagentIdのみです。

会話に認可が必要な場合は、REST APIを使用して、WebSocket接続用の署名付きリンクまたはWebRTC接続用の会話トークンを生成してください。

startSessionは、conversationIdに解決されるPromiseを返します。この値は、個別の会話を識別するために使用できるグローバルに一意な会話IDです。

// Node.js server
app.get("/signed-url", yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a signed url requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        "xi-api-key": process.env.ELEVENLABS_API_KEY,
      },
    }
  );
  if (!response.ok) {
    return res.status(500).send("Failed to get signed URL");
  }
  const body = await response.json();
  res.send(body.signed_url);
});

// Client
const response = await fetch("/signed-url", yourAuthHeaders);
const signedUrl = await response.text();
await conversation.startSession({
  signedUrl,
});

endSession

会話を手動で終了するためのメソッドです。接続を切断して会話を終了します。

await conversation.endSession();

setVolume

会話の出力音量を設定します。0から1までのvolumeフィールドを持つオブジェクトを受け取ります。

await conversation.setVolume({ volume: 0.5 });

sendUserMessage

エージェントにテキストメッセージを送信します。

マイクを使用する代わりに、ユーザーがメッセージを入力できるようにするために使用できます。sendContextualUpdateとは異なり、これはユーザーメッセージとして扱われ、エージェントに会話の応答を促します。

const { sendUserMessage, sendUserActivity } = useConversation();
const [value, setValue] = useState("");
return (
  <>
    <input
      value={value}
      onChange={e => {
        setValue(e.target.value);
        sendUserActivity();
      }}
    />
    <button
      onClick={() => {
        sendUserMessage(value);
        setValue("");
      }}
    >
      SEND
    </button>
  </>
);

sendContextualUpdate

応答をトリガーしないコンテキスト情報をエージェントに送信します。

const { sendContextualUpdate } = useConversation();
sendContextualUpdate(
  "User navigated to another page. Consider it for next response, but don't react to this contextual update."
);

sendFeedback

会話の品質に関するフィードバックを提供します。これはエージェントのパフォーマンス向上に役立ちます。

const { sendFeedback } = useConversation();
sendFeedback(true); // positive feedback
sendFeedback(false); // negative feedback

sendUserActivity

中断を防ぐため、ユーザーのアクティビティをエージェントに通知します。ユーザーがアプリを操作中で、エージェントが発話を一時停止すべき場合、たとえばユーザーがチャットで入力している場合に便利です。

このシグナルを受信した後、エージェントは約2秒間発話を停止します。

const { sendUserActivity } = useConversation();
// Call this when user is typing to prevent interruption
sendUserActivity();

changeInputDevice

アクティブな音声会話中にオーディオ入力デバイスを切り替えます。このメソッドは音声会話でのみ使用できます。

// Change to a specific input device
conversation.changeInputDevice({
  sampleRate: 16000,
  format: "pcm",
  preferHeadphonesForIosDevices: true,
  inputDeviceId: "a1b2c3d4e5f6", // Optional: specific device ID
});

changeOutputDevice

アクティブな音声会話中にオーディオ出力デバイスを切り替えます。このメソッドは音声会話でのみ使用できます。

// Change to a specific output device
conversation.changeOutputDevice({
  sampleRate: 16000,
  format: "pcm",
  outputDeviceId: "a1b2c3d4e5f6", // Optional: specific device ID
});

getId

現在の会話IDを返します。

const { getId } = useConversation();
const conversationId = getId();
console.log(conversationId); // e.g., "conv_9001k1zph3fkeh5s8xg9z90swaqa"

getInputVolume / getOutputVolume

現在の入出力音量レベル（0～1のスケール）を返すメソッドです。

const { getInputVolume, getOutputVolume } = useConversation();
const inputLevel = getInputVolume();
const outputLevel = getOutputVolume();

getInputByteFrequencyData / getOutputByteFrequencyData

現在の入出力周波数データを含むUint8Arrayを返すメソッドです。詳細はAnalyserNode.getByteFrequencyDataを参照してください。

const { getInputByteFrequencyData, getOutputByteFrequencyData } = useConversation();
const inputFrequencyData = getInputByteFrequencyData();
const outputFrequencyData = getOutputByteFrequencyData();

sendMCPToolApprovalResult

MCP（Model Context Protocol）ツール呼び出しの承認結果を送信します。

const { sendMCPToolApprovalResult } = useConversation();
// Approve a tool call
sendMCPToolApprovalResult("tc_8k2m4n6p8r0t", true);
// Reject a tool call
sendMCPToolApprovalResult("tc_8k2m4n6p8r0t", false);

戻り値

上記のメソッドに加えて、useConversationは以下のリアクティブな状態を返します：

• status - 現在の接続ステータス（"disconnected"、"connecting"、"connected"）。
• isSpeaking - エージェントが現在話しているかどうか。
• isListening - エージェントが現在聞いているかどうか。
• mode - 現在の会話モード（"speaking"または"listening"）。
• isMuted - マイクが現在ミュートされているかどうか。
• setMuted - マイクをミュート／ミュート解除する関数。
• canSendFeedback - 現在の会話にフィードバックを送信できるかどうか。
• message - 会話からの最新メッセージ。

const { status, isSpeaking, isListening, isMuted, setMuted, canSendFeedback } = useConversation();
return (
  <div>
    <p>Status: {status}</p>
    <p>Agent is {isSpeaking ? 'speaking' : 'listening'}</p>
    <button onClick={() => setMuted(!isMuted)}>
      {isMuted ? 'Unmute' : 'Mute'}
    </button>
  </div>
);

粒度の細かいフック

レンダリングパフォーマンスを向上させるには、useConversationの代わりにこれらのフックを使用してください。各フックは対象とする状態の一部のみを購読するため、コンポーネントは消費するデータが変化した場合にのみ再レンダリングされます。

すべての粒度の細かいフックには、親要素にConversationProviderが必要です。

useConversationControls

会話を制御するアクションメソッドを返します。安定した関数参照のみを提供するため、このフックによって再レンダリングが発生することはありません。

import { useConversationControls } from "@elevenlabs/react";
function Controls() {
  const {
    startSession,
    endSession,
    sendUserMessage,
    sendContextualUpdate,
    sendUserActivity,
    setVolume,
    changeInputDevice,
    changeOutputDevice,
    sendMCPToolApprovalResult,
    getId,
    getInputVolume,
    getOutputVolume,
    getInputByteFrequencyData,
    getOutputByteFrequencyData,
  } = useConversationControls();
  return (
    <button onClick={() => startSession({ agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6" })}>
      Start
    </button>
  );
}

useConversationStatus

現在の接続ステータスと任意のステータスメッセージを返します。

import { useConversationStatus } from "@elevenlabs/react";
function StatusIndicator() {
  const { status, message } = useConversationStatus();
  return <p>Status: {status}</p>; // "disconnected" | "connecting" | "connected"
}

useConversationInput

ミュート状態と、マイクのオン／オフを切り替えるセッターを返します。

import { useConversationInput } from "@elevenlabs/react";
function MuteToggle() {
  const { isMuted, setMuted } = useConversationInput();
  return <button onClick={() => setMuted(!isMuted)}>{isMuted ? "Unmute" : "Mute"}</button>;
}

useConversationMode

エージェントの発話／聞き取り状態を返します。

import { useConversationMode } from "@elevenlabs/react";
function ModeIndicator() {
  const { mode, isSpeaking, isListening } = useConversationMode();
  return <p>Agent is {isSpeaking ? "speaking" : "listening"}</p>;
}

useConversationFeedback

フィードバックの可否と、フィードバックを送信するメソッドを返します。

import { useConversationFeedback } from "@elevenlabs/react";
function FeedbackButtons() {
  const { canSendFeedback, sendFeedback } = useConversationFeedback();
  if (!canSendFeedback) return null;
  return (
    <div>
      <button onClick={() => sendFeedback(true)}>Like</button>
      <button onClick={() => sendFeedback(false)}>Dislike</button>
    </div>
  );
}

useRawConversation

生の会話インスタンスを返します。これは、基盤となるVoiceConversationまたはTextConversationオブジェクトに直接アクセスする必要がある高度なユースケース向けのエスケープハッチです。

import { useRawConversation } from "@elevenlabs/react";
function Advanced() {
  const conversation = useRawConversation();
  // Access the raw conversation instance directly
}

useConversationClientTool

Reactコンポーネントからクライアントツールを動的に登録するためのフックです。コンポーネントがアンマウントされると、ツールは自動的に登録解除されます。

プロバイダーレベルでは利用できないコンポーネントのstateやpropsに、ツールのハンドラーからアクセスする必要がある場合に便利です。

import { useConversationClientTool } from "@elevenlabs/react";
import { useState } from "react";
function MapComponent() {
  const [location, setLocation] = useState({ lat: 0, lng: 0 });
  useConversationClientTool("getLocation", () => {
    return `${location.lat},${location.lng}`;
  });
  useConversationClientTool("setLocation", (params: { lat: number; lng: number }) => {
    setLocation(params);
    return "Location updated";
  });
  return <Map center={location} />;
}

このフックは常にハンドラーの最新のクロージャ値を使用するため、古いstateを心配する必要はありません。