Tavus Examples

https://github.com/tavus-engineering/tavus-examples
Admin
A collection of example applications and demos showcasing Tavus conversational video interface with...
Tokens:27,693
Snippets:247
Trust Score:6.8
License:Apache-2.0
Update:20 hours ago
Show doc for...
Tokens:
Raw
### Install frontend dependencies

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-pipecat-example/QUICKSTART.md

Installs the frontend npm dependencies by navigating to the frontend directory and running npm install.

```bash
cd frontend
npm install
cd ..
```

--------------------------------

### Start the frontend

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-pipecat-example/QUICKSTART.md

Starts the frontend development server. Run 'npm install' only the first time, then 'npm start' to launch the app at http://localhost:3000.

```bash
cd frontend
npm install  # Only needed first time
npm start
```

--------------------------------

### Install dependencies with npm install

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-transparent-background/README.md

Installs the project dependencies required for the example. Run this first before starting the development server.

```bash
npm install
```

--------------------------------

### Start the Pipecat bot

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-pipecat-example/QUICKSTART.md

Activates the virtual environment and starts the Pipecat bot with WebRTC transport on localhost:8080. Wait for the 'Bot ready!' message before proceeding.

```bash
# Make sure virtual environment is activated
source env/bin/activate

python tavus-pipecat.py --transport webrtc --host localhost --port 8080
```

--------------------------------

### Start development server with npm run dev

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-transparent-background/README.md

Starts the local development server for the example. After running this, enter your Tavus API key when prompted in the app. You can create an API key at https://platform.tavus.io/api-keys.

```bash
npm run dev
```

--------------------------------

### Install and run the landing page example

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-landing-page/README.md

Run these commands in the project root to install dependencies and start the Vite dev server. Requires a deployment id in src/constants.ts; without one the page shows a notice instead of the embed.

```bash
npm install
npm run dev
```

--------------------------------

### Install frontend dependencies

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-pipecat-example/frontend/README.md

Run from the frontend directory to install required npm packages.

```bash
cd frontend
npm install
```

--------------------------------

### Bot ready output

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-pipecat-example/QUICKSTART.md

Expected output after the Pipecat bot starts successfully, indicating the client URL to open.

```text
🚀 Bot ready!
   → Open http://localhost:8080/client in your browser
```

--------------------------------

### Start frontend development server

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-pipecat-example/frontend/README.md

Starts the React frontend, which opens at http://localhost:3000 and auto-connects to the assistant.

```bash
npm start
```

--------------------------------

### Create and activate virtual environment

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-pipecat-example/QUICKSTART.md

Creates a Python virtual environment and activates it. On macOS/Linux use 'source env/bin/activate'; on Windows use 'env\Scripts\activate'.

```bash
# Create virtual environment
python -m venv env

# Activate virtual environment
# On macOS/Linux:
source env/bin/activate
# On Windows:
# env\Scripts\activate
```

--------------------------------

### Install dependencies and run dev server

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-full-screen/README.md

Run these commands in the project root to install dependencies and start the Vite development server.

```bash
npm install
npm run dev

```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-livekit/README.md

Clone the repository, navigate to the project directory, and install dependencies using uv.

```bash
git clone <repo-url>
cd tavus-livekit

# Install dependencies
uv sync
```

--------------------------------

### Install CVI UI components with npx

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-ui-conversation/README.md

Run this command to add the CVI UI components and helper hook to your project.

```bash
npx @tavus/cvi-ui@latest add conversation-01 use-request-permissions
```

--------------------------------

### Environment variables required in .env

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-pipecat-example/QUICKSTART.md

Lists the required environment variables for the application. Ensure these are set in your .env file before running.

```text
DEEPGRAM_API_KEY=...
CARTESIA_API_KEY=...
GOOGLE_API_KEY=...
TAVUS_API_KEY=...
TAVUS_REPLICA_ID=...
```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-tool-calling/README.md

Commands to clone the repository, navigate to the cvi-tool-calling directory, and install npm dependencies.

```bash
git clone <repository-url>
cd cvi-tool-calling
npm install
```

--------------------------------

### Environment Setup (.env.local)

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-tool-calling/README.md

Create a .env.local file with your Tavus API key and persona ID. Obtain credentials from the Tavus Developer Portal and Persona Creation page.

```bash
TAVUS_API_KEY=your_tavus_api_key_here
TAVUS_PERSONA_ID=your_persona_id_here
```

--------------------------------

### Start cloud recording with callFrame.startRecording

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/start-stop-recording/index.html

