Ultravox Client SDK for Web

Common errors

• Error: Missing version.js file

  cause The build process for the Ultravox Client SDK failed to locate or generate the `version.js` file, which is required for package metadata.
  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`.

• WebSocket connection failed: Error during WebSocket handshake: Unexpected response code: 403

  cause The WebSocket server rejected the connection request, often due to an invalid or expired `joinCall` URL, or incorrect authentication/authorization.
  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.

• TypeError: Failed to construct 'WebSocket': The URL 'invalid-url' is invalid.

  cause The URL provided to `session.joinCall()` is not a valid WebSocket (ws:// or wss://) URL format.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install ultravox-client npm
• yarn add ultravox-client yarn
• pnpm add ultravox-client pnpm

Imports

• UltravoxSession
  wrong:

  const { UltravoxSession } = require('ultravox-client');

  correct:

  import { UltravoxSession } from 'ultravox-client';

  This library is primarily designed for modern web environments and uses ES Modules. CommonJS `require` is not the intended way to import.
• UltravoxSessionStatus
  wrong:

  import UltravoxSessionStatus from 'ultravox-client';

  correct:

  import { UltravoxSessionStatus } from 'ultravox-client';

  UltravoxSessionStatus is an enum used for session state; ensure it's imported as a named export.
• UltravoxSession (Type)

  import type { UltravoxSession } from 'ultravox-client';

  For TypeScript projects, use `import type` when only importing the type definition for better tree-shaking and build performance.

Quickstart

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.

import { UltravoxSession } from 'ultravox-client';

// In a real application, replace this with a URL obtained securely from your backend
// which generates it via the Ultravox API. Do NOT hardcode or expose API keys.
const ULTRAVOX_JOIN_URL = 'wss://your-call-join-url'; // Placeholder for demonstration

const session = new UltravoxSession();

session.addEventListener('status', (event) => {
  console.log('Session status changed: ', session.status);
  if (session.status === 'disconnected') {
    console.log('Ultravox session disconnected. Attempting to reconnect if desired.');
  } else if (session.status === 'listening') {
    console.log('Ultravox is now listening for your voice input. Speak freely!');
  } else if (session.status === 'speaking') {
    console.log('Ultravox AI is responding...');
  }
});

session.addEventListener('transcripts', (event) => {
  // `session.transcripts` is an array of all received transcripts.
  // This event fires for both partial and final transcripts.
  const currentTranscripts = session.transcripts;
  console.log('Current transcripts: ', currentTranscripts);

  // Example: Find and log the latest final transcript
  const lastFinalTranscript = currentTranscripts.findLast(t => t.isFinal);
  if (lastFinalTranscript) {
    console.log(`[${lastFinalTranscript.speaker}]: ${lastFinalTranscript.text}`);
  }
});

async function startUltravoxSession() {
  try {
    console.log('Attempting to join Ultravox call at:', ULTRAVOX_JOIN_URL);
    await session.joinCall(ULTRAVOX_JOIN_URL);
    console.log('Successfully joined Ultravox call. Waiting for initial status...');
  } catch (error) {
    console.error("Failed to join call, ensure URL is valid and network is available:", error);
  }
}

startUltravoxSession();

// Example: To leave the call after some user interaction or timeout
// setTimeout(() => {
//   console.log('Leaving Ultravox call after a demonstration period...');
//   session.leaveCall();
// }, 60000); // Automatically leave after 60 seconds