Oshara Docs

How configuration works

The widget reads its settings from two places, checked in order:

data-* attributes on the <script> tag
window.VOICE_* globals set before the script loads

data-* attributes take precedence. Use window globals when a tag manager or bundler makes data-* attributes awkward.

Attributes reference

Attribute	Window global	Type	Default	Description
`data-agent`	`VOICE_AGENT_SLUG`	string	—	Required. The character slug to load (e.g. `support-bot`).
`data-api-url`	`VOICE_API_URL`	string	`https://api.oshara.ai`	Base URL for the Oshara backend. Override for self-hosted installs.
`data-appearance-url`	`VOICE_APPEARANCE_URL`	string	auto-derived	Override the URL from which appearance JSON is fetched. Defaults to `{apiUrl}/api/agents/{slug}/appearance/`.
`data-open-chat`	`VOICE_OPEN_CHAT`	boolean	`false`	Auto-expand the voice panel on page load.
`data-deepfilter-cdn`	`VOICE_DEEPFILTER_CDN`	string	`https://cdn.mezon.ai`	Base CDN for DeepFilterNet3 model files.
`data-deepfilter-wasm-url`	`VOICE_DEEPFILTER_WASM_URL`	string	`{cdn}/df_bg.wasm`	Direct URL to the DeepFilterNet3 WASM binary. Overrides CDN derivation.
`data-deepfilter-onnx-url`	`VOICE_DEEPFILTER_ONNX_URL`	string	`{cdn}/DeepFilterNet3_onnx.tar.gz`	Direct URL to the ONNX model archive.
`data-deepfilter-module-url`	`VOICE_DEEPFILTER_MODULE_URL`	string	`https://esm.sh/mezonai-deepfilter`	ESM module URL for the DeepFilterNet3 JS wrapper.

Minimal example


<script
  src="https://api.oshara.ai/widget.js"
  data-agent="support-bot">
</script>

Self-hosting DeepFilterNet3 models

If you want noise-cancellation models to load from your own CDN (e.g. for CSP compliance), override the three model URLs:


<script
  src="https://api.oshara.ai/widget.js"
  data-agent="support-bot"
  data-deepfilter-wasm-url="https://cdn.yoursite.com/df_bg.wasm"
  data-deepfilter-onnx-url="https://cdn.yoursite.com/DeepFilterNet3_onnx.tar.gz"
  data-deepfilter-module-url="https://cdn.yoursite.com/deepfilternet3.esm.js">
</script>

Download the files from cdn.mezon.ai and host them yourself.

Using window globals


<script>
  window.VOICE_AGENT_SLUG  = "support-bot";
  window.VOICE_API_URL     = "https://api.oshara.ai";
  window.VOICE_OPEN_CHAT   = true;
</script>
<script src="https://api.oshara.ai/widget.js" async></script>

Set all globals before the widget script executes. With async, that means setting them synchronously before the <script async> tag.


// Tear down the current instance (removes DOM, disconnects audio)
window.__OsharaVoiceWidget?.destroy();
 
// Update config
window.VOICE_AGENT_SLUG = "new-bot";
 
// Re-load the script — or call the init function if you imported it as a module

Notes

The data-agent slug is the only required attribute. All others have sensible defaults.
Boolean attributes are true when the attribute is present or when the value is the string "true".
Appearance (branding, colors, forms) is controlled server-side via the character’s appearance config, not via data-* attributes. See Appearance.