JavaScript - vox.ai 문서

@vox-ai/client는 바닐라 JavaScript 프로젝트에서 바로 쓰는 SDK예요. 프레임워크별 라이브러리의 기반으로도 쓸 수 있어요. React를 쓰면 React를 보세요.

설치하기

프로젝트에 패키지를 설치하세요.

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

세션 시작하기

Conversation.startSession(options)으로 세션을 시작하세요. 이 호출로 WebRTC 연결이 열리고, 마이크로 에이전트와 통화가 시작돼요.

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

const conversation = await Conversation.startSession(options);

세션을 시작하기 전에 화면에서 마이크 접근 권한이 필요한 이유를 알리고 권한을 요청하세요.

// 마이크 권한이 필요한 이유를 UI에서 안내한 후 호출
await navigator.mediaDevices.getUserMedia({ audio: true });

세션 설정

startSession에 넘기는 옵션으로 세션 방식을 정해요. Agent ID는 vox.ai 대시보드에서 확인하세요.

const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  apiKey: "<your-client-key>",
  visitorId: "visitor_1024",
});

옵션	타입	필수	설명
`agentId`	`string`	O	Agent ID
`apiKey`	`string`	O	클라이언트용 키예요. `pk_`로 시작하는 키를 넣어요. 서버에서 실행할 때는 서버용 키(`sk_`)도 쓸 수 있어요
`agentVersion`	`string`	-	에이전트 버전(`"current"`, `"production"`, `"v1"` 등). 기본값 `"current"`
`textOnly`	`boolean`	-	`true`면 마이크와 오디오 없이 텍스트로만 연결해요. 기본값 `false`
`dynamicVariables`	`Record<string, string \| number \| boolean>`	-	에이전트 프롬프트에 넣을 동적 변수
`metadata`	`Record<string, unknown>`	-	통화 메타데이터. 웹훅과 통화 기록에 들어가요
`visitorId`	`string`	-	같은 방문자의 세션을 한 고객으로 이어 붙일 고정 ID
`audio`	`AudioOptions`	-	브라우저 마이크 처리 옵션. `echoCancellation`·`noiseSuppression`·`autoGainControl`을 하나씩 끌 수 있고 기본값은 모두 `true`

브라우저에는 클라이언트용 키(pk_)를 넣고, 서버용 키(sk_)는 공개 웹페이지에 넣지 마세요. 클라이언트용 키는 세션 시작만 할 수 있어요.

키를 만들고 바꾸는 방법은 API 키에 있어요.

visitorId: 생략하면 SDK가 브라우저별 ID를 만들어 저장하고 다음 세션에도 다시 써요. 이 값은 vox.ai 내부 고객 UUID가 아니에요. 다른 기기, 시크릿 모드, 브라우저 저장소를 지운 뒤에는 새 익명 고객이 생길 수 있어요. 브라우저에 공개되는 값이라 조작될 수 있으니 로그인 여부나 권한 판단에 쓰지 마세요.
메모리: 에이전트의 메모리가 켜져 있으면 같은 고객과 에이전트에 저장된 메모리를 첫 응답 전에 자동으로 불러와요. SDK에서 메모리를 따로 조회하지 않아도 돼요.
audio: 브라우저가 마이크 입력에 기본으로 적용하는 에코 제거, 잡음 억제, 자동 음량 조절을 항목별로 꺼요. 생략하면 셋 다 켜져 있고, Text Only 세션에서는 무시돼요.
Android Chrome의 통화 모드: 에코 제거가 켜진 마이크를 열면 기기가 통화 모드로 바뀌어 에이전트 음성이 미디어가 아닌 통화 경로로 재생돼요. 사용자가 이어폰이나 헤드셋을 쓰거나 앱에서 마이크 입력을 따로 처리하면 echoCancellation: false로 피할 수 있어요.
스피커폰: echoCancellation을 끄면 스피커로 나온 에이전트 음성이 마이크로 다시 들어가 사용자 발화로 처리돼요. 에이전트가 자기 목소리에 반응해 말을 끊을 수 있으니 스피커폰을 쓰는 화면에서는 끄지 마세요.

콜백 받기

startSession 옵션으로 콜백(Callback)을 등록할 수 있어요.

