# Authentication Source: https://docs.tavus.io/api-reference/authentication Generate an API key in the Developer Portal and send it on each request in the `x-api-key` header. To use the Tavus API, you need an API key to authenticate your requests. This key verifies that requests are coming from your Tavus account. ## Get the API key 1. Go to the Developer Portal and select **API Key** from the sidebar menu. 2. Click **Create New Key** to begin generating your API key. 3. Enter a name for the key and (optional) specify allowed IP addresses, then click **Create API Key**. 4. Copy your newly created API key and store it securely. **Remember that your API key is a secret!** Never expose it in client-side code such as browsers or apps. Always load your API key securely from environment variables or a server-side configuration. ## Make Your First Call Requests go to **`https://tavusapi.com`**. Authenticate with your API key by sending it in the **`x-api-key`** header on every request, as below. ```http theme={null} x-api-key: ``` For example, you are using the [POST - Create Conversation](/api-reference/conversations/create-conversation) endpoint to create a real-time video call session with a Tavus replica. In this scenario, you can send an API request and replace `` with your actual API key. ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "replica_id": "r90bbd427f71", "persona_id": "pdac61133ac5", "conversation_name": "Interview User" }' ``` # Create conversation Source: https://docs.tavus.io/api-reference/conversations/create-conversation post /v2/conversations This endpoint starts a real-time video conversation with your AI replica, powered by a persona that allows it to see, hear, and respond like a human. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete Conversation Source: https://docs.tavus.io/api-reference/conversations/delete-conversation delete /v2/conversations/{conversation_id} This endpoint deletes a single conversation by its unique identifier. Use this for destructive data removal. For normal call cleanup when a user leaves or a session is finished, use [End Conversation](/api-reference/conversations/end-conversation) instead. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # End Conversation Source: https://docs.tavus.io/api-reference/conversations/end-conversation post /v2/conversations/{conversation_id}/end This endpoint ends a single conversation by its unique identifier. Use this for routine call cleanup when a user leaves or your app no longer needs the room. To destructively remove conversation data, use [Delete Conversation](/api-reference/conversations/delete-conversation). For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Conversation Source: https://docs.tavus.io/api-reference/conversations/get-conversation get /v2/conversations/{conversation_id} This endpoint returns a single conversation by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Conversations Source: https://docs.tavus.io/api-reference/conversations/get-conversations get /v2/conversations This endpoint returns a list of all Conversations created by the account associated with the API Key in use. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Create Document Source: https://docs.tavus.io/api-reference/documents/create-document post /v2/documents Upload documents to your knowledge base for personas to reference during conversations. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete Document Source: https://docs.tavus.io/api-reference/documents/delete-document delete /v2/documents/{document_id} Delete a document and its associated data using its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Document Source: https://docs.tavus.io/api-reference/documents/get-document get /v2/documents/{document_id} Retrieve detailed information about a specific document using its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Documents Source: https://docs.tavus.io/api-reference/documents/get-documents get /v2/documents Retrieve a list of documents. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Update Document Source: https://docs.tavus.io/api-reference/documents/patch-document patch /v2/documents/{document_id} Update a document's `document_name` and `tags`. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Recrawl Document Source: https://docs.tavus.io/api-reference/documents/recrawl-document post /v2/documents/{document_id}/recrawl Trigger a recrawl of a website document to fetch fresh content. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Create Guardrails Source: https://docs.tavus.io/api-reference/guardrails/create-guardrails post /v2/guardrails Create a new guardrail. Guardrails provide strict behavioral boundaries that are enforced throughout a conversation. Attach guardrails to a persona directly via `guardrail_ids` or by tag via `guardrail_tags` on [Create Persona](/api-reference/personas/create-persona). See [Legacy guardrail sets](/api-reference/guardrails/legacy-guardrail-sets). For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete Guardrails Source: https://docs.tavus.io/api-reference/guardrails/delete-guardrails delete /v2/guardrails/{guardrail_id} Delete a single guardrail by its unique identifier. Personas with this guardrail attached via `guardrail_ids` will have the reference removed automatically. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Guardrails Source: https://docs.tavus.io/api-reference/guardrails/get-guardrails get /v2/guardrails/{guardrail_id} Retrieve a single guardrail by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Guardrails Source: https://docs.tavus.io/api-reference/guardrails/list-guardrails get /v2/guardrails Return a flat list of guardrails owned by the caller. Pass `legacy=false` — recommended for all new integrations. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Patch Guardrails Source: https://docs.tavus.io/api-reference/guardrails/patch-guardrails patch /v2/guardrails/{guardrail_id} Update specific fields of a guardrail using [JSON Patch](https://jsonpatch.com/) operations. Paths must match the **current** document shape — compare against the response from [Get Guardrails](/api-reference/guardrails/get-guardrails) before patching. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Create Objectives Source: https://docs.tavus.io/api-reference/objectives/create-objectives post /v2/objectives This endpoint creates objectives for a persona. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete Objective Source: https://docs.tavus.io/api-reference/objectives/delete-objectives delete /v2/objectives/{objectives_id} This endpoint deletes a single objective by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Objective Source: https://docs.tavus.io/api-reference/objectives/get-objectives get /v2/objectives/{objectives_id} This endpoint returns a single objective by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Objectives Source: https://docs.tavus.io/api-reference/objectives/get-objectives-list get /v2/objectives This endpoint returns a list of all objectives. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Patch Objective Source: https://docs.tavus.io/api-reference/objectives/patch-objectives patch /v2/objectives/{objectives_id} This endpoint allows you to update specific fields of an objective using JSON Patch operations. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Overview Source: https://docs.tavus.io/api-reference/overview Discover the Tavus API — build a real-time, human-like multimodal video conversation with a replica. ## Getting Started with Tavus APIs Tavus APIs allow you to create a Conversational Video Interface (CVI), an end-to-end pipeline for real-time video conversations with an AI replica. Each replica is integrated with a persona that enables it to see, hear, and respond like a human. You can access the API through standard HTTP requests, making it easy to integrate CVI into any application or platform. For machine-readable API and docs context, use `https://docs.tavus.io/openapi.yaml` as the canonical HTTP API contract, `https://docs.tavus.io/llms.txt` as the docs page index, and `https://docs.tavus.io/llms-full.txt` as the full bundled docs export. ### Who Is This For? This API is for developers looking to add real-time, human-like AI interactions into their apps or services. ### What Can You Do? Use the end-to-end CVI pipeline to build human-like, real-time multimodal video conversations with these three core components: Define the agent’s behavior, tone, and knowledge. Train a lifelike digital replica from a short video or headshot image. Create a real-time video call session with your AI replica. A typical path: [Authentication](/api-reference/authentication), then [Create Persona](/api-reference/personas/create-persona), [Create Replica](/api-reference/phoenix-replica-model/create-replica), and [Create Conversation](/api-reference/conversations/create-conversation). For what CVI includes end-to-end, see [What is CVI?](/sections/conversational-video-interface/overview-cvi). # Create Persona Source: https://docs.tavus.io/api-reference/personas/create-persona post /v2/personas Creates a persona that configures how a replica behaves and sounds in CVI for every conversation that uses that persona. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete Persona Source: https://docs.tavus.io/api-reference/personas/delete-persona delete /v2/personas/{persona_id} This endpoint deletes a single persona by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Persona Source: https://docs.tavus.io/api-reference/personas/get-persona get /v2/personas/{persona_id} This endpoint returns a single persona by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Personas Source: https://docs.tavus.io/api-reference/personas/get-personas get /v2/personas This endpoint returns a list of all Personas created by the account associated with the API Key in use. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Patch Persona Source: https://docs.tavus.io/api-reference/personas/patch-persona patch /v2/personas/{persona_id} This endpoint allows you to update specific fields of a persona using JSON Patch operations. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Create Replica Source: https://docs.tavus.io/api-reference/phoenix-replica-model/create-replica post /v2/replicas Creates a new replica from a training video or image URL for use in conversations—see [Which training path?](/sections/replica/which-training-path) for preparation, consent, and media requirements. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete Replica Source: https://docs.tavus.io/api-reference/phoenix-replica-model/delete-replica delete /v2/replicas/{replica_id} Deletes a Replica by its unique ID; deleted replicas cannot be used in a conversation. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Replica Source: https://docs.tavus.io/api-reference/phoenix-replica-model/get-replica get /v2/replicas/{replica_id} This endpoint returns a single Replica by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Replicas Source: https://docs.tavus.io/api-reference/phoenix-replica-model/get-replicas get /v2/replicas This endpoint returns a list of all Replicas created by the account associated with the API Key in use. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Rename Replica Source: https://docs.tavus.io/api-reference/phoenix-replica-model/patch-replica-name patch /v2/replicas/{replica_id}/name This endpoint renames a single Replica by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Create Pronunciation Dictionary Source: https://docs.tavus.io/api-reference/pronunciation-dictionaries/create-pronunciation-dictionary post /v2/pronunciation-dictionaries Create a [pronunciation dictionary](/sections/conversational-video-interface/persona/pronunciation-dictionaries) with custom rules for controlling how words are spoken. Rules are automatically synced to both Cartesia and ElevenLabs so they work regardless of which TTS engine your persona uses. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete Pronunciation Dictionary Source: https://docs.tavus.io/api-reference/pronunciation-dictionaries/delete-pronunciation-dictionary delete /v2/pronunciation-dictionaries/{dictionary_id} Permanently delete a pronunciation dictionary and remove it from all linked personas. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Pronunciation Dictionary Source: https://docs.tavus.io/api-reference/pronunciation-dictionaries/get-pronunciation-dictionary get /v2/pronunciation-dictionaries/{dictionary_id} Retrieve a pronunciation dictionary by its ID, including all rules. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Pronunciation Dictionaries Source: https://docs.tavus.io/api-reference/pronunciation-dictionaries/list-pronunciation-dictionaries get /v2/pronunciation-dictionaries List all pronunciation dictionaries for the authenticated user with pagination. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Update Pronunciation Dictionary Source: https://docs.tavus.io/api-reference/pronunciation-dictionaries/update-pronunciation-dictionary patch /v2/pronunciation-dictionaries/{dictionary_id} Update a pronunciation dictionary's name or rules using [JSON Patch](https://jsonpatch.com/) format (RFC 6902). Supported mutable fields are `name` and `rules`. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Generate Video Source: https://docs.tavus.io/api-reference/video-request/create-video post /v2/videos This endpoint generates a new video using a Replica and either a script or an audio file. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete Video Source: https://docs.tavus.io/api-reference/video-request/delete-video delete /v2/videos/{video_id} This endpoint deletes a single video by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Video Source: https://docs.tavus.io/api-reference/video-request/get-video get /v2/videos/{video_id} This endpoint returns a single video by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Videos Source: https://docs.tavus.io/api-reference/video-request/get-videos get /v2/videos This endpoint returns a list of all Videos created by the account associated with the API Key in use. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Rename Video Source: https://docs.tavus.io/api-reference/video-request/patch-video-name patch /v2/videos/{video_id}/name This endpoint renames a single video by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Voices Source: https://docs.tavus.io/api-reference/voices/list-voices get /v2/voices Returns available stock **`voice_name`** values and their linked **replica** metadata. When you [Create Replica](/api-reference/phoenix-replica-model/create-replica) with **`train_image_url`** (image-to-replica), **`voice_name`** is required—use this list to pick a valid slug and to preview options. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Agents & automation Source: https://docs.tavus.io/sections/agents-and-automation How to access machine-readable docs and API artifacts for developers, IDEs, and automation - llms.txt, OpenAPI, Agent Skills, and MCP. **How do I point my agent, IDE, or automation at Tavus’s documentation and HTTP APIs?** This guide helps you pick the right artifact for your workflow. ## Documentation bundle reference | Artifact | Role | URL | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | **llms.txt** | Curated directory of doc URLs for selective fetch | `https://docs.tavus.io/llms.txt` | | **llms-full.txt** | Full bundled text export for offline or bulk ingest | `https://docs.tavus.io/llms-full.txt` | | **openapi.yaml** | HTTP API contract (paths, request/response schemas, security schemes) | `https://docs.tavus.io/openapi.yaml` | | **skill.md** | Agent-oriented capability summary ([Agent Skills](https://agentskills.io) conventions) | `https://docs.tavus.io/skill.md` | | **MCP** | Hosted Model Context Protocol server: search plus fetch full pages from the indexed docs site (see [Model Context Protocol](#model-context-protocol-mcp)) | `https://docs.tavus.io/mcp` | ## When to use what * **MCP:** Interactive tools that need live search and current page retrieval against the indexed site. * **llms-full.txt:** Bulk or offline ingestion; snapshot of doc text (not a substitute for OpenAPI). * **openapi.yaml:** Source of truth for HTTP APIs (requests, responses, auth headers); agents should not invent endpoints that contradict it. * **llms.txt / selective fetches:** Discovery and pulling specific pages when you do not want the full bundle. * **skill.md:** Compact capability orientation for agents; still point to OpenAPI and deep docs for details. ## Model Context Protocol (MCP) An MCP endpoint is available for this documentation site. Configure clients that support HTTP transport with: ```json theme={null} { "url": "https://docs.tavus.io/mcp", "transport": "http" } ``` Use MCP when the tool needs **live** search and retrieval against the **current** indexed documentation, not a frozen file export. # Changelog Source: https://docs.tavus.io/sections/changelog/changelog ## Enhancements * **Meet Rivian, Tiffany, and Brian:** Our 3 new stock replicas! * **Improved Image to Replica uploading flow:** Get more detailed and accurate errors before training submission. ## New Features * **Guardrails as first-class primitives:** Guardrails are now standalone resources that can be created, edited, and reused across multiple personas. Compose individual guardrails into sets via `guardrail_tags`. [Learn more](/sections/conversational-video-interface/guardrails) * **Choose your delivery channel:** Guardrail violations can now be delivered via [Interaction Events](/sections/conversational-video-interface/interactions-protocols/overview) (in-call `app-message`) or [Webhooks](/sections/webhooks-and-callbacks#guardrail-callbacks) (server-side `callback_url`) — or both. * **`guardrail_uuid` on violations:** Triggered events and callbacks now include `guardrail_uuid`, so you can identify exactly which individual guardrail was violated. ## New Features * **Azure TTS support:** Azure is now available as a TTS engine, expanding language coverage for multilingual and localized voice output. [Learn more](/sections/conversational-video-interface/persona/tts) ## New Features * **Individually addressable guardrails:** Guardrails are now first-class resources. Create, attach, edit, and delete each guardrail independently via the [Guardrails API](/api-reference/guardrails/create-guardrails). Bundle guardrails by tag and reference them on a persona via `guardrail_ids` or `guardrail_tags`. [Learn more](/sections/conversational-video-interface/guardrails) * **Node.js plugin support for LiveKit integration:** The LiveKit Agents integration now supports Node.js via the `@livekit/agents-plugin-tavus` plugin, in addition to Python. Install with `npm install @livekit/agents @livekit/agents-plugin-tavus`. [Learn more](/sections/integrations/livekit#node-js) * **Real-time event timestamps:** Every interaction event (`conversation.utterance`, `conversation.started_speaking`, etc.) now carries a `timestamp` field delivered in real time on the respective Interaction event. Learn more * **Transcript utterance timestamps:** End-of-call transcripts now carry per-turn timing. The [`application.transcription_ready`](https://docs.tavus.io/sections/webhooks-and-callbacks#conversation-callbacks) webhook (and the same payload nested under `events` in the verbose [`GET /conversations/{id}?verbose=true`](https://docs.tavus.io/api-reference/conversations/get-conversation) response) now includes `timestamp` (Unix epoch float, seconds — same field name as live interaction events), `seconds_from_start`, `duration` (seconds, float — same field name as `conversation.stopped_speaking.duration`), and `inference_id` (on assistant turns) on each transcript entry. ## Enhancements * **New, and more detailed, error messages when a replica fails:** [Learn more](/sections/errors-and-status-details#replica-training-errors) ## New Features * **AI Image Fixer API support:** [Create Replica](/api-reference/phoenix-replica-model/create-replica) now accepts an `auto_fix_training_image` property. Set it to `true` to use Tavus's AI Image Fixer to instantly fix any uploaded image to fit our requirements, eliminating the need for editing or recapturing photos. [Learn more](/sections/replica/train-with-an-image#ai-image-fixer) ## New Features * **AI Image Fixer:** Instantly fix any uploaded image to fit our requirements, eliminating the need for editing or recapturing photos. ## New Features * **Frame Checker (Video to Replica):** Get instant feedback, before recording, on whether your camera setup meets our requirements. ## Enhancements * **Less footage required (Video to Replica):** We now only require 1 minute of video, down from the 2 minutes previously needed. * **Simpler in-portal recording flow (Video to Replica):** A streamlined recording experience in the portal to help you capture high-quality recordings. ## New Features * **Image to Replica:** Build a replica from a single still. Drop in a photo, illustration, or brand mascot. ## New Features * **Voice Activity Detector improvements:** Resulting in a smoother conversational experience in noisy environments. This is automatically rolled out to all users. * **Expanded Recording Storage Support:** Conversation recordings can now be delivered to Google Cloud Storage (GCP) and Azure Blob Storage, in addition to AWS S3. Learn more ## Enhancements * **Tavus Components Library Updates:** Improved audio-video sync, plus new chat components and closed captions with streaming support. Learn more ## New Features * **Wake Phrase:** Personas can now stay silent until they hear a specific phrase, similar to how voice assistants like Siri or Alexa work. Configure it via the `wake_phrase` parameter in the Conversational Flow layer. The persona still hears everything that is said and responds with full conversation history once the wake phrase is detected. Learn more ## New Features * **Idle Engagement:** Replicas can now proactively re-engage by speaking to the user after a period where the user is silent. Eagerness of this feature can be configured via the `idle_engagement` parameter in the Conversational Flow layer. Learn more ## New Features * **Speaking Events:** Two new events — `conversation.started_speaking` and `conversation.stopped_speaking` — fire for both the replica and the user with a `role` field (`"replica"` or `"user"`) identifying the speaker. `conversation.stopped_speaking` includes an `interrupted` boolean and a `duration` field (in seconds). Learn more * **Conversation Diagnostics:** A new diagnostics surface for inspecting what happened in a conversation — including packet loss, network connection, FPS, and more — designed to make debugging significantly faster. Click on any conversation in the Developer Portal to access its diagnostics page. ## Enhancements * **Non-Interruptible Custom Greetings:** Custom greetings now finish entirely before users can interrupt speech. Previously, participants could talk over a `custom_greeting`; now the replica completes the greeting before it begins listening. Learn more * **Improved Turn-Taking Latency:** Significant TTS optimizations reduce turn-taking latency, resulting in faster and more natural back-and-forth during conversations. ## New Features * **Streaming Utterance Event:** A new `conversation.utterance.streaming` event progressively reports what has been said during a conversation turn for both replica and user utterances. Use it to power closed captioning and build accurate transcripts — especially when a user interrupts the replica, since the streaming event reflects only the words actually spoken rather than the full LLM response. Learn more * **Pronunciation Dictionaries:** Define custom pronunciation rules so your persona says brand names, technical terms, acronyms, and foreign words exactly right. Choose between simple alias substitution (e.g., "Tavus" → "TAH-vus") or precise IPA phonetic notation. Create a dictionary once and attach it to a persona via the TTS layer — any updates automatically propagate to all linked personas with zero extra latency at conversation time. Learn more ## New Features * **Voice Isolation:** Filter background noise from participant audio to improve conversation quality. Configure it via the `voice_isolation` parameter in the Conversational Flow layer. Learn more ## Changes * **Chat Interrupt History:** Personas now know when they have been interrupted. This allows the persona to pick back up where it left off, and also improves objectives adherence. ## New Features * **Expanded ASR Model Selection:** You can now choose from five specialized speech-to-text engines via the `stt_engine` parameter. New models include `tavus-parakeet`, `tavus-soniox`, `tavus-whisper`, and `tavus-deepgram-medical`. Use `tavus-auto` to automatically route to the best model for each conversation. Learn more ## Enhancements * **30% Faster Phoenix-4 Boot Time:** Phoenix-4 conversations now boot 30% faster, significantly reducing the time from conversation creation to readiness. ## Changes * **`conversation.replica_interrupted` Event Removed:** The `conversation.replica_interrupted` application message has been removed from interaction events. This event was deprecated in a previous backend update. Use `conversation.replica.stopped_speaking` with the `interrupted: true` property to detect interruptions instead. * **`duration` and `interrupted` Fields on Replica Stopped Speaking:** The `conversation.replica.stopped_speaking` event now includes a `duration` field (how long the replica spoke in seconds) and an `interrupted` field (`true`/`false`) indicating whether the replica was interrupted by the user. Learn more ## New Features * **Event Ordering and Turn Tracking:** All server-broadcasted interaction events now include `seq` and `turn_idx` fields. `seq` is a globally monotonic sequence number for ordering events that may arrive out of order, and `turn_idx` groups related events from the same conversation turn. Learn more ## Enhancements * **30% Faster Phoenix-4 Boot Time:** Phoenix-4 conversations now boot 30% faster, significantly reducing the time from conversation creation to readiness. ## Enhancements * **EU ElevenLabs BYOK Support:** Customers can now bring their own ElevenLabs API key from EU-region accounts. ## Enhancements * **Improved Knowledge Base Retrieval:** Optimized underlying infrastructure to improve utterance to utterance response times, particularly when `rag_search_quality` is set to `quality`. ## New Features * **Expanded Tavus-Hosted LLM Selection:** Added new Tavus-hosted LLM options including models from Gemini, Claude, and GPT families. `tavus-gpt-oss` is recommended as the default. Legacy models `tavus-gpt-4.1`, `tavus-gpt-4o`, and `tavus-gpt-4o-mini` are now deprecated. Learn more → * **Visual RAG:** CVI now supports visual retrieval-augmented generation. Upload custom image explanations that are matched and queried via vision embeddings, giving your persona richer visual context during conversations. ## Changes * **Persona**`context`**Field Deprecated:** The `context` field has been deprecated in favor of a unified `system_prompt` field. Existing `context` values have been automatically merged into system prompts. The API remains backward compatible, but we recommend using **only** `system_prompt` going forward. ## New Features * **Raven-1 Perception Model:** Introduced Raven-1, a multimodal perception model with audio emotion analysis and enhanced visual awareness. Raven-1 captures user emotion from audio in real time (sub-100ms audio perception latency), enabling personas to respond with greater emotional intelligence. The model is now the default for all new personas. Enable it by setting `perception_model_name` in your persona configuration. Learn more → * **Private Rooms:** Require authentication to join conversations for enhanced security. When enabled, we return a JWT meeting token that users must include when entering the room. Learn more ## Enhancements * **Upgraded Transcription Engine:** Upgraded transcription engine with 3x improvements in word error rates (WER). ## New Features * **Website Crawling for Knowledge Base:** You can now enable link crawling when creating knowledge base documents. Configure crawl `depth` and `max_pages` to automatically discover and ingest content from linked pages. Additionally, existing crawled documents can now be recrawled to keep knowledge base content up to date. ## Changes * **PlayHT TTS Removed:** PlayHT has been fully removed as a supported TTS engine. All personas previously using PlayHT should migrate to Cartesia or ElevenLabs. ## New Features * **Hard Delete for Conversations:** Conversations can now be permanently deleted via the API using the `hard=true` query parameter. Use this for GDPR compliance or data cleanup workflows. ## Enhancements * **Default TTS Model Updated to Sonic-3:** The default text-to-speech model has been updated to Sonic-3 across all new personas, delivering improved voice quality and naturalness. * **LiveKit Connection Stability:** Extensive reliability improvements to the LiveKit-based transport layer, including fixes for connection timeouts, track publishing hangs, event loop starvation, and ping timeout issues. ## Changes * **Default LLM Migrated to `tavus-gpt-oss`:** The default LLM for all new personas is now `tavus-gpt-oss`. All remaining `tavus-llama-4` personas have been automatically migrated. Legacy Tavus-Llama model references have been removed. ## New Features * **LLM Temperature & Top-P Parameters:** You can now configure `temperature` and `top_p` parameters for both Tavus-hosted LLMs and custom LLMs via the `extra_body` field in your persona's LLM configuration. Learn more → ## Enhancements * **Text Echo Language Accuracy:** Text echoes now correctly use the input language for conversion, improving accuracy in multilingual conversations. ## New Features * **Test Mode for Conversations:** You can now start conversations in test mode, where the replica does not join. Validate your setup, integrations, and conversational flows without incurring costs or using concurrency slots. Set `test_mode: true` when creating a conversation. Learn more → ## Enhancements * **Fuzzy Search for Personas:** Search now supports fuzzy matching for personas, allowing users to find results based on partial matches of UUIDs or names. ## New Features * **Memories:** CVI now remembers context across conversations. Every conversation builds on the last with full context and time/date awareness, enabling use cases like adaptive tutoring, mentorship, and recurring consultations. Learn more → * **Knowledge Base (RAG):** Bring your own data to conversations instantly. Upload documents or links and get grounded answers with \~30ms retrieval latency. Power AI recruiters, support agents, travel guides, and more with domain-specific knowledge. Learn more → * **Objectives & Guardrails:** Define clear goals, branching logic, and measurable outcomes for your personas while keeping conversations safe, compliant, and on-brand. Ideal for complex workflows and regulated industries. Learn more → * **Persona Builder:** A guided creation flow in the Developer Portal to shape AI personas with goals, behaviors, and style — then test or launch within minutes. ## New Features * **Events Console:** A new events console in the Developer Portal lets you monitor everything happening during a conversation in real time — from message flows to system activity. * **Conversation Transcripts & Perception Analysis:** View full conversation details directly in the Developer Portal, including transcripts with speaker roles and perception analysis showing how your AI persona sees, hears, and responds. ## New Features * **Persona Layer Controls:** Enable or disable layers like Sparrow directly within a Persona and adjust sensitivity settings in real time from the Developer Portal side panel. * **Persona Editing in Developer Portal:** We've added new editing capabilities to help you refine your Personas more efficiently. You can now update system prompt, context, and layers directly in our Developer Portal, plus duplicate existing Personas to quickly create variations or use them as starting points for new projects. Find these new features in your Persona Library at platform.tavus.io. ## Enhancements * **Interaction Events Playground Improvements:** Major updates to the Interaction Events Playground including correct `properties.context` format and append vs overwrite toggle. ## New Features * **Multilingual Settings in Developer Portal:** You can now specify the language of a conversation directly in the Developer Portal, including a new multilingual option for dynamic, real-world interactions. ## New Features * **Llama 4 Support:** Your persona just got even smarter, thanks to Meta's Llama 4 model 🧠 You can start using Llama 4 by specifying `tavus-llama-4` for the LLM `model` value when creating a new persona or updating an existing one. Click here to learn more! ## New Features * **React Component Library:** Developers can build with Tavus even faster now with our pre-defined components 🚀 Click here to learn more! ## New Features * **Multilingual Conversation Support:** CVI now supports dynamic multilingual conversations through automatic language detection. Set `properties.language` to "multilingual" and CVI will automatically detect the user's spoken language and respond in the same language using ASR technology. * **Audio-Only Mode:** CVI now supports audio-only conversations with advanced perception (powered by Raven) and intelligent turn-taking (powered by Sparrow-1). Set `audio_only=true` in your create conversation request to enable streamlined voice-first interactions. ## Enhancements * **Fixed CVI responsiveness issue:** Resolved an issue where CVI would occasionally ignore very brief user utterances. All user inputs, regardless of length, now receive consistent responses. * **Expanded tavus-llama-4 context window:** Increased maximum context window to 32,000 tokens. For optimal performance and response times, we recommend staying under 25,000 tokens. ## Enhancements * Reduced conversation boot time by 58% (p50). ## Changes * Added a new recording requirement to Training from a video : Start the talking segment with a big smile. ## Enhancements * Added echo and respond events to conversational context. ## Enhancements * **Major Phoenix 3 Enhancements for CVI**: * Increased frame rate from 27fps to 32fps, significantly boosting smoothness. * Reduced Phoenix step's warm boot time by 60% (from 5s to 2s). * Lipsync accuracy improved by \~22% based on AVSR metric. * Resolved blurriness and choppiness at conversation start. * Enhanced listening mode with more natural micro expressions (eyebrow movements, subtle gestures). * Greenscreen mode speed boosted by an additional \~1.5fps. * **Enhanced CVI Audio Quality**: Audio clicks significantly attenuated, providing clearer conversational audio. * **Phoenix 3 Visual Artifacts Fix**: Resolved visual artifacts in 4K videos on Apple devices, eliminating black spot artifacts in thumbnails. ## New Features * Launched LiveKit Integration : With Tavus video agents now integrated into LiveKit, you can add humanlike video responses to your voice agents in seconds. * Persona API : Enabled patch updates to personas. ## Enhancements * Resolved TTS (Cartesia) stability issues and addressed hallucination. * **Phoenix 3 Improvements**: * Fixed blinking/jumping issues and black spots in videos. * FPS optimization to resolve static and audio crackling. ## Enhancements * **Replica API**: * Enhanced Error Messaging for Training Videos. * Optimized Auto QA for Training Videos. # Blocks Source: https://docs.tavus.io/sections/conversational-video-interface/component-library/blocks High-level component compositions that combine multiple UI elements into complete interface layouts Blocks are composed React layouts generated by `npx @tavus/cvi-ui@latest add ...`. They are copied into your app, so import paths are relative to your generated component directory. | Block | Add command | Import path pattern | Props | Required context | Generated location pattern | | ----------------------------- | -------------------------------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------- | | `Conversation` full layout | `npx @tavus/cvi-ui@latest add conversation-01` or `add conversation` | `/components/conversation` | `conversationUrl: string`, `onLeave: () => void` | `CVIProvider` ancestor | `/components/conversation.*` plus supporting components/hooks/styles | | `Conversation` minimal layout | `npx @tavus/cvi-ui@latest add conversation-02` | `/components/conversation` | `conversationUrl: string`, `onLeave: () => void` | `CVIProvider` ancestor | `/components/conversation.*` plus supporting components/hooks/styles | | `HairCheck` | `npx @tavus/cvi-ui@latest add hair-check-01` | `/components/hair-check` | `isJoinBtnLoading: boolean`, `onJoin: () => void`, `onCancel?: () => void` | `CVIProvider` ancestor | `/components/hair-check.*` plus device hooks/styles | The docs below use relative imports such as `./components/cvi/components/conversation`. Replace the prefix with the components path configured in your generated `cvi-components.json`. ### Conversation block The Conversation component provides a complete video chat interface for one-to-one conversations with AI replicas. Two variants are available: `conversation-01` (full-featured, default) and `conversation-02` (minimal). #### conversation-01 (full-featured, default) ```bash theme={null} npx @tavus/cvi-ui@latest add conversation-01 ``` The default `Conversation` block — a full-featured video chat surface for one-to-one conversations with AI replicas. **Features:** * **Main Video Display**: Large video area showing the AI replica or screen share * **Top-right Self-View**: Square self-view preview pinned to the top-right of the main video * **Chat**: Slide-in chat side panel with toggle button (built on the [Chat](/sections/conversational-video-interface/component-library/components#chat) module) * **Closed Captions**: Live captions overlay with toggle button (built on the [Closed Captions](/sections/conversational-video-interface/component-library/components#closed-captions) module) * **Screen Sharing**: Automatic switching between replica video and screen share * **Animated Connect / Leave States**: Animated transitions when joining and leaving the call * **Device Controls**: Integrated microphone, camera, and screen share controls * **Error Handling**: Graceful handling of camera/microphone permission errors * **Responsive Layout**: Adaptive design for different screen sizes **Props:** * `conversationUrl` (string): Daily.co room URL for joining * `onLeave` (function): Callback when user leaves the conversation ```tsx theme={null} import { Conversation } from './components/cvi/components/conversation'; ``` ```tsx theme={null} handleLeaveCall()} /> ``` Preview Conversation Block Preview #### conversation-02 (minimal) ```bash theme={null} npx @tavus/cvi-ui@latest add conversation-02 ``` A minimal `Conversation` block — video plus the essential device and leave controls, without chat or captions. Use this when you want to compose your own UI around the call surface. **Features:** * **Main Video Display**: Large video area showing the AI replica or screen share * **Self-View Preview**: Small preview window showing local camera feed * **Device Controls**: Microphone, camera, and screen share toggle buttons * **Leave Button**: Disconnects from the call and fires `onLeave` * **Animated Connect / Leave States**: Animated transitions when joining and leaving the call * **Error Handling**: Graceful handling of camera/microphone permission errors * **Responsive Layout**: Adaptive design for different screen sizes **Props:** * `conversationUrl` (string): Daily.co room URL for joining * `onLeave` (function): Callback when user leaves the conversation ```tsx theme={null} import { Conversation } from './components/cvi/components/conversation'; ``` ```tsx theme={null} handleLeaveCall()} /> ``` Preview Conversation 02 Block Preview ### Hair Check The HairCheck component provides a pre-call interface for users to test and configure their audio/video devices before joining a video chat. ```bash theme={null} npx @tavus/cvi-ui@latest add hair-check-01 ``` The `HairCheck` component provides a pre-call interface for users to test and configure their audio/video devices before joining a video chat. **Features:** * **Device Testing**: Live preview of camera feed with mirror effect * **Permission Management**: Handles camera and microphone permission requests * **Device Controls**: Integrated microphone and camera controls * **Join Interface**: Call-to-action button to join the video chat * **Responsive Design**: Works on both desktop and mobile devices **Props:** * `isJoinBtnLoading` (boolean): Shows loading state on join button * `onJoin` (function): Callback when user clicks join * `onCancel` (function, optional): Callback when user cancels ```tsx theme={null} import { HairCheck } from './components/cvi/components/hair-check'; ``` ```tsx theme={null} ``` Preview Haircheck Block Preview # Components Source: https://docs.tavus.io/sections/conversational-video-interface/component-library/components Learn about our pre-built React components to accelerate integrating the Tavus Conversational Video Interface (CVI) into your application. These pages document **installable** UI pieces from **`@tavus/cvi-ui`** (`npx @tavus/cvi-ui@latest add …`). Wrap your app with **`CVIProvider`** so Daily’s React context and hooks work under this tree. For composed layouts see [Blocks](/sections/conversational-video-interface/component-library/blocks), for state hooks see [Hooks](/sections/conversational-video-interface/component-library/hooks), and for init + embed flows see [Embed CVI](/sections/integrations/embedding-cvi). | Module | Add command | Import path pattern | Exports | Props / parameters | Required context | Generated location pattern | | ----------------- | ---------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------ | | `cvi-provider` | `npx @tavus/cvi-ui@latest add cvi-provider` | `/components/cvi-provider` | `CVIProvider` | `children: ReactNode` | None; this creates the Daily provider context | `/components/cvi-provider.*` | | `audio-wave` | `npx @tavus/cvi-ui@latest add audio-wave` | `/components/audio-wave` | `AudioWave` | `id: string` participant/session ID | `CVIProvider` ancestor and active Daily call | `/components/audio-wave.*` | | `device-select` | `npx @tavus/cvi-ui@latest add device-select` | `/components/device-select` | `MicSelectBtn`, `CameraSelectBtn`, `ScreenShareButton` | No component props | `CVIProvider` ancestor and active Daily call | `/components/device-select.*` | | `media-controls` | `npx @tavus/cvi-ui@latest add media-controls` | `/components/media-controls` | `MicToggleButton`, `CameraToggleButton`, `ScreenShareButton` | No component props | `CVIProvider` ancestor and active Daily call | `/components/media-controls.*` | | `closed-captions` | `npx @tavus/cvi-ui@latest add closed-captions` | `/components/closed-captions` | `ClosedCaptionsProvider`, `ClosedCaptionsButton`, `ClosedCaptions` | Provider: `children`, `defaultEnabled?: boolean` | `CVIProvider`; wrap caption UI in `ClosedCaptionsProvider` | `/components/closed-captions.*` | | `chat` | `npx @tavus/cvi-ui@latest add chat` | `/components/chat` | `ChatProvider`, `ChatButton`, `ChatPanel` | Provider: `children`, `defaultOpen?: boolean` | `CVIProvider`; wrap chat UI in `ChatProvider` | `/components/chat.*` | `CVIProvider` is the React wrapper that makes Daily React context available. Components and hooks that read call state must render under it. ### CVI Provider The `CVIProvider` component wraps your app with the Daily.co provider context, enabling all Daily React hooks and components to function. ```bash theme={null} npx @tavus/cvi-ui@latest add cvi-provider ``` The `CVIProvider` component wraps your app with the Daily.co provider context, enabling all Daily React hooks and components to function. **Features:** * Provides Daily.co context to all child components * Required for using Daily React hooks and video/audio components * Simple wrapper for app-level integration **Props:** * `children` (ReactNode): Components to be wrapped by the provider ```tsx theme={null} import { CVIProvider } from './cvi-provider'; ``` ```tsx theme={null} {/* your app components */} ``` Import paths such as `./cvi-provider` are **relative to your file** and to where the CLI copied components. Paths in [Embed CVI](/sections/integrations/embedding-cvi) (for example `./components/cvi/components/cvi-provider`) show another valid layout—adjust imports to match your project tree. ### AudioWave The `AudioWave` component provides real-time audio level visualization for video chat participants, displaying animated bars that respond to audio input levels. ```bash theme={null} npx @tavus/cvi-ui@latest add audio-wave ``` The `AudioWave` component provides real-time audio level visualization for video chat participants, displaying animated bars that respond to audio input levels. **Features:** * **Real-time Audio Visualization**: Three animated bars that respond to audio levels * **Active Speaker Detection**: Visual distinction between active and inactive speakers * **Performance Optimized**: Uses `requestAnimationFrame` for smooth animations * **Responsive Design**: Compact circular design that fits well in video previews * **Audio Level Scaling**: Intelligent volume scaling for consistent visual feedback **Props:** * `id` (string): The participant's session ID to monitor audio levels for ```tsx theme={null} import { AudioWave } from './audio-wave'; ``` ```tsx theme={null} ``` ### Device Select The `device-select` module provides advanced device selection controls, including dropdowns for choosing microphones and cameras, and integrated toggle buttons. ```bash theme={null} npx @tavus/cvi-ui@latest add device-select ``` The `device-select` module provides advanced device selection controls, including dropdowns for choosing microphones and cameras, and integrated toggle buttons. **Exported Components:** * **`MicSelectBtn`**: Microphone toggle button with device selection * **`CameraSelectBtn`**: Camera toggle button with device selection * **`ScreenShareButton`**: Button to toggle screen sharing **Features:** * Integrated device selection and toggling * Dropdowns for camera/microphone selection * Visual state indicators and accessibility support * Uses Daily.co device management hooks * CSS modules for styling ```tsx theme={null} import { MicSelectBtn, CameraSelectBtn, ScreenShareButton } from './device-select'; ``` ```tsx theme={null} ``` **`ScreenShareButton`** exists in both **`device-select`** and **`media-controls`**. They are different exports from different modules—import from the path that matches the `npx @tavus/cvi-ui@latest add device-select` or `… add media-controls` command you ran. ### Media Controls The `media-controls` module provides simple toggle buttons for microphone, camera, and screen sharing, designed for direct use in video chat interfaces. ```bash theme={null} npx @tavus/cvi-ui@latest add media-controls ``` The `media-controls` module provides simple toggle buttons for microphone, camera, and screen sharing, designed for direct use in video chat interfaces. **Exported Components:** * **`MicToggleButton`**: Toggles microphone mute/unmute state * **`CameraToggleButton`**: Toggles camera on/off * **`ScreenShareButton`**: Toggles screen sharing on/off **Features:** * Simple, accessible toggle buttons * Visual state indicators (muted, unmuted, on/off) * Disabled state when device is not ready * Uses Daily.co hooks for device state * CSS modules for styling ```tsx theme={null} import { MicToggleButton, CameraToggleButton, ScreenShareButton } from './media-controls'; ``` ```tsx theme={null} ``` ### Closed Captions The `closed-captions` module renders live captions for both the user and the replica, plus a toggle button and a context provider that lets multiple components share the on/off state. ```bash theme={null} npx @tavus/cvi-ui@latest add closed-captions ``` The `closed-captions` module renders live captions for both the user and the replica, plus a toggle button and a context provider that lets multiple components share the on/off state. **Exported Components:** * **`ClosedCaptionsProvider`**: Context provider that owns the captions on/off state. Wrap your conversation tree with it. * **`ClosedCaptionsButton`**: Toggle button that flips captions on and off (uses `aria-pressed`). * **`ClosedCaptions`**: Overlay that displays the active caption with the speaker's role label. Shows the latest 3 lines and auto-clears 2 seconds after the final utterance. **Features:** * Streams captions from `conversation.utterance.streaming` for both `user` and `replica` roles * Auto-clears the caption after each final utterance * Anchors to the bottom of the overlay so the most recent text is always visible * CSS modules for styling, customizable via `--cc-line-height` and `--cc-max-lines` **Provider Props:** * `children` (ReactNode): Components to be wrapped by the provider * `defaultEnabled` (boolean, optional): Initial captions on/off state. Defaults to `false`. ```tsx theme={null} import { ClosedCaptions, ClosedCaptionsButton, ClosedCaptionsProvider, } from './closed-captions'; ``` ```tsx theme={null}
{/* main video, self-view, etc. */}
{/* other controls */}
``` ### Chat The `chat` module renders a slide-in side panel for text chat alongside the live conversation, plus a toggle button and a context provider that owns the panel's open/closed state. ```bash theme={null} npx @tavus/cvi-ui@latest add chat ``` The `chat` module renders a slide-in side panel for text chat alongside the live conversation, plus a toggle button and a context provider that owns the panel's open/closed state. **Exported Components:** * **`ChatProvider`**: Context provider that owns the chat panel's open/closed state. Wrap your conversation tree with it. * **`ChatButton`**: Toggle button that opens and closes the chat panel (uses `aria-expanded` and `aria-controls`). * **`ChatPanel`**: Slide-in side panel containing the message list and composer. Renders a persistent ARIA live region so screen readers announce new messages, and is set to `inert` while closed so its contents stay out of the tab order. **Features:** * **Message list**: Renders the running transcript of `user` and `replica` messages tracked by [`useChat`](/sections/conversational-video-interface/component-library/hooks#usechat), with optimistic local echo for messages the user just sent. * **Composer**: Multi-line textarea with **Enter to send**, **Shift+Enter for newline**, and IME-safe input handling so composition (e.g. CJK input) is not interrupted by the send shortcut. **Provider Props:** * `children` (ReactNode): Components to be wrapped by the provider * `defaultOpen` (boolean, optional): Initial open/closed state of the chat panel. Defaults to `false`. ```tsx theme={null} import { ChatButton, ChatPanel, ChatProvider, } from './chat'; ``` ```tsx theme={null}
{/* main video, self-view, etc. */}
{/* other controls */}
``` # Hooks Source: https://docs.tavus.io/sections/conversational-video-interface/component-library/hooks See what hooks Tavus supports for managing video calls, media controls, participant management, and conversation events. Hooks are generated source files copied into your app by `npx @tavus/cvi-ui@latest add ...`. Import them from your generated hooks directory and render them under `CVIProvider` unless the hook explicitly only creates request helpers. | Hook | Add command | Import path pattern | Parameters | Return values | Required context | Generated location pattern | | ------------------------- | -------------------------------- | ---------------------------------------------------- | ----------------- | ------------------------------------------------------------------ | ----------------------------- | ------------------------------------------------------ | | `useCVICall` | `add use-cvi-call` | `/hooks/use-cvi-call` | None | `joinCall`, `leaveCall` | `CVIProvider` | `/hooks/use-cvi-call.*` | | `useStartHaircheck` | `add use-start-haircheck` | `/hooks/use-start-haircheck` | None | Permission booleans, `requestPermissions` | `CVIProvider` | `/hooks/use-start-haircheck.*` | | `useLocalCamera` | `add use-local-camera` | `/hooks/use-local-camera` | None | `onToggleCamera`, `isCamReady`, `isCamMuted`, `localSessionId` | `CVIProvider` and active call | `/hooks/use-local-camera.*` | | `useLocalMicrophone` | `add use-local-microphone` | `/hooks/use-local-microphone` | None | `onToggleMicrophone`, `isMicReady`, `isMicMuted`, `localSessionId` | `CVIProvider` and active call | `/hooks/use-local-microphone.*` | | `useLocalScreenshare` | `add use-local-screenshare` | `/hooks/use-local-screenshare` | None | `onToggleScreenshare`, `isScreenSharing`, `localSessionId` | `CVIProvider` and active call | `/hooks/use-local-screenshare.*` | | `useRequestPermissions` | `add use-request-permissions` | `/hooks/use-request-permissions` | None | `requestPermissions` | `CVIProvider` | `/hooks/use-request-permissions.*` | | `useReplicaIDs` | `add use-replica-ids` | `/hooks/use-replica-ids` | None | `string[]` | `CVIProvider` and active call | `/hooks/use-replica-ids.*` | | `useRemoteParticipantIDs` | `add use-remote-participant-ids` | `/hooks/use-remote-participant-ids` | None | `string[]` | `CVIProvider` and active call | `/hooks/use-remote-participant-ids.*` | | `useObservableEvent` | `add cvi-events-hooks` | `/hooks/cvi-events-hooks` | `callback(event)` | None | `CVIProvider` and active call | `/hooks/cvi-events-hooks.*` | | `useClosedCaption` | `add use-closed-caption` | `/hooks/use-closed-caption` | None | `ClosedCaption` or `null` | `CVIProvider` and active call | `/hooks/use-closed-caption.*` | | `useSendAppMessage` | `add cvi-events-hooks` | `/hooks/cvi-events-hooks` | None | `sendMessage(message)` | `CVIProvider` and active call | `/hooks/cvi-events-hooks.*` | | `useChat` | `add use-chat` | `/hooks/use-chat` | None | `messages`, `sendMessage(text)` | `CVIProvider` and active call | `/hooks/use-chat.*` | ## 🔧 Core Call Management ### useCVICall Essential hook for joining and leaving video calls. ```bash theme={null} npx @tavus/cvi-ui@latest add use-cvi-call ``` A React hook that provides comprehensive call management functionality for video conversations. This hook handles the core lifecycle of video calls, including connection establishment, room joining, and proper cleanup when leaving calls. **Purpose:** * Manages call join/leave operations with proper state management * Handles connection lifecycle and cleanup * Provides simple interface for call control **Return Values:** * `joinCall` (function): Function to join a call by URL - handles Daily.co room connection * `leaveCall` (function): Function to leave the current call - properly disconnects and cleans up resources ```tsx theme={null} import { useCVICall } from './hooks/use-cvi-call'; ``` ```tsx theme={null} const CallManager = () => { const { joinCall, leaveCall } = useCVICall(); const handleJoin = () => { joinCall({ url: 'https://your-daily-room-url' }); }; return (
); }; ``` ### useStartHaircheck A React hook that manages device permissions and camera initialization for the hair-check component. ```bash theme={null} npx @tavus/cvi-ui@latest add use-start-haircheck ``` A React hook that manages device permissions and camera initialization for the hair-check component. **Purpose:** * Monitors device permission states * Starts camera and microphone when appropriate * Provides permission state for UI conditional rendering * Handles permission request flow **Return Values:** * `isPermissionsPrompt` (boolean): Browser is prompting for device permission * `isPermissionsLoading` (boolean): Permissions are being processed or camera is initializing * `isPermissionsGranted` (boolean): Device permission granted * `isPermissionsDenied` (boolean): Device permission denied * `requestPermissions` (function): Function to request camera and microphone permissions ```tsx theme={null} import { useStartHaircheck } from './hooks/use-start-haircheck'; ``` ```tsx theme={null} const HairCheckComponent = () => { const { isPermissionsPrompt, isPermissionsLoading, isPermissionsGranted, isPermissionsDenied, requestPermissions } = useStartHaircheck(); useEffect(() => { requestPermissions(); }, []); return (
{isPermissionsLoading && } {isPermissionsPrompt && } {isPermissionsDenied && } {isPermissionsGranted && }
); }; ``` *** ## 🎥 Media Controls ### useLocalCamera A React hook that provides local camera state and toggle functionality. ```bash theme={null} npx @tavus/cvi-ui@latest add use-local-camera ``` A React hook that provides local camera state and toggle functionality. **Purpose:** * Manages local camera state (on/off) * Tracks camera permission and ready state **Return Values:** * `onToggleCamera` (function): Function to toggle camera on/off * `isCamReady` (boolean): Camera permission is granted and ready * `isCamMuted` (boolean): Camera is currently turned off * `localSessionId` (string): Local session ID ```tsx theme={null} import { useLocalCamera } from './hooks/use-local-camera'; ``` ```tsx theme={null} const CameraControls = () => { const { onToggleCamera, isCamReady, isCamMuted } = useLocalCamera(); return ( ); }; ``` ### useLocalMicrophone A React hook that provides local microphone state and toggle functionality. ```bash theme={null} npx @tavus/cvi-ui@latest add use-local-microphone ``` A React hook that provides local microphone state and toggle functionality. **Purpose:** * Manages local microphone state (on/off) * Tracks microphone permission and ready state **Return Values:** * `onToggleMicrophone` (function): Function to toggle microphone on/off * `isMicReady` (boolean): Microphone permission is granted and ready * `isMicMuted` (boolean): Microphone is currently turned off * `localSessionId` (string): Local session ID ```tsx theme={null} import { useLocalMicrophone } from './hooks/use-local-microphone'; ``` ```tsx theme={null} const MicrophoneControls = () => { const { onToggleMicrophone, isMicReady, isMicMuted } = useLocalMicrophone(); return ( ); }; ``` ### useLocalScreenshare A React hook that provides local screen sharing state and toggle functionality. ```bash theme={null} npx @tavus/cvi-ui@latest add use-local-screenshare ``` A React hook that provides local screen sharing state and toggle functionality. **Purpose:** * Manages screen sharing state (on/off) * Provides screen sharing toggle function * Handles screen share start/stop with optimized display media options **Return Values:** * `onToggleScreenshare` (function): Function to toggle screen sharing on/off * `isScreenSharing` (boolean): Whether screen sharing is currently active * `localSessionId` (string): Local session ID **Display Media Options:** When starting screen share, the hook uses the following optimized settings: * **Audio**: Disabled (false) * **Self Browser Surface**: Excluded * **Surface Switching**: Included * **Video Resolution**: 1920x1080 ```tsx theme={null} import { useLocalScreenshare } from './hooks/use-local-screenshare'; ``` ```tsx theme={null} const ScreenShareControls = () => { const { onToggleScreenshare, isScreenSharing } = useLocalScreenshare(); return ( ); }; ``` ### useRequestPermissions A React hook that requests camera and microphone permissions with optimized audio processing settings. ```bash theme={null} npx @tavus/cvi-ui@latest add use-request-permissions ``` A React hook that requests camera and microphone permissions with optimized audio processing settings. **Purpose:** * Requests camera and microphone permissions from the user * Starts camera and audio with specific configuration * Applies noise cancellation audio processing * Provides a clean interface for permission requests **Return Values:** * `requestPermissions` (function): Function to request camera and microphone permissions **Configuration:** When requesting permissions, the hook uses the following settings: * **Video**: Started on (startVideoOff: false) * **Audio**: Started on (startAudioOff: false) * **Audio Source**: Default system audio input * **Audio Processing**: Noise cancellation enabled ```tsx theme={null} import { useRequestPermissions } from './hooks/use-request-permissions'; ``` ```tsx theme={null} const PermissionRequest = () => { const requestPermissions = useRequestPermissions(); const handleRequestPermissions = async () => { try { await requestPermissions(); console.log('Permissions granted successfully'); } catch (error) { console.error('Failed to get permissions:', error); } }; return ( ); }; ``` *** ## 👥 Participant Management ### useReplicaIDs A React hook that returns the IDs of all Tavus replica participants in a call. ```bash theme={null} npx @tavus/cvi-ui@latest add use-replica-ids ``` A React hook that returns the IDs of all Tavus replica participants in a call. **Purpose:** * Filters and returns participant IDs where `user_id` includes 'tavus-replica' **Return Value:** * `string[]` — Array of replica participant IDs ```tsx theme={null} import { useReplicaIDs } from './hooks/use-replica-ids'; ``` ```tsx theme={null} const ids = useReplicaIDs(); // ids is an array of participant IDs for Tavus replicas ``` ### useRemoteParticipantIDs A React hook that returns the IDs of all remote participants in a call. ```bash theme={null} npx @tavus/cvi-ui@latest add use-remote-participant-ids ``` A React hook that returns the IDs of all remote participants in a call. **Purpose:** * Returns participant IDs for all remote participants (excluding local user) **Return Value:** * `string[]` — Array of remote participant IDs ```tsx theme={null} import { useRemoteParticipantIDs } from './hooks/use-remote-participant-ids'; ``` ```tsx theme={null} const remoteIds = useRemoteParticipantIDs(); // remoteIds is an array of remote participant IDs ``` *** ## 💬 Conversation & Events ### useObservableEvent A React hook that listens for CVI app messages and provides a callback mechanism for handling various conversation events. ```bash theme={null} npx @tavus/cvi-ui@latest add cvi-events-hooks ``` A React hook that listens for CVI app messages and provides a callback mechanism for handling various conversation events. **Purpose:** * Listens for app messages from the Daily.co call mapped to CVI events * Handles various conversation event types (utterances, tool calls, speaking events, etc.) * Provides type-safe event handling for CVI interactions **Parameters:** * `callback` (function): Function called when app messages are received **Event Types:** This hook handles all CVI conversation events. For detailed information about each event type, see the [Interaction Events overview](/sections/conversational-video-interface/interactions-protocols/overview). ```tsx theme={null} import { useObservableEvent } from './hooks/cvi-events-hooks'; ``` ```tsx theme={null} const ConversationHandler = () => { useObservableEvent((event) => { switch (event.event_type) { case 'conversation.utterance': console.log('Speech:', event.properties.speech); break; case 'conversation.replica.started_speaking': console.log('Replica started speaking'); break; case 'conversation.user.stopped_speaking': console.log('User stopped speaking'); break; } }); return
Listening for conversation events...
; }; ``` ### useClosedCaption A React hook that returns the latest closed caption with the speaker's role and text. ```bash theme={null} npx @tavus/cvi-ui@latest add use-closed-caption ``` A React hook that returns the latest closed caption with the speaker's role and text. Subscribes to `conversation.utterance.streaming` events for both `user` and `replica` roles and exposes the latest caption to your UI. **Purpose:** * Streams captions for both the user and the replica from `conversation.utterance.streaming` * Updates progressively as either party speaks * Auto-clears the caption 2 seconds after a `final` utterance * Returns `null` when no caption is currently being shown **Return Value:** * `ClosedCaption | null` where `ClosedCaption` is `{ role: "user" | "replica"; text: string }` ```tsx theme={null} import { useClosedCaption } from './hooks/use-closed-caption'; ``` ```tsx theme={null} const Captions = () => { const caption = useClosedCaption(); if (!caption) return null; return (
{caption.role === 'replica' ? 'Replica' : 'You'} {caption.text}
); }; ``` ### useSendAppMessage A React hook that provides a function to send CVI app messages to other participants in the call. ```bash theme={null} npx @tavus/cvi-ui@latest add cvi-events-hooks ``` A React hook that provides a function to send CVI app messages to other participants in the call. **Purpose:** * Sends various types of conversation messages to the CVI system * Supports echo, respond, interrupt, and context management messages * Provides type-safe message sending with proper validation * Enables real-time communication with Tavus replicas and conversation management **Return Value:** * `(message: SendAppMessageProps) => void` - Function that sends the message when called **Message Types:** This hook supports all CVI interaction types. For detailed information about each interaction type and their properties, see the [Interaction Events overview](/sections/conversational-video-interface/interactions-protocols/overview). ```tsx theme={null} import { useSendAppMessage } from './hooks/cvi-events-hooks'; ``` ```tsx theme={null} const MessageSender = () => { const sendMessage = useSendAppMessage(); // Send a text echo const sendTextEcho = () => { sendMessage({ message_type: "conversation", event_type: "conversation.echo", conversation_id: "conv-123", properties: { modality: "text", text: "Hello, world!", audio: "", sample_rate: 16000, inference_id: "inf-456", done: true } }); }; // Send a text response const sendResponse = () => { sendMessage({ message_type: "conversation", event_type: "conversation.respond", conversation_id: "conv-123", properties: { text: "This is my response to the conversation." } }); }; return (
); }; ``` ### useChat A React hook that powers a chat experience on top of the live conversation. It tracks the running transcript and provides a function to send a user turn back to the replica. ```bash theme={null} npx @tavus/cvi-ui@latest add use-chat ``` A React hook that powers a chat experience on top of the live conversation. Subscribes to Daily app messages and tracks `conversation.utterance` events from both `user` and `replica` roles, and exposes a `sendMessage` function that dispatches `conversation.respond`. **Purpose:** * Builds a chronological transcript of `user` and `replica` messages from `conversation.utterance` events * Optimistically appends locally sent messages so the UI updates immediately, then reconciles each pending message with the matching server-side utterance using `inference_id` * Dispatches `conversation.respond` when the user sends a chat message * Designed to back the [`Chat`](/sections/conversational-video-interface/component-library/components#chat) components (`ChatProvider`, `ChatPanel`, `ChatButton`) **Return Values:** * `messages` (`ChatMessage[]`): Ordered transcript where `ChatMessage` is `{ id: string; role: "user" | "replica"; text: string; inference_id?: string; pending?: boolean }` * `sendMessage` (`(text: string) => void`): Sends a user turn — appends a pending local echo to `messages` and dispatches `conversation.respond`. The pending entry is reconciled (and `pending` cleared) when the matching utterance arrives by `inference_id`. ```tsx theme={null} import { useChat } from './hooks/use-chat'; ``` ```tsx theme={null} const Chat = () => { const { messages, sendMessage } = useChat(); const [draft, setDraft] = useState(''); const onSubmit = () => { const text = draft.trim(); if (!text) return; sendMessage(text); setDraft(''); }; return (
    {messages.map((m) => (
  • {m.role === 'replica' ? 'Replica' : 'You'}: {m.text}
    • ))}