Omnia Voice SDK

Add voice AI capabilities to your web applications with our JavaScript SDK.

Platform Support

This SDK is designed for web browsers only. It uses WebRTC and browser APIs for real-time voice communication. For iOS/Android apps, you can embed a WebView or contact us for native SDK options.

Installation

npm install @omnia-voice/sdk

Quick Start

1. Initialize the SDK

import { OmniaSession } from '@omnia-voice/sdk';

const session = new OmniaSession({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.omnia-voice.com'
});

2. Join a Call

You can join a call using a pre-configured agent or with inline configuration:

// Use a pre-configured agent from your dashboard
await session.joinCall({
  agentId: 'your-agent-id'
});

3. Listen for Events

// Status changes: 'connecting', 'listening', 'speaking', 'thinking', 'disconnected'
session.addEventListener('status', () => {
  console.log('Status:', session.status);
});

// Transcripts (conversation history)
session.addEventListener('transcripts', () => {
  console.log('Transcripts:', session.transcripts);
});

4. Control the Call

// Mute/unmute microphone
session.toggleMicMute();

// Check mute status
console.log('Is muted:', session.isMicMuted);

// End the call
await session.leaveCall();

Client-Side Tools

// Register a tool before joining the call
session.registerTool('getWeather', async (params) => {
  const response = await fetch(`https://api.weather.com?city=${params.city}`);
  const data = await response.json();
  return `The weather in ${params.city} is ${data.temp}°F`;
});

// When using inline config, declare the tool schema
await session.joinCall({
  systemPrompt: 'You can check weather using the getWeather tool.',
  voice: 'Mark',
  language: 'en',
  selectedTools: [
    {
      temporaryTool: {
        modelToolName: 'getWeather',
        description: 'Get current weather for a city',
        dynamicParameters: [
          {
            name: 'city',
            location: 'PARAMETER_LOCATION_BODY',
            schema: {
              type: 'string',
              description: 'The city name'
            },
            required: true
          }
        ],
        client: {}  // Marks this as a client-side tool
      }
    }
  ]
});

API Reference

OmniaSession

The main class for managing voice sessions.

Constructor Options

Option	Type	Description
apiKey	string	Your Omnia API key
baseUrl	string	API base URL (default: https://api.omnia-voice.com)

Properties

Property	Type	Description
status	string	'disconnected' \| 'connecting' \| 'listening' \| 'thinking' \| 'speaking'
transcripts	array	Array of transcript objects with speaker, text, isFinal
isMicMuted	boolean	Whether the microphone is muted

Methods

Method	Description
joinCall(options)	Join a voice call with agent ID or inline config
leaveCall()	End the current call
toggleMicMute()	Toggle microphone mute state
registerTool(name, handler)	Register a client-side tool
addEventListener(event, callback)	Listen for 'status' or 'transcripts' events

joinCall Options

Agent ID Mode

Option	Type	Description
agentId	string	ID of a pre-configured agent from your dashboard

Inline Config Mode

Option	Type	Required	Description
systemPrompt	string	Yes	Instructions for the AI agent
voice	string	Yes	Voice name (e.g., 'Mark', 'Jessica')
language	string	Yes	Language code (e.g., 'en', 'es', 'fi')
selectedTools	array	No	Tool definitions for client-side tools

Complete Example

<!DOCTYPE html>
<html>
<head>
  <title>Omnia Voice Demo</title>
</head>
<body>
  <button id="startCall">Start Call</button>
  <button id="endCall" disabled>End Call</button>
  <div id="status">Ready</div>
  <div id="transcripts"></div>

  <script src="https://unpkg.com/@omnia-voice/sdk@0.2.0/dist/index.global.js"></script>
  <script>
    const session = new OmniaVoiceSDK.OmniaSession({
      apiKey: 'your-api-key',
      baseUrl: 'https://api.omnia-voice.com'
    });

    // Listen for status changes
    session.addEventListener('status', () => {
      document.getElementById('status').textContent = session.status;
    });

    // Listen for transcripts
    session.addEventListener('transcripts', () => {
      const html = session.transcripts
        .map(t => `<p><strong>${t.speaker}:</strong> ${t.text}</p>`)
        .join('');
      document.getElementById('transcripts').innerHTML = html;
    });

    // Start call button
    document.getElementById('startCall').onclick = async () => {
      await session.joinCall({ agentId: 'your-agent-id' });
      document.getElementById('startCall').disabled = true;
      document.getElementById('endCall').disabled = false;
    };

    // End call button
    document.getElementById('endCall').onclick = async () => {
      await session.leaveCall();
      document.getElementById('startCall').disabled = false;
      document.getElementById('endCall').disabled = true;
    };
  </script>
</body>
</html>

Troubleshooting

Microphone Permission Denied

The SDK requires microphone access. Make sure your page is served over HTTPS and the user has granted permission.

Connection Failed

Check that your API key is valid and has sufficient balance. Verify the baseUrl is correct.

Tools Not Being Called

When using inline config, make sure to include the tool definition in selectedTools. The tool must be registered with registerTool() before joining the call.