Starts a cloud recording on the joined conversation using recordingType "cloud". Requires the conversation to be joined first; otherwise the callFrame is undefined and an error is caught.

```JavaScript
// Start Recording
startRecordingButton.addEventListener("click", () => {
  try {
    callFrame.startRecording({ recordingType: "cloud" });
    statusDiv.textContent = "Recording started!";
  } catch (error) {
    statusDiv.textContent = "Failed to start recording: " + error.message;
  }
});
```

--------------------------------

### Toggle instructions visibility

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/start-stop-recording/index.html

Toggles the display of the instructions content between block and none. Used for the expand/collapse behavior of the setup instructions section.

```JavaScript
// Function to toggle the visibility of the instructions
function toggleInstructions() {
  const instructionsContent = document.getElementById("instructions-content");
  instructionsContent.style.display = instructionsContent.style.display === "block" ? "none" : "block";
}
```

--------------------------------

### Run the Agent

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-livekit/README.md

Start the agent with uv run python tavus.py dev. The agent will wait for participants to join a LiveKit room.

```bash
uv run python tavus.py dev
```

--------------------------------

### Create .env file with VITE_APP_TAVUS_API_KEY

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-quickstart-react/README.md

Create a `.env` file in the root directory and add your Tavus API key using the `VITE_APP_TAVUS_API_KEY` variable. You can create an API key at https://platform.tavus.io/.

```bash
VITE_APP_TAVUS_API_KEY=your_api_key_here
```

--------------------------------

### Start Pipecat bot with WebRTC transport

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-pipecat-example/frontend/README.md

Launches the Pipecat assistant server on localhost:8080 using WebRTC transport.

```bash
python tavus-pipecat.py --transport webrtc --host localhost --port 8080
```

--------------------------------

### Install and import @tavus/embed

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Install the package and import it once at the app entry as a static import. Do not use lazy import() to avoid Vite dependency re-optimization issues. In server-rendered frameworks, import inside a client component or after mount.

```bash
npm install @tavus/embed
```

```javascript
import "@tavus/embed"
```

--------------------------------

### Install ngrok

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Install ngrok for local development. On macOS with Homebrew, use `brew install ngrok`. Alternatively, download from the ngrok website.

```bash
# On macOS with Homebrew
brew install ngrok

# Or download from https://ngrok.com/download
```

--------------------------------

### startConversation()

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Starts a conversation programmatically, taking the same path as the built-in Start button: device permission prompt, bot check if enabled, then join. Safe to call multiple times; it never throws or rejects, and failures are reported via events.

```APIDOC
## startConversation()

### Description
Starts a conversation programmatically, taking the same path as the built-in Start button: device permission prompt, bot check if enabled, then join. Safe to call multiple times; it never throws or rejects, and failures are reported via events.

### Method
startConversation()

### Parameters
None

### Usage Notes
- Call after the element's `ready` event has fired, or inside the ready handler if the click mounts the element.
- Calling twice still starts one conversation; a call while one is live does nothing.
- Failures arrive as `tavus:error` `{ code, message }` and the element moves to its unavailable screen, firing `tavus:mode-change` with `unavailable`.
- Do not call again from `tavus:error` or `tavus:conversation-ended` handlers; the element shows a Try again button where retry can help.
- To skip the device check when the visitor has already pressed your button, use `override-config` `{"customization":{"show_haircheck":false}}`.

### Events
- Success: `tavus:conversation-started` `{ conversationId }`
- Failure: `tavus:error` `{ code, message }`
- Mode change: `tavus:mode-change` with `unavailable`
```

--------------------------------

### Project Structure

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-livekit/README.md

Shows the main files in the project: tavus.py, pyproject.toml, and .env.

```text
├── tavus.py           # Main agent code
├── pyproject.toml     # Python dependencies
└── .env               # Environment variables (create this)
```

--------------------------------

### Install required packages

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Install all Python dependencies listed in requirements.txt.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install and import @tavus/widget

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/widget-prompt.md

Install the package with npm and import it once at the app entry as a static import. Avoid lazy import() in Vite dev server to prevent dependency re-optimization issues. For server-rendered frameworks, import inside a client component or after mount.

```bash
npm install @tavus/widget
```

```javascript
import "@tavus/widget"
```

--------------------------------

### Persona System Prompt

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-tool-calling/README.md

System prompt for the Tavus Shopping Guide persona. Instructs the assistant to use only provided context, confirm before calling add_to_cart, and never call the tool without confirmation.

