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 내에서 사용해야 합니다. 이 provider로 앱(또는 관련 하위 트리)을 감싸세요.

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

Provider props

provider는 콜백, 클라이언트 도구, 오버라이드, 서버 위치를 포함하여 useConversation과 동일한 옵션을 허용합니다. 따라서 각 훅 소비자가 아닌 provider 수준에서 이를 구성할 수 있습니다.

<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>

제어되는 음소거 상태

provider는 제어되는 음소거 상태 관리를 위해 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 - 에이전트의 응답 텍스트가 생성되는 동안 시작, 델타, 중지 이벤트와 함께 호출되는 핸들러입니다. 텍스트 전용 모드에서는 항상 전송됩니다. 음성 대화의 경우 에이전트의 client_events 구성에서 agent_chat_response_part를 활성화하세요.

클라이언트 도구

클라이언트 도구를 사용하면 에이전트가 클라이언트 측 기능을 호출할 수 있습니다. 사용자를 대신하여 모달을 열거나 API 호출을 수행하는 등 클라이언트에서 작업을 트리거하는 데 사용할 수 있습니다.

클라이언트 도구 정의는 함수 객체이며, ElevenLabs 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

음소거 상태와 마이크를 전환하기 위한 setter를 반환합니다.

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 컴포넌트에서 클라이언트 도구를 동적으로 등록하기 위한 훅입니다. 컴포넌트가 언마운트되면 도구 등록이 자동으로 해제됩니다.

도구의 핸들러가 provider 수준에서는 사용할 수 없는 컴포넌트 상태나 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} />;
}

이 훅은 항상 핸들러의 최신 클로저 값을 사용하므로 오래된 상태를 걱정할 필요가 없습니다.