useConvaiClient Hook

useConvaiClient 管理所有 Convai 连接逻辑、音频/视频管线和消息流。

配置

interface ConvaiConfig {
  apiKey: string;                    // 必需：您的 API 密钥
  characterId: string;                // 必需：角色 ID
  endUserId?: string;                 // 可选：用于记忆和分析
  url?: string;                       // 可选：自定义 API 端点
  enableVideo?: boolean;              // 启用视频/屏幕共享（默认：false）
  startWithVideoOn?: boolean;         // 启动时开启摄像头（默认：false）
  startWithAudioOn?: boolean;         // 启动时开启麦克风（默认：false）
  ttsEnabled?: boolean;               // 启用 TTS（默认：true）
  enableLipsync?: boolean;            // 启用 blendshape（默认：false）
  blendshapeConfig?: {
    format?: 'arkit' | 'mha';         // 形变格式（默认：'mha'）
  };
  actionConfig?: {                    // 可选：角色动作
    actions: string[];
    characters: Array<{ name: string; bio: string }>;
    objects: Array<{ name: string; description: string }>;
    currentAttentionObject?: string;
  };
}

返回值

const convaiClient = useConvaiClient(config);

State

convaiClient.state              // 连接 + 活动状态
convaiClient.connectionType     // 'audio' | 'video' | null
convaiClient.isBotReady         // 机器人已准备好接收消息
convaiClient.chatMessages       // 所有对话消息
convaiClient.userTranscription  // 实时语音转文本

连接方法

convaiClient.connect(config?)   
convaiClient.disconnect()
convaiClient.reconnect()
convaiClient.resetSession()

消息发送

convaiClient.sendUserTextMessage(text)
convaiClient.sendTriggerMessage(triggerName, message?)
convaiClient.updateTemplateKeys({ key: 'value' })
convaiClient.updateDynamicInfo({ text: 'context' })

控制

convaiClient.audioControls
convaiClient.videoControls
convaiClient.screenShareControls
convaiClient.toggleTts(enabled)

示例：手动连接

function App() {
  const convaiClient = useConvaiClient(); // 无初始配置

  const connect = () => convaiClient.connect({
    apiKey: '你的-api-key',
    characterId: 'your-character-id'
  });

  return <button onClick={connect}>连接</button>;
}