```text
You are Tavus Shopping Guide, a friendly and knowledgeable assistant.  

Your purpose is to help customers by:  
- Explaining the Tavus product information provided in the context.  
- Providing accurate pricing information from the context when asked.  

Guidelines:  
- All product and pricing information is available in the context — do not invent or assume details.  
- Always be helpful, supportive, and customer-focused.  
- Keep responses professional but approachable — like a helpful store associate.  
- When unsure or if information is missing from the context, Tell the customer to check website and add manually.

Tool usage:  
- If a customer asks to add an item, first confirm the product name and quantity with them.  
- After explicit confirmation, call the `add_to_cart` tool with the correct parameters.  
- Never call the tool without confirmation.
```

--------------------------------

### Start Flask server with custom_llm_iss.py

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Starts the Flask server on `http://127.0.0.1:8000`. Port 8000 is used to avoid conflicts with macOS AirPlay on port 5000.

```bash
python custom_llm_iss.py
```

--------------------------------

### Clone the repository

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Clone the tavus-examples repository and navigate to the custom LLM example directory.

```bash
git clone git@github.com:Tavus-Engineering/tavus-examples.git
cd examples/cvi-custom-llm-with-backend
```

--------------------------------

### startConversation()

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/widget-prompt.md

Starts a conversation with the agent programmatically. This is used when a custom page button is needed instead of the built-in launcher.

```APIDOC
## startConversation()

### Description
Starts a conversation with the agent programmatically. This is used when a custom page button is needed instead of the built-in launcher.

### Method
startConversation

### Parameters
None.

### Example
```js
startConversation();
```
```

--------------------------------

### Wrap App with CVIProvider in main.tsx

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-ui-conversation/README.md

Wrap your React app with CVIProvider in main.tsx or index.tsx to enable CVI UI components.

```tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import { CVIProvider } from './components/cvi/components/cvi-provider';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <CVIProvider>
      <App />
    </CVIProvider>
  </StrictMode>
);
```

--------------------------------

### conversation.tool_call event schema example

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-tool-calling/README.md

Shows the JSON structure of a conversation.tool_call event as per Tavus documentation, including message_type, event_type, conversation_id, inference_id, and properties with name and arguments.

```typescript
{
  "message_type": "conversation",
  "event_type": "conversation.tool_call",
  "conversation_id": "c123456",
  "inference_id": "83294d9f-8306-491b-a284-791f56c8383f",
  "properties": {
    "name": "add_to_cart",
    "arguments": "{\"item_name\": \"Bananas\", \"quantity\": 2}"
  }
}
```

--------------------------------

### Request camera and microphone permissions with useRequestPermissions

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-ui-conversation/README.md

Call the built-in useRequestPermissions hook before creating a conversation. The handleJoin function requests permissions, creates a conversation on your backend, and updates the screen state.

```tsx
import { createConversation } from './api';
import { useRequestPermissions } from './components/cvi/hooks/use-request-permissions';

// …component setup

const handleJoin = async (token: string) => {
  try {
    setLoading(true);

    // 1️⃣ Ask the browser for permissions
    await requestPermissions();

    // 2️⃣ Create a conversation on your backend
    const conversation = await createConversation(token);
    setConversation(conversation);
    setScreen('call');
  } catch (error) {
    alert('Something went wrong.');
  } finally {
    setLoading(false);
  }
};
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-livekit/README.md

Create a .env file with LiveKit credentials and API keys for OpenAI, Deepgram, Cartesia, and Tavus.

```env
# LiveKit credentials (from https://cloud.livekit.io/)
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret

# AI service API keys
OPENAI_API_KEY=sk-...
DEEPGRAM_API_KEY=...
CARTESIA_API_KEY=...
TAVUS_API_KEY=...
```

--------------------------------

### Expose local server with ngrok

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Starts an ngrok tunnel to expose the local Flask server on port 8000 to the internet. Run in a new terminal window.

```bash
ngrok http 8000
```

--------------------------------

### Activate virtual environment

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Activates the Python virtual environment before starting the Flask server. On Windows, use `venv\Scripts\activate` instead.

```bash
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

--------------------------------

