JavaScript - vox.ai Docs

설치

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

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

사용법

바닐라 JavaScript 프로젝트에서 바로 쓸 수 있고, 프레임워크별 라이브러리의 기반으로도 쓸 수 있습니다. React를 쓴다면 React를, React Native를 쓴다면 React Native를 확인해 보세요.

세션 초기화

Conversation.startSession(options)으로 세션을 시작합니다.

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

const conversation = await Conversation.startSession(options);

이 호출로 WebRTC 연결이 시작되고, 마이크를 통해 에이전트와 통화가 열립니다. 세션 시작 전에 UI에서 마이크 접근 권한을 안내하고 요청해 주세요.

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

세션 설정

startSession에 전달하는 옵션으로 세션 방식을 설정합니다. Agent ID는 vox.ai 대시보드에서 확인하세요.

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

옵션	타입	필수	설명
`agentId`	`string`	O	Agent ID
`apiKey`	`string`	O	API Key
`agentVersion`	`string`		에이전트 버전 (`"current"`, `"production"`, `"v1"` 등). 기본값 `"current"`
`textOnly`	`boolean`		`true`면 마이크/오디오 없이 텍스트 전용으로 연결. 기본값 `false`
`dynamicVariables`	`Record<string, string \| number \| boolean>`		에이전트 프롬프트에 주입할 동적 변수
`metadata`	`Record<string, unknown>`		콜 메타데이터 (웹훅, 통화 기록에 포함)
`visitorId`	`string`		같은 방문자의 세션을 하나의 Customer로 이어 붙일 안정적인 ID
`audio`	`AudioOptions`		브라우저 마이크 처리 옵션. `echoCancellation`·`noiseSuppression`·`autoGainControl`을 각각 끌 수 있으며 기본값은 모두 `true`

visitorId를 생략하면 SDK가 브라우저별 ID를 만들고 저장해 다음 세션에도 재사용합니다. 이 값은 vox.ai 내부 Customer UUID가 아닙니다. 다른 기기나 시크릿 모드, 브라우저 저장소 삭제 후에는 새 익명 Customer가 생길 수 있습니다.

브라우저에 공개되는 visitorId는 조작될 수 있습니다. 로그인 여부나 권한을 판단하는 데 사용하지 마세요.

에이전트의 Memory가 켜져 있으면 같은 Customer와 에이전트에 저장된 Memory를 첫 응답 전에 자동으로 불러옵니다. SDK에서 Memory를 따로 조회할 필요가 없습니다.

apiKey는 조직 secret입니다. 공개 웹페이지에는 넣지 마세요. 노출됐다고 판단되면 대시보드에서 즉시 로테이션하세요.

audio는 브라우저가 마이크 입력에 기본으로 적용하는 에코 제거·잡음 억제·자동 음량 조절을 항목별로 끕니다. 생략하면 셋 다 켜진 상태입니다. Android Chrome은 에코 제거가 켜진 마이크를 열면 기기를 통화 모드로 전환해 에이전트 음성이 미디어가 아닌 통화 경로로 재생됩니다. 사용자가 이어폰·헤드셋을 쓰거나 앱에서 마이크 입력을 따로 처리한다면 echoCancellation: false로 이를 피할 수 있습니다. Text Only 세션에서는 무시됩니다.

스피커폰에서 echoCancellation을 끄면 스피커로 나온 에이전트 음성이 마이크로 다시 들어가 사용자 발화로 처리됩니다. 에이전트가 자기 목소리에 반응해 말을 끊을 수 있으니 스피커폰을 쓰는 화면에서는 끄지 마세요.

콜백

startSession 옵션으로 콜백을 등록할 수 있습니다.

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-api-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 인스턴스를 돌려줍니다. 마이크 권한이 거부되거나 연결이 실패하면 에러를 throw합니다.

메서드

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-api-key>",
  textOnly: true,
  onMessage: (msg) => console.log(`${msg.source}: ${msg.text}`),
});

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

Text Only 세션은 마이크 권한을 요청하지 않습니다.
오디오 관련 API(getInputVolume 등)는 zero-value를 돌려줍니다.

Dynamic Variables와 Metadata

const conversation = 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 — 웹훅과 통화 기록에 포함됩니다.

연관 검색어

JavaScript SDK, JS SDK, @vox-ai/client, visitorId, Customer, Memory, 웹 연동, web integration, startSession, 바닐라 자바스크립트

​설치

​사용법

​세션 초기화

​세션 설정

​콜백

​반환값

​메서드

​endSession

​getId

​getMessages

​sendUserMessage

​setVolume

​setMicMuted

​getInputVolume / getOutputVolume

​getInputByteFrequencyData / getOutputByteFrequencyData

​changeInputDevice

​changeOutputDevice

​상태 조회

​Text Only 모드

​Dynamic Variables와 Metadata

설치

사용법

세션 초기화

세션 설정

콜백

반환값

메서드

endSession

getId

getMessages

sendUserMessage

setVolume

setMicMuted

getInputVolume / getOutputVolume

getInputByteFrequencyData / getOutputByteFrequencyData

changeInputDevice

changeOutputDevice

상태 조회

Text Only 모드

Dynamic Variables와 Metadata