JavaScript SDK

npm install @omnia-voice/sdk

The SDK handles microphone capture, audio playback, transcripts, and client-side tools. It talks to /calls/create (saved agent) or /calls/inline (config in the request) and connects you to the returned WebSocket.

Basic use

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

const session = new OmniaSession({ apiKey: OMNIA_API_KEY });

session.addEventListener("status", () => console.log(session.status));
session.addEventListener("transcripts", () => {
  const latest = session.transcripts.at(-1);
  if (latest) render(latest);
});

const { callId } = await session.joinCall({ agentId: "agt_123" });

Where the API key goes

OmniaSession sends your API key directly to the Omnia API with X-API-Key. Constructed in a browser with a production key, that key is visible to anyone who opens devtools.For anything public-facing, run the SDK behind your own server: point baseUrl at an endpoint you control that injects the key and forwards to api.omnia-voice.com. The SDK ships a minimal proxy under proxy/ as a starting point.Using it directly in the browser is reasonable for internal tools, prototypes, and demos — just not with a key that can spend real credits.

string

required

Your API key.

string

default:"https://api.omnia-voice.com"

Point this at your own proxy to keep the key server-side.

boolean

default:"true"

Stream the user’s own speech as they talk, arriving with isFinal: false.

AudioContext

Supply your own, if you already manage one.

Joining a call

joinCall resolves to { callId } and accepts either shape:

await session.joinCall({
  agentId: "agt_123",
  metadata: { customerId: "c_9" },
});

await session.joinCall({
  systemPrompt: "You are a concise support agent for Northside Clinic.",
  voice: "Mark",
  language: "en",
  model: "llama",
  temperature: 0,
  firstSpeaker: "agent",
  recordingEnabled: true,
});

Inline needs no saved agent — useful when the persona is generated per user. See Inline calls.

Controlling the call

session.muteMic();            session.unmuteMic();
session.toggleMicMute();      // session.isMicMuted

session.muteSpeaker();        session.unmuteSpeaker();
session.toggleSpeakerMute();  // session.isSpeakerMuted

session.sendText("The customer is on the Pro plan.");
await session.leaveCall();

method

Inject text as though the user had spoken it. Pass deferResponse: true to add context without prompting an immediate reply — useful for feeding in facts mid-call.

method

Send a structured message. Must include a type, and the encoded payload must stay under 1024 bytes.

Client tools

session.registerTool("showForm", async (params) => {
  const result = await showMyForm(params);
  return result;                       // string, or { result, responseType }
});

// or several at once
session.registerTools({
  showForm: handleForm,
  highlightProduct: handleHighlight,
});

The SDK matches invocations to results for you — no invocation IDs to track. See Client tools.

Events

Event	Read from
`status`	`session.status`
`transcripts`	`session.transcripts`
`data_message`	The event itself — cancelable

React

import { OmniaVoiceProvider, useOmniaVoice, useTranscripts, useStatus,
         useMicrophone, useSpeaker } from "@omnia-voice/sdk/react";

function App() {
  return (
    <OmniaVoiceProvider config={{ apiKey: KEY }}>
      <CallPanel />
    </OmniaVoiceProvider>
  );
}

function CallPanel() {
  const { joinCall, leaveCall } = useOmniaVoice();
  const transcripts = useTranscripts();
  const status = useStatus();
  const { isMuted, toggle } = useMicrophone();
  useSpeaker();
  // …
}

Requirements

Microphone access needs a secure context — HTTPS or localhost. It will not work on a plain-HTTP staging domain.

Troubleshooting

Microphone permission denied

Once denied, the browser will not ask again — the user must clear it in site settings. Ask for permission on a click; requesting it on page load is denied far more often, because the user has no idea what it is for yet.

Connection failed

Confirm the agent is ACTIVE and the workspace has credits — an out-of-credit workspace fails at call creation with 402. WebSocket URLs are short-lived and single-use, so never cache one.

Tools are not firing

Usually the tool description, not the wiring — the model decides from that text alone. Also check the name passed to registerTool matches the tool’s modelToolName exactly.

No audio out

Browsers block autoplaying audio until the user interacts with the page. Start the call from a real click.

Inline calls

Configure an agent per call, with no saved record.

Raw WebSocket

Skip the SDK and speak the protocol.

Get started

Core concepts

Tools

Telephony

Apps & SDKs

Guides

Examples

Speech to text

Help

Basic use

Where the API key goes

Joining a call

Controlling the call

Client tools

Events

React

Requirements

Troubleshooting

Inline calls

Raw WebSocket

​Basic use

​Where the API key goes

​Joining a call

​Controlling the call

​Client tools

​Events

​React

​Requirements

​Troubleshooting

Inline calls

Raw WebSocket

Basic use

Where the API key goes

Joining a call

Controlling the call

Client tools

Events

React

Requirements

Troubleshooting