### conversational-context attribute

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Passes the current state (cart, open product, visitor's selection) to the agent at the start of a call. The agent only knows what the page tells it.

```APIDOC
## conversational-context

### Description
Attribute on the `<tavus-embed>` element that provides the agent with the current page state at the start of a call.

### Usage
Set the attribute to a JSON string representing the state.

### Example
```html
<tavus-embed conversational-context='{"cart": [], "product": "..."}'></tavus-embed>
```
```

--------------------------------

### Join Tavus Conversation with DailyIframe

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/start-stop-recording/index.html

Initializes a Daily call frame, joins the conversation using the provided URL, and enables the recording buttons on success. Requires a valid Tavus Conversation URL (e.g., https://tavus.daily.co/cc12345abcde).

```JavaScript
const videoFrame = document.getElementById("video-frame");
const joinButton = document.getElementById("join-Conversation");
const startRecordingButton = document.getElementById("start-recording");
const stopRecordingButton = document.getElementById("stop-recording");
const statusDiv = document.getElementById("status");
let callFrame;

// Join Conversation
joinButton.addEventListener("click", () => {
  const ConversationURL = document.getElementById("Conversation-url").value;
  if (!ConversationURL) {
    statusDiv.textContent = "Please enter a valid Conversation URL.";
    return;
  }

  // If a previous call frame exists, leave it
  if (callFrame) {
    callFrame.leave();
    videoFrame.innerHTML = ""; // Clear the iframe
  }

  // Initialize the call frame
  callFrame = DailyIframe.createFrame(videoFrame, {
    showLeaveButton: true,
  });

  // Join the Conversation
  callFrame.join({ url: ConversationURL })
    .then(() => {
      statusDiv.textContent = "Joined Conversation successfully!";
      startRecordingButton.disabled = false;
      stopRecordingButton.disabled = false;
    })
    .catch((error) => {
      statusDiv.textContent = "Failed to join Conversation: " + error.message;
    });
});
```

--------------------------------

### Customize Tavus Avatar

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-livekit/README.md

Edit tavus.py to set your replica_id and persona_id from the Tavus dashboard.

```python
avatar = tavus.AvatarSession(
    replica_id="your-replica-id",    # Your Tavus replica
    persona_id="your-persona-id",    # Your Tavus persona
)
```

--------------------------------

### Customize Agent Personality

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-livekit/README.md

Set custom instructions for the agent's behavior.

```python
agent = Agent(
    instructions="Your custom instructions here..."
)
```

--------------------------------

### Render Conversation component in App.tsx

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-ui-conversation/README.md

Render the CVI UI Conversation component once you have a conversation object. It conditionally shows the welcome screen or the call screen based on the screen state.

```tsx
import { Conversation } from './components/cvi/components/conversation';

// …inside the component
return (
  <main>
    {screen === 'welcome' && (
      <WelcomeScreen onStart={handleJoin} loading={loading} />
    )}

    {screen === 'call' && conversation && (
      <Conversation
        conversationUrl={conversation.conversation_url}
        onLeave={handleEnd}
      />
    )}
  </main>
);
```

--------------------------------

### Tool Configuration for add_to_cart

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-tool-calling/README.md

JSON tool configuration for the add_to_cart function. Requires item_name and optional quantity (defaults to 1). Must be added to the persona's LLM configuration with model tavus-gpt-4o.

```json
[
  {
    "type": "function",
    "function": {
      "name": "add_to_cart",
      "parameters": {
        "type": "object",
        "required": [
          "item_name"
        ],
        "properties": {
          "quantity": {
            "type": "number",
            "description": "The number of units to add to the cart. Defaults to 1 if not specified."
          },
          "item_name": {
            "type": "string",
            "description": "The exact name of the product to add to the cart (e.g., 'Bananas', 'Almond Milk', 'Whole Wheat Bread')."
          }
        }
      },
      "description": "Adds a specific product from the available catalog to the customer's shopping cart. Always confirm the item name and quantity with the customer before calling this function."
    }
  }
]
```

--------------------------------

### Expected response from conversation creation

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Example JSON response returned by `conversation_creation.py`, containing the `conversation_id`, `conversation_name`, `conversation_url`, `status`, `callback_url`, and `created_at` fields.

```json
{
  "conversation_id": "c0eaa60a267274af",
  "conversation_name": "Jared Life Coach", 
  "conversation_url": "https://tavus.daily.co/c0eaa60a267274af",
  "status": "active",
  "callback_url": "https://yourwebsite.com/webhook",
  "created_at": "2025-09-10T00:35:24.310570Z"
}
```

--------------------------------

### Streaming Response Format

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Example of the streaming response in OpenAI chat completions format, showing data chunks and the [DONE] marker.

```text
data: {"choices": [{"delta": {"content": "Hello"}}]}
data: {"choices": [{"delta": {"content": "!"}}]}
data: [DONE]
```

--------------------------------

### Process tool call and send conversation.echo response

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-tool-calling/README.md

Handles a conversation.tool_call event by parsing arguments, executing the add_to_cart function against the shopping catalog, and sending a conversation.echo response back to Tavus via call.sendAppMessage.

```typescript
const handleToolCall = async (event) => {
  const { conversation_id, properties } = event.data
  const { name, arguments: args } = properties
  
  // Parse arguments and execute function
  const parsedArgs = JSON.parse(args)
  
  switch (name) {
    case 'add_to_cart':
      // Find item in catalog
      const foundItem = shoppingItems.find(item => 
        item.name.toLowerCase().includes(parsedArgs.item_name.toLowerCase())
      )
      
      if (foundItem) {
        // Add to cart
        onAddToCart(foundItem, parsedArgs.quantity || 1)
        result = `Added ${foundItem.name} to your cart!`
      } else {
        result = `Sorry, I couldn't find "${parsedArgs.item_name}" in our store.`
      }
      break
  }
  
  // Send response back to Tavus
  call.sendAppMessage({
    message_type: 'conversation',
    event_type: 'conversation.echo',
    conversation_id: conversation_id,
    properties: {
      modality: 'text',
      text: result,
      done: true
    }
  }, '*')
}
```

--------------------------------

### Render HairCheck component to request permissions

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-ui-haircheck-conversation/README.md

Render the HairCheck component to request camera and microphone permissions. Call the useRequestPermissions hook before creating a conversation. The component accepts isJoinBtnLoading, onJoin, and onCancel props.

```tsx
import { createConversation } from './api';
import { HairCheck } from './components/cvi/components/hair-check';