onConnect: 세션이 연결되면 불려요.
onDisconnect: 연결이 끊기면 불려요.
onMessage: 메시지가 들어올 때 불려요. 사용자 음성을 옮긴 텍스트나 에이전트 응답이 여기로 와요.
onError: 오류가 나면 불려요.
onStatusChange: 연결 상태가 바뀔 때 불려요. "disconnected", "connecting", "connected" 가운데 하나가 넘어와요.
onAgentStateChange: 에이전트 상태가 "initializing", "idle", "listening", "thinking", "speaking" 가운데 하나로 바뀔 때 불려요.

const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  apiKey: "<your-client-key>",
  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),
  onAgentStateChange: (agentState) => console.log("Agent state:", agentState),
});

startSession은 세션을 제어하는 Conversation 인스턴스를 돌려줘요. 연결이 실패하면 onError를 부른 뒤 오류를 던지고, 이때 onDisconnect는 불리지 않아요.

연결 확인

세션을 시작한 뒤 콜백으로 연결을 확인하세요.

연결 상태: onStatusChange에 "connecting"과 "connected"가 차례로 오고, 연결되면 onConnect가 불려요.
마이크: 음성 세션이면 conversation.getMicMuted()가 false예요. true면 마이크를 켜지 못한 채 연결된 거예요.
에이전트 응답: 에이전트가 말하면 onAgentStateChange에 "speaking"이 오고, onMessage로 source가 "agent"인 메시지가 와요.

세션 제어하기

endSession

세션을 끝내요. 연결을 끊고 리소스를 정리하며, Promise<void>를 돌려줘요.

await conversation.endSession();

getId

지금 세션 ID를 돌려줘요. 세션 ID가 없으면 undefined를 돌려줘요.

const id = conversation.getId();

getMessages

세션에서 주고받은 메시지를 timestamp 순으로 돌려줘요.

const messages = conversation.getMessages();

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

sendUserMessage

에이전트에게 텍스트 메시지를 보내요. 마이크 대신 텍스트로 입력할 때 쓰세요. Promise<void>를 돌려줘요.

sendButton.addEventListener("click", async () => {
  await conversation.sendUserMessage(textInput.value);
  textInput.value = "";
});

setVolume

에이전트 음성의 출력 볼륨을 조절해요. 0~1 사이 값을 넣으세요.

conversation.setVolume({ volume: 0.5 });

setMicMuted

마이크를 음소거하거나 해제해요. Promise<void>를 돌려줘요.

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

// 해제
await conversation.setMicMuted(false);

getInputVolume / getOutputVolume

지금 입출력 볼륨을 0~1 스케일로 돌려줘요.

const inputVolume = conversation.getInputVolume();
const outputVolume = conversation.getOutputVolume();

getInputByteFrequencyData / getOutputByteFrequencyData

입출력 주파수 데이터를 Uint8Array로 돌려줘요. 오디오 시각화에 쓸 수 있어요.

const inputFrequency = conversation.getInputByteFrequencyData();
const outputFrequency = conversation.getOutputByteFrequencyData();

오디오 모니터링 메서드는 음성 세션에서만 동작해요. 볼륨과 주파수 측정은 이 메서드를 처음 부를 때 시작돼서 첫 호출은 0이나 빈 배열을 돌려줄 수 있어요. 한 번도 부르지 않으면 SDK는 측정용 AudioContext를 만들지 않아요.

changeInputDevice

세션 중에 오디오 입력 장치를 바꿔요. 전환 성공 여부를 담은 Promise<boolean>을 돌려줘요.

const changed = await conversation.changeInputDevice({
  inputDeviceId: "your-device-id",
});

changeOutputDevice

세션 중에 오디오 출력 장치를 바꿔요. 전환 성공 여부를 담은 Promise<boolean>을 돌려줘요.

const changed = await conversation.changeOutputDevice({
  outputDeviceId: "your-device-id",
});

장치 전환은 음성 세션에서만 동작해요. deviceId를 지정하지 않으면 브라우저 기본 장치를 써요. 쓸 수 있는 장치 목록은 MediaDevices.enumerateDevices() API로 조회하세요.

