@vox-ai/client

vox.ai voice agent와 브라우저에서 직접 연결하기 위한 JavaScript SDK.

설치

npm install @vox-ai/client
# or
yarn add @vox-ai/client
# or
pnpm add @vox-ai/client

빠른 시작

import { Conversation } from "@vox-ai/client";

// 마이크 권한 요청 (UI에서 사전 안내 권장)
await navigator.mediaDevices.getUserMedia({ audio: true });

const conversation = await Conversation.startSession({
  agentId: "YOUR_AGENT_ID",
  apiKey: "YOUR_API_KEY",
  onStatusChange: (status) => console.log("status:", status),
  onModeChange: (mode) => console.log("mode:", mode),
  onMessage: (message) => console.log(`${message.source}: ${message.text}`),
  onError: (error) => console.error("error:", error.message),
});

세션 옵션

Conversation.startSession(options)에 전달하는 설정.

| 옵션 | 타입 | 필수 | 설명 | |------|------|------|------| | agentId | string | O | Agent ID | | apiKey | string | O | API key | | agentVersion | string | | Agent version ("current", "production", "v1" 등, default: "current") | | textOnly | boolean | | Text-only session (true면 mic/audio 없이 chat mode로 연결, default: false) | | dynamicVariables | Record<string, string \| number \| boolean> | | Agent prompt에 주입할 dynamic variables | | metadata | Record<string, unknown> | | Call metadata (webhook, call log에 포함) |

콜백

| 콜백 | 시그니처 | 설명 | |------|----------|------| | onConnect | () => void | 연결 성공 | | onDisconnect | () => void | 연결 종료 | | onStatusChange | (status: ConversationStatus) => void | Status 변경 ("disconnected" → "connecting" → "connected") | | onModeChange | (mode: ConversationMode) => void | Mode 변경 ("listening" ⇄ "speaking") | | onMessage | (message: ConversationMessage) => void | 메시지 수신 (user transcription, agent response) | | onError | (error: Error) => void | 에러 발생 |

메서드

세션 제어

// 세션 종료
await conversation.endSession();

// 세션 ID 조회
const id = conversation.getId();

// 현재 세션 메시지 조회
const messages = conversation.getMessages();

메시지 전송

// 텍스트 메시지 전송 (음성 대신 텍스트 입력)
await conversation.sendUserMessage("안녕하세요");

메시지 히스토리

const messages = conversation.getMessages();

messages.forEach((message) => {
  console.log(message.source, message.text, message.isFinal);
});

• getMessages()는 현재 세션에서 주고받은 메시지를 timestamp 순으로 반환
• 동일 id의 streaming update는 최신 메시지로 반영

Text Only

const conversation = await Conversation.startSession({
  agentId: "YOUR_AGENT_ID",
  apiKey: "YOUR_API_KEY",
  textOnly: true,
});

await conversation.sendUserMessage("텍스트로만 대화할게요");

• text-only session은 microphone 권한을 요청하지 않음
• 에이전트 응답은 LiveKit text stream으로 수신됨
• audio 전용 API는 안전한 no-op 또는 zero-value를 반환

마이크 제어

// 음소거
await conversation.setMicMuted(true);

// 음소거 해제
await conversation.setMicMuted(false);

// 현재 음소거 상태 조회
const isMuted = conversation.getMicMuted();

볼륨 제어

// Agent 음성 볼륨 설정 (0.0 ~ 1.0)
conversation.setVolume({ volume: 0.5 });

상태 조회

const status = conversation.getStatus(); // "disconnected" | "connecting" | "connected"
const mode = conversation.getMode();     // "listening" | "speaking"

오디오 모니터링

// 입출력 볼륨 (0.0 ~ 1.0)
const inputVol = conversation.getInputVolume();
const outputVol = conversation.getOutputVolume();

// Frequency data (Uint8Array, 시각화용)
const inputFreq = conversation.getInputByteFrequencyData();
const outputFreq = conversation.getOutputByteFrequencyData();

디바이스 전환

// 입력 디바이스 변경
await conversation.changeInputDevice({ inputDeviceId: "device-id" });

// 출력 디바이스 변경
await conversation.changeOutputDevice({ outputDeviceId: "device-id" });

디바이스 목록은 navigator.mediaDevices.enumerateDevices()로 조회.

Dynamic Variables / Metadata

const conversation = await Conversation.startSession({
  agentId: "YOUR_AGENT_ID",
  apiKey: "YOUR_API_KEY",
  agentVersion: "production",
  dynamicVariables: {
    userName: "홍길동",
    userType: "premium",
    accountBalance: 50000,
  },
  metadata: {
    sessionId: "sess_abc123",
    source: "mobile-app",
  },
});

• dynamicVariables — Agent prompt에서 {{userName}} 형식으로 참조
• metadata — Outbound webhook과 call log에 포함

Export 타입

import type {
  ConversationMessage,
  ConversationMode,
  ConversationSource,
  ConversationStatus,
  InputDeviceConfig,
  OutputDeviceConfig,
  SetVolumeParams,
  StartSessionOptions,
} from "@vox-ai/client";

참고

• 인증은 apiKey 직접 전달 방식
• 내부 연결은 LiveKit WebRTC 기반
• 브라우저별 audio device 제약이 있을 수 있음