Skip to main content

​
설치

프로젝트에 패키지를 설치하세요. 
npm install @vox-ai/react
# or
yarn add @vox-ai/react
# or
pnpm add @vox-ai/react

​
사용법

​
useConversation

vox.ai 에이전트 연결과 오디오 상태를 관리하는 React 훅입니다.

​
세션 초기화

useConversation으로 Conversation 인스턴스를 만듭니다. 
import { useConversation } from "@vox-ai/react";

const conversation = useConversation();
음성 세션에는 마이크 권한이 필요합니다. 세션 시작 전에 UI에서 안내하고 요청해 주세요. 
// 마이크 권한이 필요한 이유를 UI에서 안내한 후 호출
await navigator.mediaDevices.getUserMedia({ audio: true });

​
옵션

훅 초기화 시 콜백과 옵션을 넘길 수 있습니다. 
const conversation = useConversation({
  /* options */
});
옵션:
  • textOnly — Text Only 모드 기본값. 아래를 참고하세요.

​
콜백

  • onConnect — 세션이 연결되면 불립니다.
  • onDisconnect — 연결이 끊기면 불립니다.
  • onMessage — 메시지가 들어올 때 불립니다. 사용자 음성의 텍스트 변환이나 에이전트 응답이 여기로 옵니다.
  • onError — 에러 발생 시 불립니다.
  • onStatusChange — 연결 상태가 바뀔 때 불립니다.
  • onModeChange — 에이전트가 "speaking" ↔ "listening" 사이를 오갈 때 불립니다.
const conversation = useConversation({
  onConnect: () => console.log("Connected"),
  onDisconnect: () => console.log("Disconnected"),
  onMessage: (message) => console.log(`${message.source}: ${message.text}`),
  onError: (error) => console.error("Error:", error),
  onStatusChange: (status) => console.log("Status:", status),
  onModeChange: (mode) => console.log("Mode:", mode),
});

​
메서드

startSession
세션을 시작합니다. Agent ID는 vox.ai 대시보드에서 확인하세요. 세션 고유 ID를 resolve하는 Promise를 돌려줍니다. 
const conversation = useConversation();

const conversationId = await conversation.startSession({
  agentId: "<your-agent-id>",
  apiKey: "<your-api-key>",
});
startSession 옵션:
옵션타입필수설명
agentIdstringOAgent ID
apiKeystringOAPI Key
agentVersionstring에이전트 버전. 기본값 "current"
textOnlyboolean세션 단위 Text Only override
dynamicVariablesRecord<string, string | number | boolean>프롬프트에 주입할 동적 변수
metadataRecord<string, unknown>콜 메타데이터 (웹훅, 통화 기록에 포함)
endSession
세션을 종료합니다. 
await conversation.endSession();
setVolume
출력 볼륨을 조절합니다. 0~1 사이 값을 넣으세요. 
conversation.setVolume({ volume: 0.5 });
sendUserMessage
에이전트에게 텍스트 메시지를 보냅니다. 마이크 대신 텍스트로 입력할 때 쓰세요. 
const [value, setValue] = useState("");

return (
  <>
    <input value={value} onChange={(e) => setValue(e.target.value)} />
    <button
      onClick={() => {
        conversation.sendUserMessage(value);
        setValue("");
      }}
    >
      전송
    </button>
  </>
);
setMicMuted
마이크를 음소거하거나 해제합니다. 
// 음소거
await conversation.setMicMuted(true);

// 해제
await conversation.setMicMuted(false);
getId
현재 세션 ID를 돌려줍니다. 
const conversationId = conversation.getId();
getMessages
세션의 메시지 배열 snapshot을 돌려줍니다. 
const messages = conversation.getMessages();
getInputVolume / getOutputVolume
현재 입출력 볼륨을 0~1 스케일로 돌려줍니다. 
const inputLevel = conversation.getInputVolume();
const outputLevel = conversation.getOutputVolume();
getInputByteFrequencyData / getOutputByteFrequencyData
입출력 주파수 데이터를 Uint8Array로 돌려줍니다. 오디오 시각화에 쓸 수 있습니다. 
const inputFrequency = conversation.getInputByteFrequencyData();
const outputFrequency = conversation.getOutputByteFrequencyData();
오디오 모니터링 메서드는 음성 세션에서만 동작합니다.
changeInputDevice
세션 중에 오디오 입력 디바이스를 바꿉니다. 
await conversation.changeInputDevice({
  inputDeviceId: "your-device-id",
});
changeOutputDevice
세션 중에 오디오 출력 디바이스를 바꿉니다. 
await conversation.changeOutputDevice({
  outputDeviceId: "your-device-id",
});
디바이스 전환은 음성 세션에서만 동작합니다. deviceId를 지정하지 않으면 브라우저 기본 디바이스가 쓰입니다. 사용 가능한 디바이스 목록은 MediaDevices.enumerateDevices() API로 조회하세요.

​
React State

State타입설명
statusConversationStatus"disconnected" | "connecting" | "connected"
isSpeakingboolean에이전트가 지금 말하고 있는지
micMutedboolean마이크 음소거 상태
messagesConversationMessage[]세션에서 주고받은 메시지 배열
const { status, isSpeaking, micMuted, messages } = useConversation();
JavaScript SDK의 getStatus(), getMode(), getMicMuted()에 대응합니다. React에서는 state로 제공되어 값이 바뀌면 자동으로 re-render됩니다.

​
Text Only 모드

마이크 없이 텍스트만으로 에이전트와 대화할 수 있습니다. 마이크 권한을 요청하지 않고 오디오 컨텍스트도 만들지 않습니다. 
const conversation = useConversation({
  textOnly: true,
});

await conversation.startSession({
  agentId: "<your-agent-id>",
  apiKey: "<your-api-key>",
});

await conversation.sendUserMessage("안녕하세요");

​
Dynamic Variables와 Metadata

const conversationId = await conversation.startSession({
  agentId: "<your-agent-id>",
  apiKey: "<your-api-key>",
  dynamicVariables: {
    userName: "홍길동",
    userType: "premium",
    accountBalance: 50000,
  },
  metadata: {
    sessionId: "sess_abc123",
    source: "web-app",
  },
});
  • dynamicVariables — 에이전트 프롬프트에서 {{userName}} 형식으로 참조됩니다. 동적 변수에서 자세히 알아보세요.
  • metadata — 웹훅과 통화 기록에 포함됩니다.

​
전체 예제

import { useConversation } from "@vox-ai/react";
import { useState } from "react";

function VoiceWidget() {
  const conversation = useConversation({
    onConnect: () => console.log("Connected"),
    onDisconnect: () => console.log("Disconnected"),
    onMessage: (msg) => console.log(`${msg.source}: ${msg.text}`),
    onError: (err) => console.error("Error:", err),
  });

  const start = async () => {
    await navigator.mediaDevices.getUserMedia({ audio: true });
    await conversation.startSession({
      agentId: "your-agent-id",
      apiKey: "your-api-key",
    });
  };

  return (
    <div>
      <p>Status: {conversation.status}</p>
      <p>Speaking: {conversation.isSpeaking ? "Yes" : "No"}</p>

      <button
        onClick={start}
        disabled={conversation.status !== "disconnected"}
      >
        시작
      </button>
      <button onClick={() => conversation.endSession()}>종료</button>
    </div>
  );
}
React SDK, 리액트 SDK, useConversation, @vox-ai/react, 훅, hook, 웹 연동