Best Practices & Type Definitions

A summary of recommended patterns and the main TypeScript types for quick reference.

Best Practices

1. Check connection before sending messages

if (client.state.isConnected) {
  client.sendUserTextMessage('Hello');
}

2. Handle errors

try {
  await client.connect(config);
} catch (err) {
  console.error('Connection failed', err);
}

3. Unsubscribe from events when needed

const off = client.on('message', handler);
off();

4. Disconnect on cleanup

window.addEventListener('beforeunload', () => {
  client.disconnect();
});

5. Keep UI responsive with stateChange

client.on('stateChange', updateUI);

---

Key Types

interface ConvaiConfig {
  apiKey: string;
  characterId: string;
  endUserId?: string;
  enableVideo?: boolean;
  startWithVideoOn?: boolean;
  ttsEnabled?: boolean;
  actionConfig?: ActionConfig;
}

interface ConvaiClientState {
  isConnected: boolean;
  isConnecting: boolean;
  isListening: boolean;
  isThinking: boolean;
  isSpeaking: boolean;
  agentState: 'disconnected' | 'listening' | 'thinking' | 'speaking';
}

interface ChatMessage {
  id: string;
  type:
    | 'user-transcription'
    | 'bot-llm-text'
    | 'bot-emotion'
    | 'action'
    | 'behavior-tree';
  content: string;
  timestamp: number;
}