Configuration

createVoiceAgent(config) accepts a complete superset of the widget’s knobs. A bare { agentSlug } initializes identically to the widget — same noise filtering, audio defaults, and DeepFilter asset URLs.


import { createVoiceAgent } from "@oshara/voice-sdk";
 
const client = createVoiceAgent({
  agentSlug: "support-bot",
});

`VoiceAgentConfig`


interface VoiceAgentConfig {
  agentSlug: string;                 // required — the AICharacter.slug on the backend
  apiUrl?: string;                   // default "https://api.oshara.ai"
  apiKey?: string;                   // sk_… → sent as x-api-key (server/trusted)
  appearanceUrl?: string;            // override the appearance endpoint URL
  language?: string;                 // BCP-47 short code, default "en"
  fetchAppearanceOnInit?: boolean;   // auto-fetch appearance during init() (default true)
  disableAnalytics?: boolean;        // default false
  fetch?: typeof fetch;              // inject a fetch (Node <18 / testing)
 
  deepFilter?: {                     // DeepFilterNet3 asset overrides
    cdnUrl?: string;
    wasmUrl?: string;
    onnxUrl?: string;
    moduleUrl?: string;
  };
 
  audio?: Partial<AudioPrefs>;       // seed audio preferences (see below)
  persistAudioPrefs?: boolean;       // read/write prefs to localStorage (default true)
}

Fields

Field	Type	Default	Notes
`agentSlug`	`string`	—	Required. The character’s slug.
`apiUrl`	`string`	`https://api.oshara.ai`	Backend base URL.
`apiKey`	`string`	—	Secret key (`sk_…`), sent as `x-api-key`, bypassing origin gating. Server-side only — see Authentication.
`appearanceUrl`	`string`	—	Override the appearance endpoint entirely.
`language`	`string`	`"en"`	UI language; also changeable at runtime via `setLanguage`.
`fetchAppearanceOnInit`	`boolean`	`true`	If `false`, `init()` skips the appearance fetch (you supply your own UI strings).
`disableAnalytics`	`boolean`	`false`	Suppress engagement events.
`fetch`	`typeof fetch`	`globalThis.fetch`	Inject a fetch implementation for Node < 18 or tests.
`deepFilter`	`object`	widget defaults	Override DeepFilterNet3 module / WASM / ONNX URLs.
`audio`	`Partial<AudioPrefs>`	see below	Seed audio prefs; merged over defaults and stored prefs.
`persistAudioPrefs`	`boolean`	`true`	Persist per-agent audio prefs to `localStorage`.

UI-only options (openChat, inline, closeButtonHide) are not config — they live on mountVoiceUI and on <VoiceWidget>.

Audio preferences

audio seeds the initial audio settings. The precedence when the client resolves prefs is:


DEFAULT_AUDIO_PREFS  <  stored prefs (if persistAudioPrefs)  <  config.audio

The defaults match the widget exactly:


{
  noiseFilter: "deepfilter",   // "off" | "krisp" | "deepfilter"
  deepFilterStrength: 40,
  voiceIsolation: true,
  autoGainControl: false,
  echoCancellation: true,
  noiseSuppression: true,
  headphonesMode: true,
  outputVolume: 85,
  transcriptionEnabled: true,
  textInputEnabled: true,
  // micDeviceId / speakerDeviceId: system default
}

Override any subset:


createVoiceAgent({
  agentSlug: "support-bot",
  audio: { noiseFilter: "krisp", outputVolume: 70, headphonesMode: false },
  persistAudioPrefs: false, // don't touch localStorage
});

Change these later at runtime with updateAudioSettings.

DeepFilter assets

By default the SDK loads the same DeepFilterNet3 assets the widget uses. To self-host them (e.g. behind your own CDN):


createVoiceAgent({
  agentSlug: "support-bot",
  deepFilter: {
    moduleUrl: "https://cdn.acme.com/deepfilter/index.mjs",
    wasmUrl:   "https://cdn.acme.com/deepfilter/df_bg.wasm",
    onnxUrl:   "https://cdn.acme.com/deepfilter/DeepFilterNet3_onnx.tar.gz",
  },
});