상태 조회하기

const status = conversation.getStatus(); // "disconnected" | "connecting" | "connected"
const agentState = conversation.getAgentState();
// "initializing" | "idle" | "listening" | "thinking" | "speaking" | undefined
const muted = conversation.getMicMuted(); // boolean

agentState는 "initializing", "idle", "listening", "thinking", "speaking" 가운데 하나이고, 아직 받기 전에는 undefined예요. isSpeaking 같은 화면 상태가 필요하면 agentState === "speaking"으로 계산하세요.

텍스트로만 대화하기

텍스트 전용 모드(Text Only)를 쓰면 마이크 없이 텍스트만으로 에이전트와 대화할 수 있어요.

const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  apiKey: "<your-client-key>",
  textOnly: true,
  onMessage: (msg) => console.log(`${msg.source}: ${msg.text}`),
});

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

Text Only 세션은 마이크 권한을 요청하지 않아요.
오디오 관련 API(getInputVolume 등)는 0에 해당하는 값을 돌려줘요.

동적 변수와 메타데이터 넘기기

const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  apiKey: "<your-client-key>",
  dynamicVariables: {
    userName: "홍길동",
    userType: "premium",
    accountBalance: 50000,
  },
  metadata: {
    sessionId: "sess_abc123",
    source: "web-app",
  },
});

dynamicVariables: 에이전트 프롬프트에서 {{userName}} 꼴로 참조해요. 자세한 쓰임은 동적 변수에 있어요.
metadata: 웹훅과 통화 기록에 들어가요.

문제가 생겼을 때

startSession이 Session initialization failed 오류로 끝나요

agentId와 apiKey 값을 확인하세요. 세션을 만드는 요청이 거절되면 SDK가 Session initialization failed (상태 코드): 응답 본문 꼴의 오류를 던지고, 괄호 안 상태 코드와 응답 본문에 거절된 까닭이 있어요. 응답 본문에 API_KEY_NOT_FOR_SESSIONS가 있으면 클라이언트용 키 출시 이후 만든 서버용 키(sk_)를 브라우저에서 쓴 경우예요. 클라이언트용 키(pk_)로 바꾸세요.

연결됐는데 에이전트가 내 말을 듣지 못해요

브라우저의 마이크 권한과 입력 장치를 확인한 뒤 setMicMuted(false)로 마이크를 다시 켜세요. 세션을 시작할 때 마이크를 켜지 못하면 SDK는 onError만 부르고 마이크가 꺼진 채로 연결해요. 다시 켜지 못하면 setMicMuted가 오류를 던져요.

visitorId must be a non-empty string 오류가 나요

visitorId에 공백이 아닌 값을 넣거나 옵션을 빼세요. 앞뒤 공백을 지운 값이 비어 있으면 SDK가 세션 요청을 보내기 전에 TypeError를 던져요. 옵션을 빼면 SDK가 브라우저별 ID를 만들어 써요.

연결이 끊긴 뒤 다시 이어지지 않아요

Conversation.startSession을 다시 불러 새 세션을 여세요. 연결이 끊기면 SDK가 onDisconnect를 부르고 세션을 정리해서, 끊긴 Conversation 인스턴스로는 다시 연결할 수 없어요.

​설치하기

​세션 시작하기

​세션 설정

​콜백 받기

​연결 확인

​세션 제어하기

​endSession

​getId

​getMessages

​sendUserMessage

​setVolume

​setMicMuted

​getInputVolume / getOutputVolume

​getInputByteFrequencyData / getOutputByteFrequencyData

​changeInputDevice

​changeOutputDevice

​상태 조회하기

​텍스트로만 대화하기

​동적 변수와 메타데이터 넘기기

​문제가 생겼을 때

​관련 문서

설치하기

세션 시작하기

세션 설정

콜백 받기

연결 확인

세션 제어하기

endSession

getId

getMessages

sendUserMessage

setVolume

setMicMuted

getInputVolume / getOutputVolume

getInputByteFrequencyData / getOutputByteFrequencyData

changeInputDevice

changeOutputDevice

상태 조회하기

텍스트로만 대화하기

동적 변수와 메타데이터 넘기기

문제가 생겼을 때

관련 문서