Skip to main content

ConversationConfig

ug-js-sdk

ug-js-sdk / ConversationConfig

Interface: ConversationConfig

Defined in: types/index.ts:162

Configuration for the ConversationManager.

Example​

const config: ConversationConfig = {
  apiUrl: 'wss://pug.stg.uglabs.app',
  apiKey: 'your-api-key',
  federatedId: 'user-id',
  prompt: 'You are a helpful assistant.',
  hooks: {
    onStateChange: (state) => console.log('State:', state),
    onTextMessage: (event) => console.log('Text:', event.text),
  },
  // To use utilities, define them here AND add their names to onInputUtilities/onOutputUtilities
  utilities: {
    my_classifier: { type: 'classify', classification_question: '...', answers: ['a', 'b'] }
  },
  onInputUtilities: ['my_classifier'], // Runs before prompt (blocking)
}

Properties​

apiUrl​

apiUrl: string

Defined in: types/index.ts:164

WebSocket API URL for the conversation service

apiKey​

apiKey: string

Defined in: types/index.ts:169

API key for authentication - you can use your own key and then you don't need to set federatedId or use here a service account key + federated id

federatedId​

federatedId: string

Defined in: types/index.ts:171

Federated user identifier for session tracking

prompt​

prompt: string

Defined in: types/index.ts:173

The system prompt that defines the assistant's behavior

context?​

optional context: Record<string, string | number | boolean>

Defined in: types/index.ts:175

Optional Context variables that can be used in the prompt template

utilities?​

optional utilities: Record<string, AnyUtility | Reference | null>

Defined in: types/index.ts:189

Optional Utility definitions (classifiers, extractors, etc.).

Important: Defining utilities here alone does not activate them. You must also add the utility name to one of:

  • onInputUtilities - runs before prompt (blocking, adds latency)
  • onInputNonBlockingUtilities - runs on input (non-blocking, results not in prompt context)
  • onOutputUtilities - runs after assistant output

See​

  • onInputUtilities
  • onInputNonBlockingUtilities
  • onOutputUtilities

voiceProfile?​

optional voiceProfile: VoiceProfile

Defined in: types/index.ts:191

Optional Voice synthesis configuration (voice ID, speed, stability, etc.)

hooks​

hooks: object

Defined in: types/index.ts:196

Event hooks for receiving conversation events. All hooks are optional and called when the corresponding event occurs.

onDataMessage()?​

optional onDataMessage: (message) => void

Optional Called when utility data is received from the server. Use this to receive results from utilities like classifiers or extractors.

Parameters​
message​

DataEvent

Returns​

void

onTextMessage()?​

optional onTextMessage: (event) => void

Optional Called when text content is received from the assistant. Useful for displaying streaming text responses.

Parameters​
event​

TextEvent

Returns​

void

onStringMessage()?​

optional onStringMessage(message): void

Optional Called when a string message is received (e.g., from utilities).

Parameters​
message​

StringMessage

Returns​

void

onStateChange()?​

optional onStateChange: (state) => void

Optional Called when the conversation state changes. States include: 'idle', 'listening', 'userSpeaking', 'waiting', 'playing', etc.

Parameters​
state​

ConversationState

Returns​

void

onSubtitleHighlight()?​

optional onSubtitleHighlight: (event) => void

Optional Called when subtitle word highlighting changes during playback. Use this for karaoke-style subtitle highlighting.

Parameters​
event​

WordHighlightEvent

Returns​

void

onSubtitleChange()?​

optional onSubtitleChange: (subtitle) => void

Optional Called when subtitle text changes (new sentence/phrase).

Parameters​
subtitle​

SubtitleChangeEvent

Returns​

void

onImageChange()?​

optional onImageChange: (event) => void

Optional Called when the displayed image changes.

Parameters​
event​

ImageChangeEvent

Returns​

void

onNetworkStatusChange()?​

optional onNetworkStatusChange: (isReady) => void

Optional Called when network connection status changes.

Parameters​
isReady​

boolean

true when connected, false when disconnected

Returns​

void

onError()?​

optional onError: (error) => void

Optional Called when an error occurs. Error types include: 'mic_denied', 'network_timeout', 'network_error', 'server_error', 'decode_error'

Parameters​
error​

ConversationError

Returns​

void

onAvatarAnimationChanged()?​

optional onAvatarAnimationChanged: (payload) => void

Optional Called when avatar animation changes.

Parameters​
payload​
name​

string

layer​

number

loop​

boolean

Returns​

void

onSafetyEvent()?​

optional onSafetyEvent: (event) => void

Optional Called when a safety policy event is triggered by the server. This indicates the conversation triggered a safety policy violation.

Parameters​
event​

SafetyEvent

Returns​

void

capabilities?​

optional capabilities: PlaybackCapabilities

Defined in: types/index.ts:253

Optional Playback capabilities (audio, viseme, subtitles, avatar) Here for example if you use a text only experience you can disable audio to make the conversation faster

safetyPolicy?​

optional safetyPolicy: string

Defined in: types/index.ts:257

Optional Safety policy identifier to apply content filtering. If nothing applied - the default will be used

inputCapabilities?​

optional inputCapabilities: InputCapabilities

Defined in: types/index.ts:261

Optional Input capabilities (audio, text) If you only use text chat - then you can set audio to false

logger?​

optional logger: ILogger

Defined in: types/index.ts:263

Optional Custom logger implementation

recordingConfig?​

optional recordingConfig: AudioRecordingConfig

Defined in: types/index.ts:265

Optional Audio recording configuration

languageCode?​

optional languageCode: string

Defined in: types/index.ts:271

Optional language code for speech-to-text transcription. Use BCP-47 language codes like "en", "he", "es", etc. This helps the transcription service recognize the spoken language.

onInputNonBlockingUtilities?​

optional onInputNonBlockingUtilities: string[]

Defined in: types/index.ts:280

Optional Utility names to call when user input is available (non-blocking).

Unlike onInputUtilities, these run in the background and their outputs will NOT be available in the prompt context. Use for fire-and-forget operations.

See​

utilities - Define the utility here first

onInputUtilities?​

optional onInputUtilities: string[]

Defined in: types/index.ts:292

Optional Utility names to call when user input is available (blocking).

Evaluation happens BEFORE the prompt is rendered, so utility outputs can be used in the prompt context.

Warning: Use with caution as this delays the assistant response and everything that follows (audio output, output utilities, etc.).

See​

utilities - Define the utility here first

onOutputUtilities?​

optional onOutputUtilities: string[]

Defined in: types/index.ts:301

Optional Utility names to call when assistant output is available.

These utilities run after the assistant generates a response. This is the preferred way to run utilities and will not block audio

See​

utilities - Define the utility here first