{"id":15884,"library":"ultravox-client","title":"Ultravox Client SDK for Web","description":"The `ultravox-client` library provides a web client SDK for integrating Ultravox's real-time, speech-to-speech AI capabilities into web applications. Written in TypeScript, it offers an event-driven API for managing interactive voice sessions. The current stable version is 0.5.0, indicating it is still in active development with potential for API changes in future minor releases. It enables developers to join AI-powered calls, listen for session status changes, and receive real-time speech transcripts from both users and AI agents. Key differentiators include its focus on low-latency, real-time voice interaction and its comprehensive event model for managing session state and data flow within a web browser environment, abstracting away the underlying WebSocket complexities.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install ultravox-client","lang":"bash","label":"npm"},{"cmd":"yarn add ultravox-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add ultravox-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library is primarily designed for modern web environments and uses ES Modules. CommonJS `require` is not the intended way to import.","wrong":"const { UltravoxSession } = require('ultravox-client');","symbol":"UltravoxSession","correct":"import { UltravoxSession } from 'ultravox-client';"},{"note":"UltravoxSessionStatus is an enum used for session state; ensure it's imported as a named export.","wrong":"import UltravoxSessionStatus from 'ultravox-client';","symbol":"UltravoxSessionStatus","correct":"import { UltravoxSessionStatus } from 'ultravox-client';"},{"note":"For TypeScript projects, use `import type` when only importing the type definition for better tree-shaking and build performance.","symbol":"UltravoxSession (Type)","correct":"import type { UltravoxSession } from 'ultravox-client';"}],"quickstart":{"code":"import { UltravoxSession } from 'ultravox-client';\n\n// In a real application, replace this with a URL obtained securely from your backend\n// which generates it via the Ultravox API. Do NOT hardcode or expose API keys.\nconst ULTRAVOX_JOIN_URL = 'wss://your-call-join-url'; // Placeholder for demonstration\n\nconst session = new UltravoxSession();\n\nsession.addEventListener('status', (event) => {\n  console.log('Session status changed: ', session.status);\n  if (session.status === 'disconnected') {\n    console.log('Ultravox session disconnected. Attempting to reconnect if desired.');\n  } else if (session.status === 'listening') {\n    console.log('Ultravox is now listening for your voice input. Speak freely!');\n  } else if (session.status === 'speaking') {\n    console.log('Ultravox AI is responding...');\n  }\n});\n\nsession.addEventListener('transcripts', (event) => {\n  // `session.transcripts` is an array of all received transcripts.\n  // This event fires for both partial and final transcripts.\n  const currentTranscripts = session.transcripts;\n  console.log('Current transcripts: ', currentTranscripts);\n\n  // Example: Find and log the latest final transcript\n  const lastFinalTranscript = currentTranscripts.findLast(t => t.isFinal);\n  if (lastFinalTranscript) {\n    console.log(`[${lastFinalTranscript.speaker}]: ${lastFinalTranscript.text}`);\n  }\n});\n\nasync function startUltravoxSession() {\n  try {\n    console.log('Attempting to join Ultravox call at:', ULTRAVOX_JOIN_URL);\n    await session.joinCall(ULTRAVOX_JOIN_URL);\n    console.log('Successfully joined Ultravox call. Waiting for initial status...');\n  } catch (error) {\n    console.error(\"Failed to join call, ensure URL is valid and network is available:\", error);\n  }\n}\n\nstartUltravoxSession();\n\n// Example: To leave the call after some user interaction or timeout\n// setTimeout(() => {\n//   console.log('Leaving Ultravox call after a demonstration period...');\n//   session.leaveCall();\n// }, 60000); // Automatically leave after 60 seconds","lang":"javascript","description":"This quickstart initializes an `UltravoxSession`, sets up event listeners for session status changes and real-time transcript updates, and attempts to connect to an Ultravox AI call using a provided WebSocket URL. It demonstrates how to monitor the call's state, process incoming speech-to-text data, and manage the session lifecycle within a web application."},"warnings":[{"fix":"Refer to the official Ultravox documentation and changelog for specific breaking changes when upgrading to new minor versions. Consider using a version lock (`~0.x.y` instead of `^0.x.y`) in your `package.json` for stability.","message":"As the package is currently in an early development stage (version 0.5.0), the API is subject to breaking changes in minor versions. Developers should pin exact versions and review release notes carefully when upgrading.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Execute `pnpm publish --dry-run --git-checks=false` in the SDK's root directory. This command often triggers the necessary pre-publish scripts that generate the `version.js` file, resolving the build dependency.","message":"When developing or building the `ultravox-client` SDK itself, a build error 'Missing version.js file' might occur. This indicates an issue with the build tooling not generating the version file prior to compilation.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Implement a backend service that interacts with the Ultravox API to securely generate and provide the `joinCall` URL to your web client. Do not embed API keys directly in client-side code.","message":"The `UltravoxSession.joinCall()` method requires a WebSocket URL that must be generated by the Ultravox API (typically from a backend server). This URL is not static and cannot be created directly within the client-side application.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Navigate to the SDK's root directory and run `pnpm publish --dry-run --git-checks=false`. This command should trigger the necessary pre-publish hooks that generate `version.js`.","cause":"The build process for the Ultravox Client SDK failed to locate or generate the `version.js` file, which is required for package metadata.","error":"Error: Missing version.js file"},{"fix":"Verify that the `joinCall` URL passed to `session.joinCall()` is current, valid, and correctly generated by your backend using the Ultravox API. Ensure your server-side logic handles token expiry and renewal correctly.","cause":"The WebSocket server rejected the connection request, often due to an invalid or expired `joinCall` URL, or incorrect authentication/authorization.","error":"WebSocket connection failed: Error during WebSocket handshake: Unexpected response code: 403"},{"fix":"Ensure the URL passed to `session.joinCall()` is a properly formatted WebSocket URL, starting with `ws://` or `wss://`, and that it resolves to an accessible endpoint.","cause":"The URL provided to `session.joinCall()` is not a valid WebSocket (ws:// or wss://) URL format.","error":"TypeError: Failed to construct 'WebSocket': The URL 'invalid-url' is invalid."}],"ecosystem":"npm"}