Configuration

Customize the widget appearance and behavior.

Init Options#

Option	Default	Description
agentId	required*	Your agent's unique ID. *For humans-only widgets, `channelId` alone is enough.
channelId	—	ID of the widget channel. Selects which widget's settings (styling, outbound tooltips/banners) apply when one agent powers several widgets, and is the only identifier for humans-only widgets. At least one of `agentId` / `channelId` is required.
position	bottom-right	`bottom-right` or `bottom-left`
primaryColor	#3B82F6	Brand color for the widget button and header
title	Support	Header title text
greeting	auto	Welcome message (loaded from dashboard settings by default)
language	page	Widget language as a BCP-47 code (`de`, `pt-BR`). Sets the chrome, the greeting and the quick questions. When omitted the widget follows the page's `<html lang>`: a page whose `lang` is anything but `en` now starts in that language, whatever the visitor's browser says. `<html lang="en">` alone is treated as a template default and ignored: the visitor keeps the previous behaviour (remembered choice, then browser language). Pass `'browser'` to ignore `<html lang>` entirely and restore the browser-only behaviour. Change it at runtime with `Respondo.setLanguage('fr')` — useful for in-app language switchers that don't reload the page.
placeholder	—	Custom input placeholder text
quickQuestions	—	Array of suggested questions shown before first message
logoUrl	—	URL of your logo shown in widget header
avatarUrl	—	URL of AI agent avatar shown next to messages
identity	—	Pre-set user identity at init time (same fields as `identify()`)
localStorageKey	—	localStorage key to auto-read `userId` from (for GTM / no-code setups)
chatSize	default	`compact`, `default`, or `large` — chat window dimensions
launcherSize	default	`small`, `default`, or `large` — launcher button size
offsetBottom	20	Distance from bottom edge (px)
offsetSide	20	Distance from left/right edge (px)
borderRadius	20	Chat window border radius (px)
zIndex	999999	CSS z-index for the widget container
customCSS	—	Custom CSS injected into widget Shadow DOM for advanced styling
testMode	false	Mark conversations as test (hidden from main views)

Full Configuration#

Full Configurationjavascript

Respondo.init({
  agentId: 'YOUR_AGENT_ID',
  channelId: 'YOUR_CHANNEL_ID',
  position: 'bottom-right',        // 'bottom-right' | 'bottom-left'
  primaryColor: '#2563eb',
  language: 'de',                  // BCP-47; default: <html lang> (a bare en is ignored), 'browser' ignores it
  title: 'Help Center',
  greeting: 'How can we help?',
  placeholder: 'Ask anything...',
  logoUrl: 'https://yoursite.com/logo.png',
  avatarUrl: 'https://yoursite.com/avatar.png',
  quickQuestions: [
    'How do I get started?',
    'What are the pricing plans?',
    'How do I contact support?'
  ],
  testMode: false,
  localStorageKey: 'myapp_user_id', // auto-read userId from localStorage (GTM / no-code)
  chatSize: 'default',              // 'compact' | 'default' | 'large'
  offsetBottom: 20,                 // distance from bottom (px)
  identity: {                      // optional: set at init if user is already known
    email: 'user@example.com',
    name: 'John Doe',
    userId: 'usr_123',
    properties: {                  // custom contact properties
      account_type: 'enterprise',
      region: 'eu-west'
    }
  }
});

Most settings (color, logo, greeting, quick questions) are managed from the Channels dashboard. The widget fetches these at load time — you only need the agentId/channelId pair from the embed code.