// …inside the component
return (
  <main>
    ...
    <div>
      {screen === 'hairCheck' && (
        <HairCheck
          isJoinBtnLoading={loading}
          onJoin={handleJoin}
          onCancel={() => setScreen('welcome')}
        />
      )}
      ...
    </div>
  </main>
);
```

--------------------------------

### Stop cloud recording with callFrame.stopRecording

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/start-stop-recording/index.html

Stops the active cloud recording on the joined conversation. Requires the conversation to be joined first; otherwise the callFrame is undefined and an error is caught.

```JavaScript
// Stop Recording
stopRecordingButton.addEventListener("click", () => {
  try {
    callFrame.stopRecording();
    statusDiv.textContent = "Recording stopped!";
  } catch (error) {
    statusDiv.textContent = "Failed to stop recording: " + error.message;
  }
});
```

--------------------------------

### Listen for conversation.tool_call app messages in VideoBox.tsx

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-tool-calling/README.md

Registers a Daily.js app-message listener in VideoBox.tsx to detect Tavus conversation.tool_call events and route them to handleToolCall.

```typescript
// Listen for app messages from Tavus
call.on('app-message', (event) => {
  if (event.data && event.data.event_type === 'conversation.tool_call') {
    handleToolCall(event)
  }
})
```

--------------------------------

### endConversation()

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Ends a live call, cancels a pending start or device check, and ends a prepared room nobody joined. Fires tavus:conversation-ended for a live call and shows the after-call screen.

```APIDOC
## endConversation()

### Description
Ends a live call, cancels a pending start or device check, and ends a prepared room nobody joined. Fires tavus:conversation-ended for a live call and shows the after-call screen.

### Method
endConversation()

### Parameters
None

### Usage Notes
- Unmounting the element also ends its call, but without an ended event; treat your own unmount as the end.
- For a fresh preview for the next visitor, recreate the element (e.g., change its key in React) rather than reusing the one on the after-call screen.

### Events
- `tavus:conversation-ended` `{ conversationId }` (only for a live call)
```

--------------------------------

### Host API usage with TavusIntegration

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-programmatic/README.md

Shows the core host API methods and events used to control the embed programmatically. Instantiate TavusIntegration after the element is in the DOM, subscribe to 'tavus:ready' to start the conversation, and use sendMessage to send text into the conversation. The same methods and events exist on the element itself for pages without a bundler.

```ts
const tavus = new TavusIntegration("tavus-embed"); // after the element is in the DOM
tavus.on("tavus:ready", () => tavus.startConversation());
tavus.on("tavus:conversation-started", (e) => e.detail.conversationId);
tavus.sendMessage({ event_type: "conversation.respond", properties: { text } });
```

--------------------------------

### Configure AI Models

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/tavus-livekit/README.md

Modify the AgentSession in tavus.py to set STT, LLM, and TTS models. Defaults: Deepgram Nova 3, OpenAI GPT-4o, Cartesia Sonic 3.

```python
session = AgentSession(
    stt=inference.STT(model="deepgram/nova-3", language="en"),
    llm=inference.LLM(model="openai/gpt-4o"),
    tts=inference.TTS(model="cartesia/sonic-3", voice="your-voice-id", language="en"),
)
```

--------------------------------

### Tavus embed with expand-options enabled

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-preview-to-modal/README.md

Add the `expand-options` attribute with `{"enabled":true}` to the `<tavus-embed>` element to make the card expand into a modal when the call starts. The attribute is observed, so setting it later updates the card; disabling it during a call collapses the modal.

```html
<tavus-embed deployment-id="…" expand-options='{"enabled":true}'></tavus-embed>
```

--------------------------------

### Create .env file with API keys

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Create a `.env` file in the project root and add your OpenAI, Tavus, and ngrok URL keys.

```env
OPENAI_API_KEY=your_openai_api_key_here
TAVUS_API_KEY=your_tavus_api_key_here
NGROK_URL=https://your-ngrok-url.ngrok-free.app
```

--------------------------------

### open()

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/widget-prompt.md

Opens the widget's launcher or conversation programmatically. This is used when a custom page button is needed instead of the built-in launcher.

```APIDOC
## open()

