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

configRef?​

optional configRef: string

Defined in: types/index.ts:191

Optional reference name to load the entire configuration from pug. When provided, pug will resolve this reference and apply the stored config. This is used for deployed apps that load config at runtime.

When configRef is set, the prompt, utilities, voiceProfile, and safetyPolicy fields are ignored as they will be loaded from the reference.

Example​

const manager = new ConversationManager({
  apiUrl: 'https://pug.stg.uglabs.app/api/',
  apiKey: 'your-api-key',
  federatedId: 'user-123',
  configRef: 'char_abc123_v2',  // Load full config from this reference
  hooks: { ... },
})

prompt?​

optional prompt: string

Defined in: types/index.ts:195

The system prompt that defines the assistant's behavior. This field is optional when configRef is provided.

context?​

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

Defined in: types/index.ts:197

Optional Context variables that can be used in the prompt template

utilities?​

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

Defined in: types/index.ts:211

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:213

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

hooks​

hooks: object

Defined in: types/index.ts:218

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:275

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:279

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:283

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:285

Optional Custom logger implementation

recordingConfig?​

optional recordingConfig: AudioRecordingConfig

Defined in: types/index.ts:287

Optional Audio recording configuration

languageCode?​

optional languageCode: string

Defined in: types/index.ts:293

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:302

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:314

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:323

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