tavus-cvi-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tavus CVI React UI Components

Tavus CVI React UI组件

Pre-built React components for embedding CVI conversations.

用于嵌入CVI对话的预构建React组件。

Quick Setup (Vite)

快速开始（Vite）

bash

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install
npx @tavus/cvi-ui@latest init
npx @tavus/cvi-ui@latest add conversation

Creates:

src/components/cvi/components/
├── cvi-provider.tsx
└── conversation.tsx

Create

cvi-components.json

in project root:

json

{
  "tsx": true
}

bash

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install
npx @tavus/cvi-ui@latest init
npx @tavus/cvi-ui@latest add conversation

生成以下文件：

src/components/cvi/components/
├── cvi-provider.tsx
└── conversation.tsx

在项目根目录创建

cvi-components.json

文件：

json

{
  "tsx": true
}

Environment Variables

环境变量

.env

in project root:

VITE_TAVUS_API_KEY=your_api_key
VITE_REPLICA_ID=rfe12d8b9597
VITE_PERSONA_ID=pdced222244b

在项目根目录的

.env

文件中配置：

VITE_TAVUS_API_KEY=your_api_key
VITE_REPLICA_ID=rfe12d8b9597
VITE_PERSONA_ID=pdced222244b

Basic Implementation

基础实现

tsx

import { useState } from "react";
import { CVIProvider } from "./components/cvi/components/cvi-provider";
import { Conversation } from "./components/cvi/components/conversation";

export default function App() {
  const [url, setUrl] = useState<string | null>(null);

  const startConversation = async () => {
    const res = await fetch("https://tavusapi.com/v2/conversations", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": import.meta.env.VITE_TAVUS_API_KEY,
      },
      body: JSON.stringify({
        replica_id: import.meta.env.VITE_REPLICA_ID,
        persona_id: import.meta.env.VITE_PERSONA_ID,
      }),
    });
    const data = await res.json();
    setUrl(data.conversation_url);
  };

  return (
    <CVIProvider>
      {!url ? (
        <button onClick={startConversation}>Start</button>
      ) : (
        <Conversation 
          conversationUrl={url} 
          onLeave={() => setUrl(null)} 
        />
      )}
    </CVIProvider>
  );
}

tsx

import { useState } from "react";
import { CVIProvider } from "./components/cvi/components/cvi-provider";
import { Conversation } from "./components/cvi/components/conversation";

export default function App() {
  const [url, setUrl] = useState<string | null>(null);

  const startConversation = async () => {
    const res = await fetch("https://tavusapi.com/v2/conversations", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": import.meta.env.VITE_TAVUS_API_KEY,
      },
      body: JSON.stringify({
        replica_id: import.meta.env.VITE_REPLICA_ID,
        persona_id: import.meta.env.VITE_PERSONA_ID,
      }),
    });
    const data = await res.json();
    setUrl(data.conversation_url);
  };

  return (
    <CVIProvider>
      {!url ? (
        <button onClick={startConversation}>Start</button>
      ) : (
        <Conversation 
          conversationUrl={url} 
          onLeave={() => setUrl(null)} 
        />
      )}
    </CVIProvider>
  );
}

Component: CVIProvider

组件：CVIProvider

Wraps your app, provides CVI context:

tsx

import { CVIProvider } from "./components/cvi/components/cvi-provider";

function App() {
  return (
    <CVIProvider>
      {/* Your app */}
    </CVIProvider>
  );
}

包裹你的应用，提供CVI上下文：

tsx

import { CVIProvider } from "./components/cvi/components/cvi-provider";

function App() {
  return (
    <CVIProvider>
      {/* Your app */}
    </CVIProvider>
  );
}

Component: Conversation

组件：Conversation

The main video conversation UI:

tsx

<Conversation
  conversationUrl={url}
  onLeave={() => setUrl(null)}
/>

Required: Parent container must have defined dimensions.

tsx

<div style={{ width: "100%", height: "600px" }}>
  <Conversation conversationUrl={url} onLeave={handleLeave} />
</div>

核心视频对话UI组件：

tsx

<Conversation
  conversationUrl={url}
  onLeave={() => setUrl(null)}
/>

必填要求：父容器必须设置明确的尺寸。

tsx

<div style={{ width: "100%", height: "600px" }}>
  <Conversation conversationUrl={url} onLeave={handleLeave} />
</div>

Hooks

useAppMessage

Listen for CVI events:

tsx

import { useAppMessage } from "./components/cvi/hooks/use-app-message";

function MyComponent() {
  useAppMessage((event) => {
    if (event.event_type === "conversation.utterance") {
      console.log("Said:", event.properties.content);
    }
  });
  
  return <div>...</div>;
}

监听CVI事件：

tsx

