​
How configuration works

The widget reads its settings from two places, checked in order:
  1. data-* attributes on the <script> tag
  2. 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

AttributeWindow globalTypeDefaultDescription
data-agentVOICE_AGENT_SLUGstring—Required. The character slug to load (e.g. support-bot).
data-api-urlVOICE_API_URLstringhttps://api.oshara.aiBase URL for the Oshara backend. Override for self-hosted installs.
data-appearance-urlVOICE_APPEARANCE_URLstringauto-derivedOverride the URL from which appearance JSON is fetched. Defaults to {apiUrl}/api/agents/{slug}/appearance/.
data-open-chatVOICE_OPEN_CHATbooleanfalseAuto-expand the voice panel on page load.
data-deepfilter-cdnVOICE_DEEPFILTER_CDNstringhttps://cdn.mezon.aiBase CDN for DeepFilterNet3 model files.
data-deepfilter-wasm-urlVOICE_DEEPFILTER_WASM_URLstring{cdn}/df_bg.wasmDirect URL to the DeepFilterNet3 WASM binary. Overrides CDN derivation.
data-deepfilter-onnx-urlVOICE_DEEPFILTER_ONNX_URLstring{cdn}/DeepFilterNet3_onnx.tar.gzDirect URL to the ONNX model archive.
data-deepfilter-module-urlVOICE_DEEPFILTER_MODULE_URLstringhttps://esm.sh/mezonai-deepfilterESM 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.

​
Destroying and re-initialising the widget

// 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.