Skip to Content
DocumentationWidgetAppearance

Overview

When the widget boots it fetches appearance configuration from:

GET /api/agents/{slug}/appearance/

You configure this through the dashboard under Characters → [your character] → Widget Appearance. The widget merges your overrides onto the defaults shown in the tables below.

Full example

{
  "name": "Nova",
  "subtitle": "Your AI assistant",
  "logo_url": "https://cdn.yoursite.com/nova-avatar.png",
  "fab_label": "Ask Nova",
  "fab_sublabel": "AI assistant",
  "start_button_text": "Start conversation",
  "powered_by_text": "Powered by Oshara",
  "powered_by_url": "https://oshara.ai",
 
  "theme": {
    "primary_color": "#6366F1",
    "accent_color": "#22D3EE",
    "background_color": "#FFFFFF",
    "text_color": "#0F172A",
    "user_bubble_color": "#6366F1",
    "user_bubble_text_color": "#FFFFFF",
    "agent_bubble_color": "#F1F5F9",
    "agent_bubble_text_color": "#0F172A"
  },
 
  "dimensions": {
    "fab_size": 64,
    "panel_width": 380,
    "panel_height": 620,
    "border_radius": 24
  },
 
  "layout": {
    "position": "bottom-right",
    "font_family": "Inter, sans-serif"
  },
 
  "labels": {
    "idle": "Idle",
    "connecting": "Connecting…",
    "listening": "Listening",
    "speaking": "Speaking…",
    "muted": "Microphone muted",
    "call_ended": "Call ended",
    "transcript_placeholder": "Your conversation will appear here",
    "language_label": "Language"
  },
 
  "languages": [
    { "code": "en", "label": "English", "native_label": "English" },
    { "code": "ne", "label": "Nepali", "native_label": "नेपाली" }
  ],
  "default_language": "en",
 
  "max_call_seconds": 0,
  "terms_url": "https://yoursite.com/terms",
  "terms_label": "Terms & Conditions",
  "consent_text": "By starting the call you agree to our",
  "show_audio_settings": true,
 
  "forms": []
}

Top-level fields

FieldTypeDefaultDescription
namestring"Voice Assistant"Display name shown in the panel header.
subtitlestring""Subtitle line below the name.
logo_urlstring""URL for the agent avatar / logo image.
fab_labelstring""Text on the floating action button. Empty = icon only.
fab_sublabelstring""Secondary text below the FAB label.
start_button_textstring"Start Call"Label on the call-start button.
powered_by_textstring"Powered by Oshara"Attribution text shown at the bottom of the panel.
powered_by_urlstring"https://oshara.ai"Link target for the attribution text.
max_call_secondsnumber0Hard call time limit in seconds. 0 = no limit.
terms_urlstring""URL to your Terms & Conditions page. Empty = consent step skipped.
terms_labelstring"Terms & Conditions"Link text for the T&C URL.
consent_textstring"By starting the call you agree to our"Text shown before the T&C link.
show_audio_settingsbooleantrueShow the mic/speaker/noise-cancel settings drawer.
default_languagestring"en"Language pre-selected in the language picker.

theme object

FieldTypeDefaultDescription
primary_colorhex string"#6366F1"Primary brand color — buttons, FAB background, accents.
accent_colorhex string"#22D3EE"Secondary accent color — loading rings, highlights.
background_colorhex string"#FFFFFF"Panel background.
text_colorhex string"#0F172A"Primary text color.
user_bubble_colorhex string"#6366F1"Background of the user’s transcript bubbles.
user_bubble_text_colorhex string"#FFFFFF"Text color inside user bubbles.
agent_bubble_colorhex string"#F1F5F9"Background of agent transcript bubbles.
agent_bubble_text_colorhex string"#0F172A"Text color inside agent bubbles.

dimensions object

FieldTypeDefaultDescription
fab_sizenumber (px)64Diameter of the floating action button.
panel_widthnumber (px)380Width of the voice panel.
panel_heightnumber (px)620Height of the voice panel.
border_radiusnumber (px)24Corner radius applied to the panel and FAB.

layout object

FieldTypeDefaultDescription
position"bottom-right" | "bottom-left" | "top-right" | "top-left""bottom-right"Screen corner where the FAB and panel are anchored.
font_familystring""CSS font-family stack applied to the panel (e.g. "Inter, sans-serif"). Empty = inherit page font.

labels object

All labels are optional. Any omitted field falls back to its English default.

FieldDefault
idle"Idle"
connecting"Connecting…"
listening"Listening"
speaking"Speaking…"
muted"Microphone muted"
call_ended"Call ended"
transcript_placeholder"Your conversation will appear here"
language_label"Language"

languages array

Populates the language picker shown in the panel. Each entry:

{ "code": "en", "label": "English", "native_label": "English" }
FieldDescription
codeBCP-47 language code passed to STT/TTS (e.g. "en", "ne", "es").
labelEnglish name displayed to developers / admins.
native_labelName in the language’s own script — shown in the picker.

forms array

See Forms for the full schema. Forms defined here are automatically offered to the agent as callable tools — the agent can open, pre-fill, and submit them during the call.

Dark mode example

{
  "theme": {
    "primary_color": "#818CF8",
    "accent_color": "#22D3EE",
    "background_color": "#0F172A",
    "text_color": "#F1F5F9",
    "user_bubble_color": "#4F46E5",
    "user_bubble_text_color": "#FFFFFF",
    "agent_bubble_color": "#1E293B",
    "agent_bubble_text_color": "#E2E8F0"
  }
}
Last updated on
ConfigurationAudio Settings