import { useAppMessage } from "./components/cvi/hooks/use-app-message";

function MyComponent() {
  useAppMessage((event) => {
    if (event.event_type === "conversation.utterance") {
      console.log("Said:", event.properties.content);
    }
  });
  
  return <div>...</div>;
}

useSendAppMessage

Send interactions to CVI:

tsx

import { useSendAppMessage } from "./components/cvi/hooks/use-send-app-message";

function Controls() {
  const send = useSendAppMessage();
  
  const interrupt = () => {
    send({
      message_type: "conversation",
      event_type: "conversation.interrupt",
      conversation_id: "xxx"
    });
  };
  
  return <button onClick={interrupt}>Stop</button>;
}

向CVI发送交互指令：

tsx

import { useSendAppMessage } from "./components/cvi/hooks/use-send-app-message";

function Controls() {
  const send = useSendAppMessage();
  
  const interrupt = () => {
    send({
      message_type: "conversation",
      event_type: "conversation.interrupt",
      conversation_id: "xxx"
    });
  };
  
  return <button onClick={interrupt}>Stop</button>;
}

Alternative: iframe Embedding

替代方案：iframe嵌入

For non-React or quick integration:

html

<iframe
  src="CONVERSATION_URL"
  allow="camera; microphone; display-capture"
  style="width: 100%; height: 600px; border: none;"
></iframe>

适用于非React项目或快速集成场景：

html

<iframe
  src="CONVERSATION_URL"
  allow="camera; microphone; display-capture"
  style="width: 100%; height: 600px; border: none;"
></iframe>

Server-Side API Calls (Recommended)

服务端API调用（推荐）

Keep API key on server:

typescript

// pages/api/conversation.ts (Next.js)
export default async function handler(req, res) {
  const response = await fetch("https://tavusapi.com/v2/conversations", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.TAVUS_API_KEY,
    },
    body: JSON.stringify({
      replica_id: process.env.REPLICA_ID,
      persona_id: process.env.PERSONA_ID,
    }),
  });
  
  const data = await response.json();
  res.json({ conversation_url: data.conversation_url });
}

Client calls your API:

tsx

const res = await fetch("/api/conversation", { method: "POST" });
const { conversation_url } = await res.json();

将API密钥保存在服务端：

typescript

// pages/api/conversation.ts (Next.js)
export default async function handler(req, res) {
  const response = await fetch("https://tavusapi.com/v2/conversations", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.TAVUS_API_KEY,
    },
    body: JSON.stringify({
      replica_id: process.env.REPLICA_ID,
      persona_id: process.env.PERSONA_ID,
    }),
  });
  
  const data = await response.json();
  res.json({ conversation_url: data.conversation_url });
}

客户端调用你的API：

tsx

const res = await fetch("/api/conversation", { method: "POST" });
const { conversation_url } = await res.json();

Styling the Conversation

对话组件样式定制

Wrap in styled container:

tsx

<div style={{
  width: "100%",
  maxWidth: "900px",
  margin: "0 auto",
  borderRadius: "12px",
  overflow: "hidden",
  boxShadow: "0 4px 20px rgba(0,0,0,0.15)",
}}>
  <Conversation conversationUrl={url} onLeave={onLeave} />
</div>

将组件包裹在样式容器中：

tsx

<div style={{
  width: "100%",
  maxWidth: "900px",
  margin: "0 auto",
  borderRadius: "12px",
  overflow: "hidden",
  boxShadow: "0 4px 20px rgba(0,0,0,0.15)",
}}>
  <Conversation conversationUrl={url} onLeave={onLeave} />
</div>

HairCheck Component

HairCheck组件

Pre-call device check:

bash

npx @tavus/cvi-ui@latest add haircheck

tsx

import { HairCheck } from "./components/cvi/components/haircheck";

<HairCheck onComplete={() => setShowConversation(true)} />

通话前设备检查组件：

bash

npx @tavus/cvi-ui@latest add haircheck

tsx

import { HairCheck } from "./components/cvi/components/haircheck";

<HairCheck onComplete={() => setShowConversation(true)} />

tavus-cvi-ui

Original

Translation

Tavus CVI React UI Components

Tavus CVI React UI组件

Quick Setup (Vite)

快速开始（Vite）

Environment Variables

环境变量

Basic Implementation

基础实现

Component: CVIProvider

组件：CVIProvider

Component: Conversation

组件：Conversation

Hooks

Hooks

useAppMessage

useAppMessage

useSendAppMessage

useSendAppMessage

Alternative: iframe Embedding

替代方案：iframe嵌入

Server-Side API Calls (Recommended)

服务端API调用（推荐）

Styling the Conversation

对话组件样式定制

HairCheck Component

HairCheck组件

Example Projects

示例项目