### Description
Opens the widget's launcher or conversation programmatically. This is used when a custom page button is needed instead of the built-in launcher.

### Method
open

### Parameters
None.

### Example
```js
open();
```
```

--------------------------------

### Create and activate a virtual environment

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Create a Python virtual environment and activate it. On Windows, use `venv\Scripts\activate` instead.

```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

--------------------------------

### createConversation()

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Creates a conversation room ahead of time without joining, so a later startConversation() joins quickly. Use when a call is clearly coming, and set conversational-context and custom-greeting before calling.

```APIDOC
## createConversation()

### Description
Creates a conversation room ahead of time without joining, so a later startConversation() joins quickly. Use when a call is clearly coming, and set conversational-context and custom-greeting before calling.

### Method
createConversation()

### Parameters
None

### Usage Notes
- Set `conversational-context` and `custom-greeting` before calling; they are read at creation.
- If those values change after creation, create again (the element ends the room nobody joined).
- Fires `tavus:conversation-created` `{ conversationId }` and resolves with the same.
- Rejects when the room could not be created; in that case do nothing, the later start creates one as usual.
- Every creation is a real conversation on the backend even if nobody joins, so end it with `endConversation()` when the visitor leaves without starting.
- If a start arrives while the create is still in flight, the start joins that attempt and the created event does not fire.

### Events
- Success: `tavus:conversation-created` `{ conversationId }`
```

--------------------------------

### Add widget to custom code (no bundler)

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/widget-prompt.md

For site builders like Webflow, Framer, Wix, or Squarespace, paste these lines into the site's custom code before </body>.

```html
<tavus-widget deployment-id="…"></tavus-widget>
```

```html
<script src="https://unpkg.com/@tavus/widget@latest"></script>
```

--------------------------------

### Run conversation creation script

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Runs `conversation_creation.py` to create a new Tavus persona with the custom LLM endpoint and a conversation using that persona. Returns conversation details.

```bash
python conversation_creation.py
```

--------------------------------

### tavus:state-change event

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Tracks the connection state of the element. The detail contains a `state` field with values: idle, initializing, connecting, connected, disconnecting, ended, error.

```APIDOC
## tavus:state-change

### Description
Dispatched when the connection state changes. Use this to know where the element is in its lifecycle.

### Event Detail
- **state** (string) - One of: `idle`, `initializing`, `connecting`, `connected`, `disconnecting`, `ended`, `error`.

### Example
```js
element.addEventListener('tavus:state-change', (event) => {
  console.log(event.detail.state);
});
```
```

--------------------------------

### Update .env with NGROK_URL

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Sets the `NGROK_URL` environment variable to the ngrok URL (e.g., `https://abc123.ngrok-free.app`) copied from the ngrok output.

```env
NGROK_URL=https://abc123.ngrok-free.app
```

--------------------------------

### updateConfig(patch)

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Updates the embed configuration at runtime. The patch takes the same shape as `override-config` and is deep-merged over the current configuration.

```APIDOC
## updateConfig(patch)

### Description
Changes settings while the element is mounted. The patch is deep-merged over the current configuration, for example to switch themes.

### Method
updateConfig

### Parameters
- **patch** (object) - Required - Same shape as `override-config`; deep-merged over the current configuration.

### Example
```js
element.updateConfig({ theme: 'dark' });
```
```

--------------------------------

### POST /chat/completions

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Initiates a chat completion that forwards requests to OpenAI's API with authentication. It accepts a list of messages and returns a streaming response in OpenAI chat completions format.

