CVI App Quickstart

Put a Tavus CVI conversation in your web app with @tavus/embed. No backend and no API key in the browser.

Use this page when you are putting a Tavus conversation in your own web app. If you only want to create a PAL and join your first conversation from a link, use API Conversation Quickstart.

This guide takes a new web app from an empty project to a working Tavus conversation with @tavus/embed. The embed creates the conversation, runs the call, and ends it when the visitor leaves, so there is no backend route to write and no API key in your app.

The path is:

1. Create a PAL.
2. Create an embed deployment for that PAL.
3. Add <tavus-embed deployment-id="..."> to your app.

Your API key is used once, from your terminal, to create the PAL and the deployment. The app only needs the deployment ID, which is safe to expose.

Build it with a coding agent

If your coding agent supports MCP, as Cursor, Claude Code and Codex do, connect the Tavus MCP server and let the agent do every step on this page.

1. Add the server

   For Claude Code:

   claude mcp add -s user --transport http tavus https://mcp.tavus.io/mcp
   

   For Codex:

   codex mcp add tavus --url https://mcp.tavus.io/mcp
   

   Sign in once in the browser when the client asks. Other clients are on the MCP server page.

2. Ask for the app

   For example: “Create a PAL that answers questions about our product and put it in an embed on the home page of this app.” The agent builds the PAL, asks where the site is hosted and how much use to allow, creates the deployment once you confirm, and writes the <tavus-embed> integration in your stack.

See Build with a coding agent for the full flow. To do it by hand, follow the steps below.

Prerequisites

• A Tavus API key from the PAL Maker, for the two setup requests below.
• Node.js 20+ for the React example.

Set the key in your terminal for the requests in steps 1 and 2:

export TAVUS_API_KEY="<your_api_key>"

1. Create a PAL

A deployment needs a PAL you own; stock PALs cannot back one. Create a PAL on the stock Anna face (rc9cff32ceba):

curl --request POST \
  --url https://tavusapi.com/v2/pals \
  --header "Content-Type: application/json" \
  --header "x-api-key: $TAVUS_API_KEY" \
  --data '{
    "pal_name": "Product Guide",
    "system_prompt": "You are a friendly product guide. Answer questions clearly and keep replies short.",
    "pipeline_mode": "full",
    "default_face_id": "rc9cff32ceba"
  }'

Copy pal_id from the response. To shape how the PAL thinks and acts, see PAL overview and Create PAL.

2. Create an embed deployment

Create an active embed deployment for the PAL. allowed_origins limits which sites can load it, so start with your local dev server:

curl --request POST \
  --url https://tavusapi.com/v2/deployments \
  --header "Content-Type: application/json" \
  --header "x-api-key: $TAVUS_API_KEY" \
  --data '{
    "pal_id": "<your_pal_id>",
    "channel": "embed",
    "name": "My first Tavus app",
    "status": "active",
    "allowed_origins": ["http://localhost:5173"]
  }'

Copy deployment_id from the response. Without "status": "active" the deployment is created as a draft and the embed cannot start conversations until you publish it.

You can also create and publish the deployment in the PAL Maker: choose your PAL, pick the Embed channel, and copy the deployment ID. The PAL Maker is also where you change the deployment’s theme, copy, call limits and bot protection later. The embed picks up saved changes on the next page load.

3. Add the embed to your app

React (Vite)

Create a Vite React app and install the embed:

npm create vite@latest tavus-first-call -- --template react-ts
cd tavus-first-call
npm install
npm install @tavus/embed@latest

Replace src/App.tsx. Importing @tavus/embed registers the <tavus-embed> element and its JSX types:

import "@tavus/embed";

const DEPLOYMENT_ID = "<your_deployment_id>";

export default function App() {
  return (
    <main style={{ maxWidth: 960, margin: "40px auto", fontFamily: "system-ui" }}>
      <h1>My first Tavus video chat</h1>
      <div style={{ width: "100%", aspectRatio: "16 / 9" }}>
        <tavus-embed deployment-id={DEPLOYMENT_ID} />
      </div>
    </main>
  );
}

Start the dev server:

npm run dev

HTML

Save this as index.html:

<!doctype html>
<html>
  <body>
    <div style="width: 720px; aspect-ratio: 16 / 9;">
      <tavus-embed deployment-id="<your_deployment_id>"></tavus-embed>
    </div>
    <script src="https://unpkg.com/@tavus/embed"></script>
  </body>
</html>

Serve it on port 5173 so it matches the allowed origin:

npx serve -l 5173 .

Open http://localhost:5173 and press Start. The embed checks your camera and microphone, then joins the conversation.

The embed fills its parent, so the parent needs a definite height or an aspect-ratio. See Sizing for portrait layouts and full-screen pages.

4. React to the call from your page

The embed dispatches tavus:* events on the element. In React, the typed TavusIntegration helper subscribes to them:

import { useEffect } from "react";
import { TavusIntegration } from "@tavus/embed";

export function useConversationLog() {
  useEffect(() => {
    const integration = new TavusIntegration("tavus-embed");
    const onStarted = (e: CustomEvent<{ conversationId: string }>) =>
      console.log("started", e.detail.conversationId);
    const onEnded = (e: CustomEvent<{ conversationId: string }>) =>
      console.log("ended", e.detail.conversationId);

    integration.on("tavus:conversation-started", onStarted);
    integration.on("tavus:conversation-ended", onEnded);
    return () => {
      integration.off("tavus:conversation-started", onStarted);
      integration.off("tavus:conversation-ended", onEnded);
    };
  }, []);
}

Call useConversationLog() from App. The same helper starts and ends the call from your own buttons, sends messages, and answers the PAL’s tool calls. See Host communication.

Tailor each conversation

Attributes on the element change one conversation without changing the deployment:

<tavus-embed
  deployment-id={DEPLOYMENT_ID}
  conversational-context="The user is Jane, on the Pro plan, viewing the billing page."
  custom-greeting="Hey Jane, want to pick up where we left off?"
  memory-stores={`${DEPLOYMENT_ID}-user-12345`}
/>

The full list, including override-config and the expanded overlay, is on the Embed page.

Before you go live

• Add your production origin to the deployment’s allowed origins. The embed does not load on an origin that is not on the list.
• Set daily and total call limits, and turn on bot protection, in the PAL Maker. See Protecting your deployment.
• Test on a published URL. Previews that run inside an iframe may not grant camera and microphone access.

Troubleshooting

• The embed does not load. Check that the page’s origin, including the port, is in allowed_origins, and that the deployment is active.
• The embed shows an unavailable screen. A call limit was reached or the PAL is busy. The title and description of that screen are configurable per cause in the PAL Maker.
• The embed has no height. Give its parent an explicit height or an aspect-ratio.

Need full control?

@tavus/embed covers most apps. When you need to own conversation creation or the call UI yourself:

• Use the @tavus/cvi-ui React library for Tavus React components, hooks, and server helpers that create conversations from your backend.
• Use Create Conversation from your server to set any conversation parameter, and End Conversation to clean up. API Conversation Quickstart walks through it.

Where to go next

• Embed for every attribute, sizing, and the expanded overlay.
• Host communication for events, the imperative API, and page tools.
• Examples for six complete embed pages.
• Widget for a floating launcher instead of an inline surface.
• Agents & automation for llms.txt, OpenAPI, Agent Skills, and MCP access.