```APIDOC
## POST /chat/completions

### Description
Initiates a chat completion that forwards requests to OpenAI's API with authentication.

### Method
POST

### Endpoint
/chat/completions

### Headers
- `Content-Type: application/json`
- `Authorization: Bearer <your-api-key>` (any non-empty string works for this demo)

### Request Body
- `messages` (array) - Required - List of message objects, each with `role` and `content`.

### Request Example
```json
{
  "messages": [
    {"role": "user", "content": "Your message here"}
  ]
}
```

### Response
A streaming response in OpenAI chat completions format.

#### Response Example
```
data: {"choices": [{"delta": {"content": "Hello"}}]}
data: {"choices": [{"delta": {"content": "!"}}]}
data: [DONE]
```
```

--------------------------------

### updateConfig(patch)

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/widget-prompt.md

Updates the widget configuration while the element is mounted. The patch takes the same shape as override-config and is deep-merged over the current configuration.

```APIDOC
## updateConfig(patch)

### Description
Updates the widget configuration while the element is mounted. The patch takes the same shape as override-config and is deep-merged over the current configuration.

### Method
updateConfig

### Parameters
- **patch** (object) - Required - Configuration patch to merge.

### Example
```js
updateConfig({ theme: 'dark', launcherText: 'Chat with us' });
```
```

--------------------------------

### sendMessage()

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Sends a message into the conversation. Only call after tavus:conversation-started. Accepts an object with event_type and properties, or a plain string that is wrapped as conversation.respond.

```APIDOC
## sendMessage()

### Description
Sends a message into the conversation. Only call after tavus:conversation-started. Accepts an object with event_type and properties, or a plain string that is wrapped as conversation.respond.

### Method
sendMessage(message)

### Parameters
- **message** (object or string) - Required - The message to send. If a string, it is wrapped as `conversation.respond`.

### Supported event_type values
- `conversation.respond` - Makes the agent answer the text as if the visitor had said it.
- `conversation.echo` - Makes the agent say the text verbatim.
- `conversation.interrupt` - Stops the agent mid-sentence.
- `conversation.append_llm_context` - Changes what the agent knows mid-call (append).
- `conversation.overwrite_llm_context` - Changes what the agent knows mid-call (overwrite).

### Request Example
```json
{
  "event_type": "conversation.respond",
  "properties": {
    "text": "Hello"
  }
}
```
```

--------------------------------

### sendChat()

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Sends a chat message as the visitor on the element. This is a method on the element object (el.tavus.sendChat).

```APIDOC
## el.tavus.sendChat(text)

### Description
Sends a chat message as the visitor on the element. This is a method on the element object (el.tavus.sendChat).

### Method
sendChat(text)

### Parameters
- **text** (string) - Required - The chat message to send.

### Usage Notes
- Only call after `tavus:conversation-started`.
```

--------------------------------

### tavus:tool-call event

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Dispatched when the agent decides to use a tool defined with `delivery: { app_message: true }`. The event detail contains the tool name, arguments as a JSON string, and an optional tool_call_id.

```APIDOC
## tavus:tool-call

### Description
Fired when the agent invokes a tool that has `delivery: { app_message: true }`. The page must parse the arguments, validate them, perform the action, and reply via `sendMessage`.

### Event Detail
- **name** (string) - The tool name.
- **arguments** (string) - JSON string written by the model for the tool's schema.
- **tool_call_id** (string, optional) - Identifier to pair the reply with.

### Example
```js
element.addEventListener('tavus:tool-call', (event) => {
  const { name, arguments: args, tool_call_id } = event.detail;
  // parse and validate args, act, then sendMessage(...)
});
```
```

--------------------------------

### tavus:mode-change event

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Tracks the screen mode of the element. The detail contains a `mode` field with values: idle, haircheck, call, ended, unavailable.

```APIDOC
## tavus:mode-change

### Description
Dispatched when the screen mode changes. Use this to know which screen is displayed (preview, haircheck, call, after-call, unavailable).

### Event Detail
- **mode** (string) - One of: `idle`, `haircheck`, `call`, `ended`, `unavailable`.

### Example
```js
element.addEventListener('tavus:mode-change', (event) => {
  console.log(event.detail.mode);
});
```
```

--------------------------------

### Test API endpoint with curl

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

Sends a POST request to the custom LLM endpoint at `/chat/completions` with an `Authorization: Bearer` header and a JSON body containing a user message. The API expects requests in the standard OpenAI chat completions format.

```bash
curl -X POST https://your-ngrok-url.ngrok-free.app/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer random-api-key" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'
```

--------------------------------

### POST /chat/completions Request Body

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/cvi-custom-llm-with-backend/README.md

JSON payload for initiating a chat completion. The messages array contains the conversation history with user role and content.

```json
{
  "messages": [
    {"role": "user", "content": "Your message here"}
  ]
}
```

--------------------------------

### append_llm_context method

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Updates the agent's context mid-call when the page state changes. Use this to keep the agent informed of changes during a call.

```APIDOC
## append_llm_context

### Description
Sends additional context to the agent during a call. Call this when the page state changes mid-call.

### Parameters
- **context** (object) - Required - The new or updated state information.

### Example
```js
element.append_llm_context({ cart: ['item1'] });
```
```

--------------------------------

### sendMessage({ event_type: "conversation.tool_result", properties: { tool_call_id, output, status } })

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Sends the result of a tool call back to the agent. The page must reply with the same tool_call_id received in the tavus:tool-call event, and set status to "success" or "error".

```APIDOC
## sendMessage

### Description
Sends a message to the agent, used to deliver tool results. The page calls this after performing the work requested by a tool call, pairing the reply with the original tool_call_id.

### Method
sendMessage

### Parameters
#### properties
- **event_type** (string) - Required - Must be `"conversation.tool_result"`.
- **properties.tool_call_id** (string) - Required - The identifier from the `tavus:tool-call` event.
- **properties.output** (string) - Required - The result of the tool execution.
- **properties.status** (string) - Required - `"success"` or `"error"`.

### Request Example
```json
{
  "event_type": "conversation.tool_result",
  "properties": {
    "tool_call_id": "...",
    "output": "...",
    "status": "success"
  }
}
```
```

--------------------------------

### Script tag for @tavus/embed

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Use this script tag in the page's custom code for site builders like Webflow, Framer, Wix, or Squarespace, or when not using a bundler. Place the element in an HTML embed block.

```html
<script src="https://unpkg.com/@tavus/embed@latest"></script>
```

--------------------------------

### expand-options attribute

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Controls the expanding card behavior. Changing the attribute updates the card; disabling it during a call collapses the modal.

```APIDOC
## expand-options

### Description
Attribute on the `<tavus-embed>` element that controls the expanding card. The modal is open while the mode is `haircheck` or `call`.

### Usage
Set or remove the attribute to expand or collapse the card.

### Example
```html
<tavus-embed expand-options></tavus-embed>
```
```

--------------------------------

### tavus:protocol-message

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/examples/embed-prompt.md

Event that delivers utterances. Filter for event_type === 'conversation.utterance' and use properties.role and properties.speech. Complete utterances have no final field; streaming partials have a boolean final field.

```APIDOC
## tavus:protocol-message

### Description
Event that delivers utterances. Filter for event_type === 'conversation.utterance' and use properties.role and properties.speech. Complete utterances have no final field; streaming partials have a boolean final field.

### Event Data
- **detail.event_type** (string) - Must be `conversation.utterance`.
- **detail.properties.role** (string) - `"user"` or `"replica"` (the agent).
- **detail.properties.speech** (string) - The spoken text.
- **detail.properties.final** (boolean, optional) - Present only on streaming partials; `false` while the sentence grows. May also carry `is_interrupted`.

### Usage Notes
- Keep only utterances without a `final` field to avoid showing every partial as its own line.
- `tavus:chat-message` and `tavus:message` exist in type definitions but never fire; do not build on them.
```

--------------------------------

### Update Persona ID in createConversation.ts

Source: https://github.com/tavus-engineering/tavus-examples/blob/main/showcase/santa-demo/README.md

Replace the persona_id with your own Santa variant or different character. The snippet shows the request body for creating a conversation, including the persona_id, replica_id, conversation_name, conversational_context, custom_greeting, and properties. Update the persona_id to customize the character.

```typescript
body: JSON.stringify({
  // Replace with your own Persona ID
  persona_id: "p5317866", // Santa's unique persona ID in Tavus
  replica_id: "r79e1c033f", // Santa's unique replica ID
  conversation_name: "A Chat with Santa", // Name of the Santa-themed conversation
  conversational_context: "You are about to talk to Santa Claus, the jolly figure of holiday cheer...", // Adds context for the conversation
  custom_greeting: "Ho Ho Ho! Merry Christmas! How can Santa help you today?", // Santa's iconic greeting
  properties: {
    language: "english", // Language for the conversation (30 avalible languages!)
  },
}),
```
Tokens:
Raw