# Authentication Source: https://docs.tavus.io/api-reference/authentication Generate an API key in the PAL Maker 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 PAL Maker 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 face. 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 '{ "face_id": "r90bbd427f71", "pal_id": "pdac61133ac5", "conversation_name": "Interview User" }' ``` # List Canvas Interactions Source: https://docs.tavus.io/api-reference/canvas-interactions/list-canvas-interactions get /v2/conversations/{conversation_id}/canvas/interactions Returns every Canvas interaction recorded for a conversation, oldest first. Uses the same field shape as the `canvas.interaction` webhook's `properties` object. Readable during and after the conversation. Call from your backend with your API key - not from the browser. See [Canvas interactions](/sections/conversational-video-interface/magic-canvas/api/interactions). For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. See [Canvas interactions](/sections/conversational-video-interface/magic-canvas/api/interactions) for webhook delivery and reconciliation guidance. # Record Canvas Interaction Source: https://docs.tavus.io/api-reference/canvas-interactions/record-canvas-interaction post /v2/conversations/{conversation_id}/canvas/interactions Record a Magic Canvas interaction (submit, skip, dismiss, clear, error, or heartbeat) while a conversation is **active**. The Tavus-hosted embed and `@tavus/cvi-ui` post interactions for you. Call this endpoint directly only if you build your own renderer. **Authentication:** No API key is required while the conversation is active. Never put your Tavus API key in a browser. Once the conversation ends, every POST is rejected. **Idempotency:** Retries with the same `(conversation_id, interaction_id)` and identical `tool_call_id`, `component`, `component_version`, `type`, and `value` return `200` without firing a second webhook. `metadata` is excluded from the match. **Rate limiting:** 120 POSTs per 60-second window per `(client IP, conversation_id)`. Exceeding the limit returns `429` with `{ "error": "Too many requests" }` and a `Retry-After` header (seconds until the window resets). Custom renderers posting `heartbeat` interactions count toward this limit. See [Canvas interactions](/sections/conversational-video-interface/magic-canvas/api/interactions) for per-component `value` rules, webhook delivery, and the full error catalog. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. See [Canvas interactions](/sections/conversational-video-interface/magic-canvas/api/interactions) for per-component `value` rules, webhook delivery, and the full error catalog. # 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 face, powered by a PAL 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 Deployment Source: https://docs.tavus.io/api-reference/deployments/create-deployment post /v2/deployments Create a managed deployment for the widget, embed, or landing-page channel. See [Deployments overview](/sections/deployments/overview). For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete Deployment Source: https://docs.tavus.io/api-reference/deployments/delete-deployment delete /v2/deployments/{deployment_id} For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # End Deployment Conversation Source: https://docs.tavus.io/api-reference/deployments/end-deployment-conversation post /v2/deployments/{deployment_id}/conversations/{conversation_id}/end Ends an active conversation started through a deployment. No API key required in the browser. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Deployment Source: https://docs.tavus.io/api-reference/deployments/get-deployment get /v2/deployments/{deployment_id} For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Deployment Init Config Source: https://docs.tavus.io/api-reference/deployments/get-deployment-init get /v2/deployments/{deployment_id}/init Public endpoint called when a widget or embed mounts. Returns customization, limits, captcha settings, and availability. Does **not** return a PAL identifier - the widget/embed runtime never reads it from `/init`. No API key required. Origin and browser-context checks apply for non-preview callers. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Deployments Source: https://docs.tavus.io/api-reference/deployments/list-deployments get /v2/deployments List deployments owned by the authenticated user. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Patch Deployment Source: https://docs.tavus.io/api-reference/deployments/patch-deployment patch /v2/deployments/{deployment_id} Apply a [JSON Patch](https://jsonpatch.com/) array to the deployment document. Send the `ETag` from GET as `If-Match` for optimistic concurrency. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Start Deployment Conversation Source: https://docs.tavus.io/api-reference/deployments/start-deployment-conversation post /v2/deployments/{deployment_id}/start Creates a conversation for a deployment. Returns the same fields as [Create Conversation](/api-reference/conversations/create-conversation). No API key required in the browser. Password, Turnstile, and call-limit checks apply for public callers. 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 PALs 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 Face Source: https://docs.tavus.io/api-reference/faces/create-face post /v2/faces Creates a new face from training video or image URL for use in conversations. See [Which training path?](/sections/faces/which-training-path) for footage requirements and [Face overview](/sections/faces/overview#platform-policies) for rights and permissions. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete Face Source: https://docs.tavus.io/api-reference/faces/delete-face delete /v2/faces/{face_id} Deletes a Face by its unique ID; deleted faces cannot be used in a conversation. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get Face Source: https://docs.tavus.io/api-reference/faces/get-face get /v2/faces/{face_id} This endpoint returns a single Face by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Faces Source: https://docs.tavus.io/api-reference/faces/list-faces get /v2/faces Returns all faces (photorealistic likenesses trained with Phoenix) created by the account associated with the API key. **Legacy:** `/v2/replicas` and `replica_id` / `replica_ids` remain supported as aliases. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Rename Face Source: https://docs.tavus.io/api-reference/faces/patch-face-name patch /v2/faces/{face_id}/name This endpoint renames a single Face by its unique identifier. 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 PAL directly via `guardrail_ids` or by tag via `guardrail_tags` on [Create PAL](/api-reference/pals/create-pal). See [Deprecated 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. PALs 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. The `legacy=true` behavior returns the deprecated guardrail set list. 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 PAL. 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 face. ## Getting Started with Tavus APIs Tavus APIs let you build a **Conversational Video Interface (CVI)**: real-time video conversations with a PAL. Each session pairs a **PAL** (behavior, knowledge, pipeline) with a **face** (photorealistic visual, Phoenix). **Terminology update:** Tavus now uses **PAL** (behavior, knowledge, and pipeline configuration) and **Face** (visual appearance and voice) in the API and docs. Legacy names **persona** and **replica** still work on existing endpoints and request fields (`/v2/personas`, `/v2/replicas`, `persona_id`, `replica_id`, and related aliases) for backward compatibility. 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 PAL's behavior, tone, and knowledge. Train a lifelike digital face from a short video or headshot image. Create a real-time video call session with your PAL. A typical path: [Authentication](/api-reference/authentication), then [Create PAL](/api-reference/pals/create-pal) (`POST /v2/pals`), [Create Face](/api-reference/faces/create-face) (`POST /v2/faces`), 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). # Attach Skill to PAL Source: https://docs.tavus.io/api-reference/pal-skills/attach-skill-to-pal put /v2/pals/{pal_id}/skills/{skill_id} Attach a skill to a PAL, or overwrite the configuration of an existing attachment. The skill is active on the PAL's next conversation. Skills with no configuration (like `internet_search`) take an empty body or `{"config": {}}`. See [Skills](/sections/conversational-video-interface/skills/overview) for each skill's configuration fields. For `magic_canvas`, see [Canvas configuration](/sections/conversational-video-interface/magic-canvas/api/configuration). For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Detach Skill from PAL Source: https://docs.tavus.io/api-reference/pal-skills/detach-skill-from-pal delete /v2/pals/{pal_id}/skills/{skill_id} Detach a skill from a PAL. The skill no longer applies to the PAL's future conversations. The skill itself stays in the registry and can be re-attached at any time. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get PAL Skill Source: https://docs.tavus.io/api-reference/pal-skills/get-pal-skill get /v2/pals/{pal_id}/skills/{skill_id} Retrieve a single skill attachment on a PAL. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List PAL Skills Source: https://docs.tavus.io/api-reference/pal-skills/list-pal-skills get /v2/pals/{pal_id}/skills List the skills attached to a PAL. The response is an object keyed by `skill_id`. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Replace PAL Skills Source: https://docs.tavus.io/api-reference/pal-skills/replace-pal-skills put /v2/pals/{pal_id}/skills Replace a PAL's entire skill set in one call. Skills not present in the request are detached. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Update PAL Skill Source: https://docs.tavus.io/api-reference/pal-skills/update-pal-skill patch /v2/pals/{pal_id}/skills/{skill_id} Merge changes into an existing skill attachment's configuration. Fields you pass replace the existing values, fields you omit are preserved, and fields set to `null` are removed. The merged configuration is validated against the skill's config schema. Unlike [Attach Skill to PAL](/api-reference/pal-skills/attach-skill-to-pal), this endpoint cannot create a new attachment - the skill must already be attached. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Attach Tools To PAL Source: https://docs.tavus.io/api-reference/pal-tools/attach-tools-to-pal post /v2/pals/{pal_id}/tools Attach one or more tools (by `tool_id`) to a PAL. A PAL can have at most 50 attached tools. Attaching a tool that is already attached is idempotent - it is reported in the response alongside any newly-attached tools. # Detach Tool From PAL Source: https://docs.tavus.io/api-reference/pal-tools/detach-tool-from-pal delete /v2/pals/{pal_id}/tools/{tool_id} Detach a tool from a PAL. The tool itself is not deleted - it remains available to attach to other PALs. # List PAL Tools Source: https://docs.tavus.io/api-reference/pal-tools/list-pal-tools get /v2/pals/{pal_id}/tools List all standalone tools currently attached to a PAL. Inline tools defined under `PAL.layers.llm.tools` and built-in system tools are not returned here - only tools created via [Create Tool](/api-reference/tools/create-tool) and attached to this PAL. # Check Conferencing Username Availability Source: https://docs.tavus.io/api-reference/pals/check-conferencing-username get /v2/pals/check-username Check whether a conferencing `username` is available on `tavusinvite.com` before creating or patching a PAL. See [Google Meet](/sections/conversational-video-interface/pal/meetings). For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. See [Google Meet / Zoom](/sections/conversational-video-interface/pal/meetings) for username rules, allowlists, and scheduling via calendar invite. # Create PAL Source: https://docs.tavus.io/api-reference/pals/create-pal post /v2/pals Creates a PAL and configures how it behaves in CVI for every conversation that uses that PAL. **`default_face_id` is required** on `POST /v2/pals` (unlike the legacy `POST /v2/personas` path, where `default_replica_id` was optional). **Legacy:** `/v2/personas` and `persona_id` / `default_replica_id` remain supported as aliases. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Delete PAL Source: https://docs.tavus.io/api-reference/pals/delete-pal delete /v2/pals/{pal_id} This endpoint deletes a single PAL by its unique identifier. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Get PAL Source: https://docs.tavus.io/api-reference/pals/get-pal get /v2/pals/{pal_id} Returns a single PAL by its unique identifier. By default this endpoint returns the **live** PAL — the version that powers conversations, deployments, and the public API. If the PAL has an active [PAL Builder](https://maker.tavus.io/dev) draft with unpublished changes, add `?source=draft` to read the draft body without publishing it. See [Draft vs live PALs](/sections/conversational-video-interface/pal/draft-and-live) for the full model. Regardless of `source`, `layers.conferencing` is always returned from the live PAL, because conferencing is deployment config that is owned by the live row (see [PATCH PAL](/api-reference/pals/patch-pal)). For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. Returns the **live** PAL by default. If the PAL has an active [PAL Builder](https://maker.tavus.io/dev) draft, add `?source=draft` to read the unpublished draft body without affecting live traffic. Draft views include a `publish_url` for [Publish PAL](/api-reference/pals/publish-pal). `layers.conferencing` is always the live value. See [Draft vs live PALs](/sections/conversational-video-interface/pal/draft-and-live). # List PALs Source: https://docs.tavus.io/api-reference/pals/list-pals get /v2/pals This endpoint returns a list of all PALs 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 PAL Source: https://docs.tavus.io/api-reference/pals/patch-pal patch /v2/pals/{pal_id} Update specific fields of a PAL using [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) operations. ### Draft vs live routing If the PAL has an active [PAL Builder](https://maker.tavus.io/dev) draft, this endpoint **routes to the draft by default**. Live conversations, deployments, and public reads continue to use the previously-published version until you publish (`POST /v2/pals/{pal_id}/publish`) or repeat the request with `?target=live`. PALs without an active draft are unaffected — the patch applies to the live row as it always did. This default was introduced so an API patch and a PAL Maker edit stay in sync: the Builder reads the draft row, so a PATCH that skipped the draft would produce an editor that still shows the pre-patch state. To bypass the draft, pass `?target=live` — this applies the edit to the live row and resyncs the retained draft from live. Any unpublished draft edits are discarded. The response always includes `edit_target`, `edited_pal_id`, `live_pal_id`, `draft_pal_id`, and `routing_message` so you can confirm which row was written. Draft-routed responses also include `publish_url`. See [Draft vs live PALs](/sections/conversational-video-interface/pal/draft-and-live) for the full model. ### `layers.conferencing` is live-owned `layers.conferencing` (the conferencing/Google Meet integration) is deployment config that lives on the live row so meeting invitations continue to work while a draft is open. Regardless of `?target`, any patch that touches `layers.conferencing` (or removes `layers`) is applied to the live PAL and then synced into the open draft, so the draft never carries a stale conferencing config. Consequences: - `?target=draft` with a conferencing op returns `400`. - A single request cannot mix conferencing ops with edits to other fields — split the request in two. - Publishing a stale draft never wipes deployed conferencing config; live conferencing is preserved. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. If the PAL has an active [PAL Builder](https://maker.tavus.io/dev) draft, this endpoint **writes to the draft by default** — live conversations are unaffected until you call [Publish PAL](/api-reference/pals/publish-pal). Draft-routed responses include a `publish_url`. Pass `?target=live` to write directly to live, discard unpublished edits, and resync the retained draft. `layers.conferencing` is always live-owned. See [Draft vs live PALs](/sections/conversational-video-interface/pal/draft-and-live). # Publish PAL Source: https://docs.tavus.io/api-reference/pals/publish-pal post /v2/pals/{pal_id}/publish Publishes the PAL Builder draft associated with this `pal_id`, making its content the live version used by new conversations, deployments, and public reads. Call this after a draft-routed [Patch PAL](/api-reference/pals/patch-pal) response. That response includes a `publish_url` you can use directly. Publishing preserves the live `layers.conferencing` configuration and keeps the draft row available for future Builder edits. If the PAL has no Builder draft, the call is idempotent: Tavus returns the current live PAL. You can pass either the stable live PAL id or its underlying draft id, although integrations should normally keep and publish the stable live `pal_id`. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. Publish after editing a PAL Builder draft through [Patch PAL](/api-reference/pals/patch-pal). The patch response and `GET /v2/pals/{pal_id}?source=draft` both return the exact `publish_url`. Publishing makes those draft changes live for new conversations while preserving live-owned conferencing configuration. # 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/pal/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 PAL 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 PALs. 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. # Get Skill Source: https://docs.tavus.io/api-reference/skills/get-skill get /v2/skills/{skill_id} Retrieve the metadata for a single skill in the registry. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # List Skills Source: https://docs.tavus.io/api-reference/skills/list-skills get /v2/skills List every skill in the registry. Skills are pre-built capabilities authored by Tavus that you can attach to a PAL - see [Skills](/sections/conversational-video-interface/skills/overview). For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. # Create Tool Source: https://docs.tavus.io/api-reference/tools/create-tool post /v2/tools Create a standalone tool that can be attached to one or more PALs via [Attach Tools To PAL](/api-reference/pal-tools/attach-tools-to-pal). **In-call tools** (`trigger_type: in_call`, default) are invoked during the conversation by an LLM (`origin: llm`) or a perception model (`origin: vision` / `origin: audio`). **Post-call actions** (`trigger_type: post_call`) run once after the conversation ends; omit `origin` and set `delivery.api` (HTTPS webhook). See [Post-Call Actions](/sections/conversational-video-interface/pal/post-call-tool). Every tool dispatches via **exactly one** delivery channel: - `delivery.app_message: true` (default) - calls land on your frontend as a `conversation.tool_call` event over the Daily data channel. - `delivery.api` - Tavus makes an HTTPS request to a URL you configure. Supports five auth types and `{placeholder}` templating in the URL path, query string, and body. See [Tools Overview](/sections/conversational-video-interface/pal/tools), [LLM Tool Delivery](/sections/conversational-video-interface/pal/llm-tool-delivery), and [LLM Tool Auth](/sections/conversational-video-interface/pal/llm-tool-auth) for the conceptual model. # Delete Tool Source: https://docs.tavus.io/api-reference/tools/delete-tool delete /v2/tools/{tool_id} Soft-deletes a tool and detaches it from every PAL it was attached to. The tool name is freed for reuse on a new tool. System tools cannot be deleted. # Get Tool Source: https://docs.tavus.io/api-reference/tools/get-tool get /v2/tools/{tool_id} Returns a single tool by its `tool_id`. Works for both user-owned tools and built-in system tools. Secret fields (`token`, `password`, `value`, `secret`, `client_secret`) are replaced with `********` in the response. # Get Tools Source: https://docs.tavus.io/api-reference/tools/get-tools get /v2/tools Returns a paginated list of tools. The `type` query parameter controls which tools are returned: - `type=user` (default) - tools you created via [Create Tool](/api-reference/tools/create-tool). - `type=system` - built-in system tools Tavus provides. These are always available to every conversation; you do not need to attach them. The only system tool today is `end_call`, which lets the PAL hang up at a natural stopping point. - `type=all` - both, with system tools listed first. System tools have `is_system_tool: true`, an `owner_id` of `null`, and use their `name` as the `tool_id` (e.g. `end_call`). They cannot be created, updated, or deleted. # Update Tool Source: https://docs.tavus.io/api-reference/tools/update-tool patch /v2/tools/{tool_id} Update one or more fields on a tool. Only fields present in the body are changed; omitted fields keep their stored value. System tools cannot be updated. **Secrets and the `********` placeholder.** [Get Tool](/api-reference/tools/get-tool) returns secret fields scrubbed to `********`. If you do a read-modify-write and PATCH that exact value back, the request is rejected - re-encrypting the placeholder would silently corrupt the stored secret. To keep the existing secret, **omit** the field from the auth object on PATCH. Sending `delivery: null` resets delivery to the default `{ app_message: true }`. # Generate Video Source: https://docs.tavus.io/api-reference/video-request/create-video post /v2/videos This endpoint generates a new video using a face 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 **face** metadata. When you [Create Face](/api-reference/faces/create-face) with **`train_image_url`** (image-to-face), **`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. # CLI Source: https://docs.tavus.io/sections/agent-tools/cli Install, authenticate, and drive the Tavus CLI to manage PALs, faces, conversations, and the agentic resource library from your terminal. The Tavus CLI (`tavus`) is a Typer-based command-line client for the Tavus API. It manages PALs, faces, conversations, and the full agentic resource library (guardrails, objectives, tools, pronunciation dictionaries), plus the conversational PAL builder and text-only chat mode. The CLI and the Tavus MCP server share the same backend client. Use the CLI for scripting and manual workflows; use MCP when an agent should drive Tavus through tools. For the autonomous new-PAL loop, see [Agentic PAL building & testing](/sections/agent-tools/pal-build-and-verify). The CLI command is `tavus pal build`; the MCP equivalent is `tavus_pal_build_and_verify`. ## Install The CLI is distributed as the `tavus-cli` Python package and exposes a `tavus` command on your `PATH`. ```bash theme={null} uv tool install tavus-cli ``` Or run it without installing: ```bash theme={null} uvx --from tavus-cli tavus doctor ``` ```bash theme={null} pip install tavus-cli ``` `tavus-cli` is the package name; confirm the package index you install from with your Tavus contact. The CLI defaults to the production environment (`PROD`). To target the test database, set `TAVUS_ENV=TEST` in your shell or pass `--env TEST` on any command. ```bash theme={null} tavus doctor ``` `tavus doctor` prints the selected environment, the resolved API base URLs, the PAL Maker URL, and the auth source, then checks API reachability. Pass `--skip-network` to validate local configuration only. ## Authenticate ### Browser login (recommended) ```bash theme={null} tavus auth login ``` This opens PAL Maker at `/dev/cli-authorize` with a loopback callback URL and an anti-CSRF state token. After you sign in, PAL Maker mints an API key for your account (tagged `source: cli`) and POSTs it back to the local loopback receiver. The CLI then stores the key in your OS keychain, scoped to the selected environment. To store an existing key instead of opening the browser, pass `--api-key` (and optionally `--name` to label the minted key): ```bash theme={null} tavus auth login --api-key --name "ci-key" ``` Check or clear credentials: ```bash theme={null} tavus auth status # {env, authenticated, source} tavus auth logout # deletes the env-scoped keychain entry ``` ### API key fallback For automation, set `TAVUS_API_KEY` directly instead of using the keychain: ```bash theme={null} TAVUS_API_KEY=... tavus pal list ``` Per-environment overrides are also supported: `TAVUS_TEST_API_KEY`, `TAVUS_STG_API_KEY`, and `TAVUS_PROD_API_KEY`. ## Environments Every command accepts a global `--env` / `-e` option that sets `TAVUS_ENV`. Recognized values are `TEST`, `STG`, and `PROD` (default). When unset, the CLI targets `PROD`. ```bash theme={null} # Production (default) tavus pal list # Test database tavus --env TEST pal list TAVUS_ENV=TEST tavus pal list ``` The environment must match the portal that minted your API key. A `TEST` key used against a `PROD` environment (or vice versa) will return `401` on downstream Tavus API calls. ## JSON round-tripping The CLI moves structured payloads through JSON consistently: * Most commands print JSON by default; commands with table output expose a `--json` flag to switch to raw JSON. * File inputs (`--file`, `--layers-file`, `--patch-file`) are parsed with `json.loads()`. * The `pal patch` `--value` option attempts a JSON parse first, then falls back to a plain string if parsing fails, so wrap string values in quotes (e.g. `--value '"New Name"'`). * Repeatable options (`--memory`, `--guardrail-id`, `--tag`, `--document-id`, etc.) are collected into lists in the request body. ## Examples ```bash theme={null} # 1. List PALs as a table, then as JSON tavus pal list --limit 10 tavus pal list --json # 2. Inspect a PAL plus the account resources you can attach to it tavus pal options # 3. Rename a PAL with a validated JSON Patch (note the quoted JSON value) tavus pal patch \ --op replace --path /pal_name --value '"New Name"' # 4. Validate a patch without sending it tavus pal patch \ --op replace --path /pal_name --value '"New Name"' --dry-run # 5. Build a PAL through the conversational builder, then verify in chat mode tavus pal build --prompt "I want a PAL for an office greeter" --json # 6. Send one chat turn to a builder session tavus builder chat --message "Make the greeting warmer" # 7. Turn on built-in PAL Maker capabilities (Web Search, then Slide Presenter) tavus pal capabilities attach web_search tavus pal capabilities attach slide_presenter \ --document-id --slides-trigger walk_the_deck # 8. Create a Knowledge document from a URL and attach it to a PAL tavus document create --url https://example.com/handbook.pdf --tag onboarding tavus pal knowledge add --document-id ``` ## Command reference All sub-apps support `-h` / `--help`, and invoking a sub-app with no arguments prints its help. ### Top-level commands | Command | What it does | | ---------------------------------- | -------------------------------------------------------------------------------------------------- | | `tavus doctor` | Show environment, auth source, and API reachability. `--skip-network` validates local config only. | | `tavus quickstart ` | Create a PAL and a conversation using a stock face by default. Options: `--name`, `--face-id`. | | `tavus embed ` | Build an embed file manifest. `--target` (default `iframe`), `--write` to write files. | ### `tavus auth` | Command | What it does | | ------------- | ----------------------------------------------------------------------------------------- | | `auth login` | Browser-based login that stores an env-scoped key in the keychain. `--api-key`, `--name`. | | `auth logout` | Delete the env-scoped key from the keychain. | | `auth status` | Show whether credentials are available for the selected env. | ### `tavus pal` | Command | What it does | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `pal list` | List PALs. `--limit`, `--page`, `--pal-type`, `--json`. | | `pal get ` | Fetch a PAL as JSON. `--include-settings`. | | `pal create` | Create a PAL. `--system-prompt`, `--name`, `--face-id`, `--pipeline-mode`, `--greeting`, `--context`, `--layers-file`, `--memory`, `--objectives-id`, `--guardrails-id`, `--guardrail-id`, `--guardrail-tag`, `--document-id`, `--document-tag`, `--template`/`--no-template`. | | `pal delete ` | Delete a PAL. | | `pal patch ` | Apply a validated JSON Patch. `--op`, `--path`, `--value`, `--patch-file`, `--dry-run`. | | `pal options ` | Return the PAL plus valid account resources and patchable paths. | | `pal paths` | List locally known JSON Patch paths for PALs. | | `pal build` | Build a PAL via the conversational builder, then verify in chat mode. `--prompt`, `--face-id`, `--max-rounds`, `--json`. | | `pal preview ` | Start a full preview conversation and print the conversation URL. `--face-id`, `--name`, `--json`. | Tools are first-class objects: attach them after creating a PAL with `tavus pal tools attach` rather than inlining them at create time. #### `tavus pal tools` | Command | What it does | | ----------------------------------------- | ------------------------------------------------- | | `pal tools list ` | List tools attached to a PAL. | | `pal tools attach ` | Attach one or more existing tools to a PAL by ID. | | `pal tools detach ` | Detach a tool from a PAL. | #### `tavus pal capabilities` Manage the built-in PAL Maker capabilities - Magic Canvas, Slide Presenter, Web Search, Perception, and Memory - with friendly IDs instead of raw JSON Patch. Accepted capability IDs are `magic_canvas`, `slide_presenter`, `web_search`, `perception`, and `memory` (the portal IDs `builtin:magic_canvas`, `builtin:slide_presenter`, `builtin:web_search`, and `skill:memory` also work). | Command | What it does | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pal capabilities catalog` | List the five PAL Maker capabilities and their backend mappings. | | `pal capabilities list ` | Show Magic Canvas, Slide Presenter, Web Search, Perception, and Memory attachment state and config for a PAL. | | `pal capabilities attach ` | Attach a capability by friendly or portal ID. Capability-specific options: `--document-id`, `--slides-trigger`, `--prompt` (Slide Presenter); `--component`, `--usage-guidance`, `--scheduling-url`, `--scheduling-provider` (Magic Canvas); `--perception-model`, `--visual-query`, `--audio-query`, `--visual-tool-prompt`, `--audio-tool-prompt` (Perception). Also `--config`/`--config-file` for raw config. | | `pal capabilities patch ` | Update the config of an already-attached capability. Same options as `attach`. | | `pal capabilities detach ` | Detach a capability. For Perception this sets the perception model to off. | Magic Canvas, Slide Presenter, Web Search, and Memory persist through the PAL's skills (`/pals/{id}/skills`); Perception persists through `layers.perception`. `pal capabilities` handles that difference for you - prefer it over `pal skills` for these five. #### `tavus pal skills` Lower-level access to the raw RQH skills attached to a PAL. Use `pal capabilities` for the five PAL Maker capabilities; reach for `pal skills` only when you need to work with a skill by its raw registry ID. | Command | What it does | | --------------------------------------- | ------------------------------------------------------------------------- | | `pal skills list ` | List raw RQH skills attached to a PAL. | | `pal skills attach ` | Attach or replace one raw RQH skill. `--config`, `--config-file`. | | `pal skills patch ` | Merge config into an already-attached skill. `--config`, `--config-file`. | | `pal skills detach ` | Detach one raw RQH skill from a PAL. | #### `tavus pal knowledge` Manage a PAL's Knowledge section - the `document_ids` and `document_tags` it draws on for retrieval, plus RAG tuning under `layers.knowledge_base`. Create the underlying documents first with [`tavus document`](#tavus-document). | Command | What it does | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pal knowledge list ` | Show attached document IDs, tags, resolved document records, and `knowledge_base` layer settings. | | `pal knowledge add ` | Attach documents or document tags. `--document-id`, `--document-tag` (both repeatable). | | `pal knowledge remove ` | Remove documents or document tags. `--document-id`, `--document-tag`. | | `pal knowledge replace ` | Replace the PAL's document and tag selections. `--document-id`, `--document-tag`. | | `pal knowledge settings ` | Patch RAG tuning under `layers.knowledge_base`. `--rag-score-threshold`, `--rag-n-chunks`, `--rag-surrounding-chunk-radius`, `--rag-observability`/`--no-rag-observability`, `--procedure-goalchain`/`--no-procedure-goalchain`. | | `pal knowledge upload ` | Upload a local file as a Knowledge document and attach it to the PAL. Same upload options as [`tavus document upload`](#tavus-document), plus `--attach`/`--upload-only`. Requires `TAVUS_PORTAL_BEARER_TOKEN`. | ### `tavus face` | Command | What it does | | ----------- | --------------------------------------------------------------------- | | `face list` | List faces. `--limit`, `--stock` (system/stock faces only), `--json`. | ### `tavus conversation` | Command | What it does | | ------------------------------------ | --------------------------------------------------------- | | `conversation create` | Create a conversation. `--pal-id`, `--face-id`, `--name`. | | `conversation end ` | End a conversation. | ### `tavus resource` | Command | What it does | | --------------------------------------- | ------------------------------------------------------------------------------------------------- | | `resource list ` | List a supported resource: `guardrails`, `objectives`, `documents`, `voices`, `tools`. `--limit`. | | `resource get ` | Get a single resource by ID. | ### `tavus document` Manage Knowledge documents - the account-level records that back a PAL's Knowledge section. With a normal Tavus API key you can create documents from an already-reachable URL; local file upload uses the same portal-only path as PAL Maker (local file → tavus-api upload/S3 URL → document record) and therefore requires a Firebase portal bearer token in `TAVUS_PORTAL_BEARER_TOKEN`. Attach documents to a PAL with [`tavus pal knowledge`](#tavus-pal-knowledge). | Command | What it does | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `document list` | List Knowledge documents. `--limit`, `--page`, `--status`, `--tag`, `--participant-tag`, `--name-or-uuid`, `--verbose`/`--compact`, `--json`. | | `document get ` | Get one Knowledge document record. `--verbose`. | | `document create` | Create a document from an already-hosted URL. `--url` (required), `--name`, `--tag`, `--participant-tag`, `--crawl-depth`, `--crawl-max-pages`, `--custom-description`, `--customer-support`/`--regular-document`, `--standard-extraction`. | | `document upload ` | Upload a local file through tavus-api, then create the document record. Requires `TAVUS_PORTAL_BEARER_TOKEN`. `--name`, `--tag`, `--participant-tag`, `--custom-description`, `--customer-support`/`--regular-document`, `--font-size-aware-extraction`/`--standard-extraction`, `--bucket-name`, `--region`, `--sign-duration`. | | `document tags` | List document tags available for Knowledge attachment. `--search`, `--page`, `--limit`. | | `document chunks ` | Read the extracted chunks RQH indexed for a document. `--collection` (default `regular`), `--limit`, `--offset`. | | `document recrawl ` | Trigger a recrawl for a crawl-backed document. `--crawl-depth`, `--crawl-max-pages`. | Use `document chunks` to inspect what RQH actually ingested before making claims about a document's contents - it returns the indexed text, not the source file. ### `tavus guardrail` | Command | What it does | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `guardrail list` | List guardrails (new flat shape by default). `--limit`, `--page`, `--type`, `--name-or-uuid`, `--tags`, `--legacy`, `--verbose`, `--json`. | | `guardrail get ` | Get a guardrail. `--verbose`, `--legacy`. | | `guardrail create` | Create a flat guardrail. `--name`, `--prompt`, `--modality`, `--callback-url`, `--tool-call`, `--app-message`/`--no-app-message`, `--tag`. | | `guardrail patch ` | Patch a guardrail. `--file`, `--name`, `--prompt`, `--modality`, `--callback-url`, `--tool-call`, `--app-message`/`--no-app-message`, `--tag`. | | `guardrail delete ` | Delete a guardrail. | | `guardrail tags` | List tags applied to the account's guardrails. `--search`, `--page`, `--limit`. | ### `tavus objective` | Command | What it does | | ---------------------------------- | ----------------------------------------------------------------------------------------- | | `objective list` | List objective sets. `--limit`, `--page`, `--type`, `--name-or-uuid`, `--sort`, `--json`. | | `objective get ` | Get an objective set. | | `objective create` | Create an objective set from a JSON file. `--file` (`{name, data, allow_loops}`). | | `objective patch ` | Patch an objective set with JSON Patch ops. `--file`. | | `objective delete ` | Delete an objective set. | | `objective validate` | Validate an objective-set payload without persisting. `--file`. | | `objective example` | Print a starter JSON body for `objective create --file`. | ### `tavus tool` | Command | What it does | | ----------------------- | -------------------------------------------------------------------------------- | | `tool list` | List tools. `--limit`, `--page`, `--type`, `--name-or-uuid`, `--sort`, `--json`. | | `tool get ` | Get a tool. | | `tool create` | Create a tool from a JSON file. `--file`. | | `tool patch ` | Patch a tool from a JSON file. `--file`. | | `tool delete ` | Delete a tool. | | `tool example` | Print a starter JSON body. `--delivery` (`app_message`, `http`, `http_oauth2`). | When patching a tool, omit any secret fields you don't intend to change. The backend rejects PATCHes that echo back the scrubbed-secret placeholder (`********`) returned from a prior GET. ### `tavus skill` Browse the RQH skill registry - the skills that back PAL capabilities. This lists what is available to attach; attach and configure per-PAL with [`tavus pal capabilities`](#tavus-pal-capabilities) or [`tavus pal skills`](#tavus-pal-skills). | Command | What it does | | ---------------------- | --------------------------------------------- | | `skill list` | List RQH skills that can be attached to PALs. | | `skill get ` | Get one RQH skill registry entry. | ### `tavus pronunciation-dictionary` | Command | What it does | | ------------------------------------------------- | ---------------------------------------------------------------------------- | | `pronunciation-dictionary list` | List pronunciation dictionaries. `--limit`, `--page`, `--sort`, `--json`. | | `pronunciation-dictionary get ` | Get a pronunciation dictionary. | | `pronunciation-dictionary create` | Create from a JSON file. `--file` (`{name, rules}`). | | `pronunciation-dictionary patch ` | Patch from a JSON file. `--file` (supplying `rules` replaces the full list). | | `pronunciation-dictionary delete ` | Delete a pronunciation dictionary. | | `pronunciation-dictionary example` | Print a starter JSON body. | ### `tavus builder` | Command | What it does | | -------------------------------------- | --------------------------------------------------------------------------------------- | | `builder create` | Start a builder session. `--name`, `--greeting`, `--pal-id`, `--model`. | | `builder list` | List builder sessions. `--limit`, `--page`, `--pal-id`, `--name`, `--status`, `--json`. | | `builder get ` | Fetch a single builder session. | | `builder delete ` | Soft-delete a builder session. | | `builder chat ` | Send a chat turn to the builder. `--message`, `--json`. | | `builder history ` | Print the chat transcript. `--limit`, `--json`. | | `builder append-messages ` | Append raw `{role, content}` messages without invoking the LLM. `--file`. | | `builder publish ` | Mark the session complete and publish its PAL. | #### `tavus builder update` | Command | What it does | | ----------------------------------------- | ------------------------------------------------------------------------------- | | `builder update objectives ` | Run an LLM update on the PAL's objectives. `--message`. | | `builder update guardrails ` | Run an LLM update on the PAL's guardrails. `--message`. | | `builder update greeting ` | Run an LLM refinement of the greeting. `--message`. | | `builder update personality ` | Refine PAL name and/or system prompt. `--message`, `--name`, `--system-prompt`. | ### `tavus chat` | Command | What it does | | ----------------------------- | --------------------------------------------------------------------------------- | | `chat start` | Start a text-only conversation against a PAL. `--pal-id`, `--greeting`, `--name`. | | `chat turn ` | Send one user turn and print the reply as plain text. `--message`, `--timeout`. | | `chat end ` | End a chat-mode conversation. | # MCP Server Source: https://docs.tavus.io/sections/agent-tools/mcp-server Connect your coding agent to the hosted Tavus MCP server to build PALs, wire bidirectional tool calls into your own code, and test the integration end to end. The Tavus MCP server is a hosted endpoint your coding agent connects to. Once it is wired into Codex, Claude Code, Cursor, or another MCP client, your agent can build and patch a PAL, define the tools that PAL can call, attach them, and start test conversations, all from your editor against your own codebase. There is nothing to install or run. You connect over HTTPS and authenticate once in the browser. ## Why connect your editor A working voice agent has two parts that have to agree: 1. The PAL needs to know which tools exist and when to call them. That lives in the PAL's tool definitions and prompt. 2. Your application needs to handle those calls when they fire. That lives in your code. Keeping those two parts in sync by hand is where integrations drift. The MCP server lets one agent work both sides: it defines the tool on the PAL and can scaffold and check the matching handler in your repo, so the two stay consistent. You then test the exchange by starting a conversation and watching the tool fire and your handler respond, without leaving your editor. Create and patch the PAL's layers, prompt, guardrails, and objectives. Define tools, attach them, and generate the handler code in your own app. Start chat or full conversations and watch tool calls round-trip live. ## Connect a client The server is reachable at an HTTPS `/mcp` endpoint. Authentication uses a browser-based OAuth flow: the PAL Maker mints a per-user API key and the server forwards it to the Tavus API as `x-api-key`. No key or shared token sits in your client config. The public Tavus MCP endpoint is `https://mcp.tavus.io/mcp`. Use this endpoint for every supported client and production integration. Point your MCP client at the hosted endpoint. For Codex: ```bash theme={null} codex mcp add tavus --url https://mcp.tavus.io/mcp ``` For Claude Code: ```bash theme={null} claude mcp add -s user --transport http tavus https://mcp.tavus.io/mcp ``` This registers the server under the name `tavus` for your user scope. Never put a Tavus API key or shared bearer token in your MCP client config. The hosted server authenticates each user through the PAL Maker and keeps keys user-scoped and out of client configuration. On first use, the client runs an OAuth flow against the server. For Codex, you can start it directly: ```bash theme={null} codex mcp login tavus ``` Then the flow is: 1. The client initiates the authorize flow. 2. The portal redirects to `/dev/cli-authorize?mode=oauth`. 3. You sign in. 4. The portal mints a per-user Tavus API key. 5. You are redirected back to the client's loopback callback. 6. The server exchanges the authorization code and forwards the minted key to the Tavus API as `x-api-key` on every downstream call. Once authenticated, the full Tavus toolset is available: PAL CRUD, faces, conversations, builder, chat-mode testing, guardrails, objectives, tools, pronunciation dictionaries, built-in PAL Maker capabilities (Magic Canvas, Slide Presenter, Web Search, Perception, Memory), and Knowledge documents. See [Agentic PAL building & testing](/sections/agent-tools/pal-build-and-verify) for the autonomous PAL loop, or the [MCP tools reference](/sections/agent-tools/mcp-tools-reference) for the full catalog. MCP tools return data and file manifests. They do not write files themselves. Your client decides what to do with the returned data, such as writing a generated tool handler into your repo. ## Bidirectional tool calls A tool call in Tavus is an exchange, and that exchange is what connects the PAL to your app: 1. During a conversation the PAL decides a tool is needed, based on the tool's `description` and the PAL's prompt, and calls it with arguments. 2. Tavus delivers that call to your code. 3. Your code runs its logic and returns a result. 4. The PAL uses the result to decide what to say and do next. The PAL calls into your application in steps 1 and 2, and your application's response shapes the PAL's next turn in steps 3 and 4. ### Two delivery channels A tool's `delivery` field sets where the call is delivered. It is the main choice you make when you define a tool. ```json theme={null} "delivery": { "app_message": true } ``` The call is emitted to your frontend or client over the conversation's data channel as a [tool-call event](/sections/event-schemas/conversation-toolcall). Your app listens for it and runs local logic. Best for actions in the UI: highlight a product, change a slide, navigate a page, or update on-screen state. This is also the default channel for [LLM tool calling](/sections/conversational-video-interface/pal/llm-tool). ```json theme={null} "delivery": { "api": { "url": "https://your-app.example.com/api/tools/get_order_status", "method": "POST", "content_type": "application/json", "body_template": { "order_id": "{order_id}" }, "timeout": 10.0 } } ``` Tavus makes a direct HTTPS call to your backend and waits for the JSON response. Best for server-side work such as database lookups, business logic, and third-party APIs. The HTTP form also supports `headers`, `query_params`, and `auth` (`none`, `bearer`, `basic`, `api_key`, `hmac`, or `oauth2_client_credentials`). `timeout` defaults to 10 seconds (max 60). Any `{placeholder}` used in `url`, `body_template`, or `query_params` must be declared as a property in the tool's `parameters.properties`. The tool's `description` plus `parameters` JSON must total 10,000 characters or fewer. ### Controlling what the PAL does around the call Two fields shape the conversational behavior of the exchange: | Field | Common values | What it does | | --------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `on_call` | `silent` | What the PAL does while the tool runs, for example staying silent instead of narrating the call. | | `on_resolve` | `generate_response`, `fire_and_forget` | What happens after the result returns. `generate_response` has the PAL speak based on the result. `fire_and_forget` (the default) does not wait or narrate. | | `static_filler` | any string | A line to say while waiting on a slow tool. | Use `on_resolve: generate_response` when the result should change what the PAL says next, such as an order status or an availability check. Use `fire_and_forget` for side effects the PAL does not need to react to. ### A complete example A backend lookup the PAL can call to answer "where's my order?": ```json get_order_status tool theme={null} { "name": "get_order_status", "description": "Look up the current status of a customer's order. Call this when the user asks about the state, location, or delivery date of an order they reference by number. The result tells you the status and the estimated delivery date so you can relay it.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order number the customer gave, e.g. 'A-10428'." } }, "required": ["order_id"] }, "delivery": { "api": { "url": "https://your-app.example.com/api/tools/get_order_status", "method": "POST", "content_type": "application/json", "body_template": { "order_id": "{order_id}" }, "timeout": 10.0 } }, "origin": "llm", "on_call": "silent", "on_resolve": "generate_response" } ``` When the PAL calls it, Tavus POSTs `{ "order_id": "A-10428" }` to your endpoint. Your handler returns JSON, for example: ```json theme={null} { "status": "out_for_delivery", "eta": "today by 6pm" } ``` Because `on_resolve` is `generate_response`, the PAL speaks from that result, for example: *"Good news, order A-10428 is out for delivery and should arrive today by 6pm."* ## Build and test it with your agent One agent can do every step above. A typical loop: 1. **Define the tool.** The agent calls `tavus_tool_create` with the `parameters` and `delivery` that match what the tool should do. 2. **Attach it.** `tavus_pal_tools_attach` wires the tool onto your PAL so it is offered during conversations. 3. **Write the handler.** For an `api` tool, the agent scaffolds the matching endpoint in your repo (the route at `delivery.api.url`) so the request and response shape match the tool's `parameters`. 4. **Test the exchange.** `tavus_chat_start` and `tavus_chat_turn` (text only), or `tavus_conversation_create` (full video), start a session so you can watch the tool fire and your handler respond, then iterate. For a new PAL, an agent can run this as one autonomous build, simulated-turn test, and judge pass with `tavus_pal_build_and_verify`. See [Agentic PAL building & testing](/sections/agent-tools/pal-build-and-verify). The server flags a likely duplicate when you create a tool that resembles one you already have, so your agent can attach the existing tool instead. Prefer attaching saved tools over redefining them inline. See the [MCP tools reference](/sections/agent-tools/mcp-tools-reference) for `tavus_tool_list`, `tavus_tool_create`, and `tavus_pal_tools_attach`. ## Built-in capabilities Custom tools are one way to extend a PAL. The other is the set of built-in **PAL Maker capabilities** - Magic Canvas, Slide Presenter, Web Search, Perception, and Memory - which the server exposes through friendly, portal-aligned tools so your agent turns them on the same way PAL Maker does: * `tavus_pal_capability_catalog` lists the five capabilities and their backend mappings. * `tavus_pal_capabilities_list` shows what is attached to a PAL and its config. * `tavus_pal_capability_attach` / `tavus_pal_capability_patch` / `tavus_pal_capability_detach` manage them by friendly ID (`magic_canvas`, `slide_presenter`, `web_search`, `perception`, `memory`). Prefer these over raw JSON Patch: the server knows that Magic Canvas, Slide Presenter, Web Search, and Memory persist through the PAL's skills (`/pals/{id}/skills`) while Perception persists through `layers.perception`. For skills that are not one of the five capabilities, the raw `tavus_skill_list` and `tavus_pal_skill_*` tools work with a skill by its registry ID. ## Knowledge Give a PAL documents to ground its answers with the Knowledge tools. This is a two-step flow that mirrors PAL Maker's Knowledge section: 1. **Create the document.** `tavus_document_create` ingests an already-hosted URL with a normal Tavus API key. To upload a local file, `tavus_document_upload` runs the portal path (local file → tavus-api upload/S3 URL → document record) and needs a locally running MCP server plus `TAVUS_PORTAL_BEARER_TOKEN`. 2. **Attach it.** `tavus_pal_knowledge_add` (or `_replace`) wires documents and document tags onto the PAL. `tavus_pal_knowledge_settings_patch` tunes RAG behavior under `layers.knowledge_base`, and `tavus_pal_knowledge_upload` does the upload-and-attach in one call. Use `tavus_document_chunks` to inspect the text RQH actually indexed for a document before relying on it - it returns the ingested chunks, not the source file. See the [MCP tools reference](/sections/agent-tools/mcp-tools-reference) for the full capability, skill, and Knowledge catalogs. ## Environment alignment The server must run in the same environment as the portal that minted your key. A `TEST` key authenticated against a production server, or the reverse, makes downstream Tavus API calls return `401`. Keep the endpoint and the portal you sign in to on the same environment. ## Troubleshooting the connection The server exposes standard OAuth discovery metadata you can inspect directly: ```bash theme={null} curl https://mcp.tavus.io/.well-known/oauth-protected-resource/mcp curl https://mcp.tavus.io/.well-known/oauth-authorization-server curl -i https://mcp.tavus.io/mcp ``` An unauthenticated `/mcp` request should return `401` with a `WWW-Authenticate` header pointing at the protected-resource metadata URL. If that header or the discovery endpoints are missing, the OAuth flow cannot complete. Re-add the server and retry the browser sign-in. # MCP Tools Reference Source: https://docs.tavus.io/sections/agent-tools/mcp-tools-reference Complete reference for every tool exposed by the Tavus MCP server, grouped by category. The Tavus MCP server exposes the full agentic PAL toolkit to MCP clients. Each tool maps to a Tavus API operation and is callable from any MCP-aware client (for example, Codex or Claude Code). This page is a complete reference of every tool, grouped by category. For installation and authentication, see the [MCP server](/sections/agent-tools/mcp-server) page. For the equivalent command-line surface, see the [CLI](/sections/agent-tools/cli). For the autonomous PAL loop, see [Agentic PAL building & testing](/sections/agent-tools/pal-build-and-verify). Tools are first-class objects, not inlined on the PAL. Before giving a PAL a tool, check the saved library with `tavus_tool_list` or `tavus_describe_pal_options`, then either attach an existing tool (`tavus_pal_tools_attach`) or create a new one (`tavus_tool_create`) and attach it. Writing tools inline via `tavus_patch_pal` (`layers.*.tools`) is deprecated. When you create a tool that overlaps an existing one, the response carries a `_tool_reuse_advisory` so you can reuse instead. MCP tools return data plus optional file manifests for the client to handle. They never write files to disk themselves. ## PAL CRUD & patch | Tool | Parameters | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tavus_pal_list` | `limit=25`, `page=0`, `pal_type=None` | List PALs with an optional type filter. | | `tavus_pal_get` | `pal_id`, `include_settings=False` | Fetch a single PAL by ID; optionally include settings. | | `tavus_pal_create` | `system_prompt=None`, `pal_name="Agentic Tavus PAL"`, `default_face_id=None`, `pipeline_mode="full"`, `greeting=None`, `context=None`, `layers=None`, `memories=None`, `objectives_id=None`, `guardrails_id=None`, `guardrail_ids=None`, `guardrail_tags=None`, `document_ids=None`, `document_tags=None`, `is_template=None` | Create a PAL. `system_prompt` is required for `pipeline_mode="full"`. Tools are attached separately after creation. | | `tavus_pal_delete` | `pal_id` | Delete a PAL by ID. | | `tavus_patch_pal` | `pal_id`, `ops` | Patch a PAL with JSON Patch operations. Ops that write inline tools (`layers.*.tools`) return `_inline_tools_deprecated` steering you to the attach/create flow. | | `tavus_describe_pal_options` | `pal_id` | Describe one PAL plus the account resources (guardrails, objectives, documents, tools, voices) that can be attached to it. | `pipeline_mode` is one of `full` (LLM + TTS + STT + perception), `speech-to-speech` (no LLM), or `echo` (TTS + transport only). ## Face | Tool | Parameters | Description | | ----------------- | ------------------------- | ------------------------------------------------------------------ | | `tavus_face_list` | `limit=25`, `stock=False` | List faces; when `stock=True`, filters to system/stock faces only. | ## Conversation | Tool | Parameters | Description | | --------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `tavus_conversation_create` | `pal_id=None`, `face_id=None`, `conversation_name=None` | Create a conversation with an optional PAL and face. Returns the conversation object with id and URL. | | `tavus_conversation_end` | `conversation_id` | End a conversation by ID. | ## Quickstart | Tool | Parameters | Description | | ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `tavus_quickstart` | `system_prompt`, `pal_name="Agentic Tavus PAL"`, `face_id=None` | One-shot recipe: create a PAL, pick a stock face when needed, and create a conversation. Returns the PAL plus the conversation. | ## Templates | Tool | Parameters | Description | | ------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tavus_pal_from_template` | `template`, `pal_name=None`, `business_context=None`, `default_face_id=None`, `layers=None` | Create a PAL from a built-in prompt template (customer-support, interviewer, sales, tutor, dev-rel) with optional business context and layer overrides. | ## Scaffold | Tool | Parameters | Description | | ---------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `tavus_scaffold_embed` | `conversation_url`, `target="iframe"`, `component_name="TavusConversation"` | Return starter files for embedding a Tavus conversation URL. `target` is one of `iframe`, `cvi-ui`, `vanilla`. | ## Resource list | Tool | Parameters | Description | | --------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `tavus_resource_list` | `resource`, `limit=25` | List account resources. `resource` is one of `guardrails`, `objectives`, `documents`, `voices`, `skills`, `tools` (singular aliases accepted). | ## Guardrails Guardrails use a flat, per-rule shape by default (not deprecated sets). | Tool | Parameters | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `tavus_guardrail_list` | `limit=25`, `page=1`, `type="user"`, `name_or_uuid=None`, `tags=None`, `legacy=False`, `verbose=False` | List guardrails with optional filtering. `type` is one of `user`, `system`, `all`. `verbose` adds `persona_refs` and `guardrail_type`. | | `tavus_guardrail_get` | `guardrail_id`, `verbose=False`, `legacy=None` | Fetch a single guardrail. | | `tavus_guardrail_create` | `guardrail_name`, `guardrail_prompt`, `modality="verbal"`, `callback_url=""`, `tool_call=None`, `app_message=True`, `tags=None` | Create a flat guardrail with optional callback and tool-call payload. `modality` is one of `verbal`, `visual`, `audio`. | | `tavus_guardrail_patch` | `guardrail_id`, `guardrail_name=None`, `guardrail_prompt=None`, `modality=None`, `callback_url=None`, `tool_call=None`, `app_message=None`, `tags=None` | Update a guardrail. Omit fields to leave them unchanged; each supplied field is replaced whole. | | `tavus_guardrail_delete` | `guardrail_id` | Delete a guardrail by ID. | | `tavus_guardrail_tags` | `search=None`, `page=None`, `limit=None` | List tags applied to the account's guardrails. | ## Objectives Objectives are stored as sets; PALs reference a set by `objectives_id`. | Tool | Parameters | Description | | -------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tavus_objective_list` | `limit=25`, `page=1`, `type="user"`, `name_or_uuid=None`, `sort="ascending"` | List objective sets. `type` is one of `user`, `system`, `all`. | | `tavus_objective_get` | `objectives_id` | Fetch a single objective set. | | `tavus_objective_create` | `data`, `name=""`, `allow_loops=False` | Create an objective set. Each item has `objective_name` (letters/digits/underscores only), `objective_prompt`, optional `confirmation_mode` ("auto"\|"manual"), `modality` ("verbal"\|"visual"\|"audio"), `output_variables`, `callback_url`, `tool_call`, and chains via `next_required_objective` or `next_conditional_objectives` (not both). When `allow_loops=False`, exactly one item must be root. | | `tavus_objective_patch` | `objectives_id`, `ops` | Patch an objective set with JSON Patch ops; cycle and single-root validation re-runs. | | `tavus_objective_delete` | `objectives_id` | Delete an objective set by ID. | | `tavus_objective_validate` | `data`, `name=""`, `allow_loops=False` | Validate an objective-set payload (cycles, single root, references) without persisting. | ## Tools (PAL tool library) | Tool | Parameters | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `tavus_tool_list` | `limit=25`, `page=1`, `type="user"`, `name_or_uuid=None`, `sort="ascending"` | List tools. `type` filters by ownership (`user`, `system`, `all`). | | `tavus_tool_get` | `tool_id` | Fetch a single tool by ID. | | `tavus_tool_create` | `name`, `description`, `parameters=None`, `delivery=None`, `origin="llm"`, `on_call=None`, `on_resolve="fire_and_forget"`, `static_filler=None` | Create a tool. Placeholders `{ident}` in url/body/query must be declared in `parameters.properties`. Description plus parameters JSON must total ≤ 10,000 chars. Returns `_tool_reuse_advisory` if similar tools exist. For [post-call actions](/sections/conversational-video-interface/pal/post-call-tool), use the CLI `tool create --file` or Tools API with `trigger_type: "post_call"` (not yet a parameter on this MCP tool). | | `tavus_tool_patch` | `tool_id`, `name=None`, `description=None`, `parameters=None`, `delivery=None`, `origin=None`, `on_call=None`, `on_resolve=None`, `static_filler=None` | Update a tool. Omit fields to leave them unchanged. Secrets returned scrubbed (`********`) from a prior GET must be omitted, not re-sent. | | `tavus_tool_delete` | `tool_id` | Delete a tool by ID. | `delivery` defaults to `{"app_message": true}` (Daily data channel), or use `{"api": {...}}` for HTTPS calls with headers, query params, body template, content type, timeout (default 10s, max 60s), and auth (`none`, `bearer`, `basic`, `api_key`, `hmac`, `oauth2_client_credentials`). ## Pronunciation dictionaries Pronunciation dictionaries are referenced from PALs via `layers.tts.pronunciation_dictionary_id`. | Tool | Parameters | Description | | --------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tavus_pronunciation_dictionary_list` | `limit=25`, `page=0`, `sort="desc"` | List pronunciation dictionaries. | | `tavus_pronunciation_dictionary_get` | `dictionary_id` | Fetch a single pronunciation dictionary. | | `tavus_pronunciation_dictionary_create` | `name`, `rules=None` | Create a dictionary. Each rule is `{text, pronunciation, type: "alias"\|"ipa", alphabet?, case_sensitive?, word_boundaries?}`; max 10,000 rules. Text values must be unique. | | `tavus_pronunciation_dictionary_patch` | `dictionary_id`, `name=None`, `rules=None` | Update a dictionary. Supplying `rules` replaces the full list (no merge). | | `tavus_pronunciation_dictionary_delete` | `dictionary_id` | Delete a dictionary by ID. | ## PAL tools (attach & detach) | Tool | Parameters | Description | | ------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tavus_pal_tools_list` | `pal_id` | List tools currently attached to a PAL. | | `tavus_pal_tools_attach` | `pal_id`, `tool_ids` | Attach one or more existing tools to a PAL by ID. A PAL can hold up to 50 tools. If any attached tool is vision/audio, the PAL's `perception_model` auto-bumps to `raven-1` (response carries `_perception_model_bumped_to_raven_1`). | | `tavus_pal_tools_detach` | `pal_id`, `tool_id` | Detach a single tool from a PAL. | ## PAL capabilities The five built-in PAL Maker capabilities - Magic Canvas, Slide Presenter, Web Search, Perception, and Memory. Prefer these over raw JSON Patch or raw skills: they accept friendly IDs (`magic_canvas`, `slide_presenter`, `web_search`, `perception`, `memory`, plus the portal IDs `builtin:magic_canvas`, `builtin:slide_presenter`, `builtin:web_search`, `skill:memory`) and know that Magic Canvas, Slide Presenter, Web Search, and Memory persist through the PAL's skills while Perception persists through `layers.perception`. | Tool | Parameters | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tavus_pal_capability_catalog` | — | List the five PAL Maker capabilities and their backend mappings. | | `tavus_pal_capabilities_list` | `pal_id` | List Magic Canvas, Slide Presenter, Web Search, Perception, and Memory attachment state and config for a PAL. | | `tavus_pal_capability_attach` | `pal_id`, `capability_id`, `config=None`, `document_ids=None`, `slides_trigger=None`, `prompt=None`, `magic_canvas_components=None`, `magic_canvas_usage_guidance=None`, `scheduling_url=None`, `scheduling_provider=None`, `perception_model=None`, `visual_awareness_queries=None`, `audio_awareness_queries=None`, `visual_tool_prompt=None`, `audio_tool_prompt=None` | Attach a capability. Options are capability-specific: Slide Presenter uses `document_ids`/`slides_trigger`/`prompt`; Magic Canvas uses `magic_canvas_*`/`scheduling_*`; Perception uses `perception_model` and the visual/audio awareness fields; Web Search and Memory take no config. | | `tavus_pal_capability_patch` | same as `tavus_pal_capability_attach` | Update the config of an already-attached capability. | | `tavus_pal_capability_detach` | `pal_id`, `capability_id` | Detach a capability. Perception detaches by setting `perception_model: off`; the other four detach from `/pals/{id}/skills`. | ## Skills (raw RQH) Lower-level access to the RQH skill registry and a PAL's raw skill attachments. Use [PAL capabilities](#pal-capabilities) for the five PAL Maker capabilities; reach for these only to work with a skill by its raw registry ID. | Tool | Parameters | Description | | ------------------------ | ----------------------------------- | -------------------------------------------------------------------- | | `tavus_skill_list` | — | List registered RQH skills/capabilities available to attach to PALs. | | `tavus_pal_skills_list` | `pal_id` | List raw RQH skill attachments for a PAL. | | `tavus_pal_skill_attach` | `pal_id`, `skill_id`, `config=None` | Attach or replace one raw RQH skill on a PAL. | | `tavus_pal_skill_patch` | `pal_id`, `skill_id`, `config` | Merge config into an already-attached raw RQH skill. | | `tavus_pal_skill_detach` | `pal_id`, `skill_id` | Detach one raw RQH skill from a PAL. | ## Knowledge documents Account-level Knowledge document records that back a PAL's Knowledge section. With a normal Tavus API key, create documents from an already-reachable URL (`tavus_document_create`). Local file upload uses the same portal-only path as PAL Maker and requires a locally running MCP server (to read the file) plus `TAVUS_PORTAL_BEARER_TOKEN`. | Tool | Parameters | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `tavus_document_list` | `limit=25`, `page=0`, `status=None`, `tags=None`, `participant_tags=None`, `name_or_uuid=None`, `verbose=True` | List Knowledge documents available to attach to PALs. | | `tavus_document_get` | `document_id`, `verbose=True` | Get one Knowledge document record. | | `tavus_document_create` | `document_url`, `document_name=None`, `tags=None`, `participant_tags=None`, `crawl=None`, `custom_description=None`, `is_customer_support_document=False`, `font_size_aware_extraction=False` | Create a Knowledge document from an already-hosted URL. | | `tavus_document_upload` | `local_path`, `document_name=None`, `tags=None`, `participant_tags=None`, `custom_description=None`, `is_customer_support_document=False`, `font_size_aware_extraction=False`, `bucket_name="developer-portal-documents"`, `region="us-east-1"`, `sign_duration=None` | Upload a local file through tavus-api/S3, then create the document record. Requires `TAVUS_PORTAL_BEARER_TOKEN`. | | `tavus_document_tags` | `search=None`, `page=None`, `limit=None` | List document tags that can be attached to PAL Knowledge. | | `tavus_document_chunks` | `document_id`, `collection="regular"`, `limit=100`, `offset=None` | Read the extracted chunks RQH indexed for a document. Use before making claims about a document's contents. | | `tavus_document_recrawl` | `document_id`, `crawl=None` | Trigger a recrawl for a crawl-backed Knowledge document. | ## PAL Knowledge A PAL's Knowledge section is its `document_ids` plus `document_tags`, with RAG tuning under `layers.knowledge_base`. Create documents first with the [Knowledge documents](#knowledge-documents) tools, then attach them here. | Tool | Parameters | Description | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `tavus_pal_knowledge_list` | `pal_id` | Show Knowledge documents/tags attached to a PAL and resolve the direct document IDs into records. | | `tavus_pal_knowledge_add` | `pal_id`, `document_ids=None`, `document_tags=None` | Attach existing Knowledge documents or document tags to a PAL. | | `tavus_pal_knowledge_remove` | `pal_id`, `document_ids=None`, `document_tags=None` | Remove Knowledge documents or document tags from a PAL. | | `tavus_pal_knowledge_replace` | `pal_id`, `document_ids=None`, `document_tags=None` | Replace the PAL's Knowledge document/tag selections. | | `tavus_pal_knowledge_settings_patch` | `pal_id`, `rag_score_threshold=None`, `rag_n_chunks=None`, `rag_surrounding_chunk_radius=None`, `enable_rag_observability_app_messages=None`, `use_procedure_goalchain=None` | Patch RAG tuning settings under `layers.knowledge_base`. | | `tavus_pal_knowledge_upload` | `pal_id`, `local_path`, `document_name=None`, `tags=None`, `participant_tags=None`, `custom_description=None`, `is_customer_support_document=False`, `font_size_aware_extraction=False`, `bucket_name="developer-portal-documents"`, `region="us-east-1"`, `sign_duration=None`, `attach=True` | Upload a local file as a Knowledge document and attach it to the PAL by default. Requires `TAVUS_PORTAL_BEARER_TOKEN`. | ## Builder The builder is an LLM-guided PAL creation flow. | Tool | Parameters | Description | | ---------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `tavus_builder_create` | `name`, `greeting=None`, `pal_id=None`, `model=None` | Create a builder session, optionally based on an existing PAL. | | `tavus_builder_list` | `limit=None`, `page=None`, `pal_id=None`, `name=None`, `status=None` | List builder sessions with optional filters. | | `tavus_builder_get` | `builder_id` | Fetch a single builder by ID. | | `tavus_builder_delete` | `builder_id` | Delete a builder session. | | `tavus_builder_chat` | `builder_id`, `message` | Send a chat turn to the builder. Returns assistant text, autocomplete suggestions, a `draft_ready` flag, and target sections for scoped updates. | | `tavus_builder_chat_history` | `builder_id`, `limit=50` | Fetch chat history for a builder session. | | `tavus_builder_append_messages` | `builder_id`, `messages` | Append messages to builder chat history. | | `tavus_builder_update_objectives` | `builder_id`, `message` | Update objectives based on a user feedback message. | | `tavus_builder_update_guardrails` | `builder_id`, `message` | Update guardrails based on a user feedback message. | | `tavus_builder_update_greeting` | `builder_id`, `message` | Update the greeting/opening based on feedback. | | `tavus_builder_update_personality` | `builder_id`, `message`, `pal_name=False`, `system_prompt=False` | Update PAL personality/system prompt based on feedback. Optionally include PAL name and/or system prompt fields. | | `tavus_builder_publish` | `builder_id` | Publish the builder's drafted PAL. | ## Chat mode (text-only) | Tool | Parameters | Description | | ------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `tavus_chat_start` | `pal_id`, `custom_greeting=None`, `conversation_name=None` | Start a text-only conversation with a PAL. Use this to test a built PAL by sending typed turns; no face video is rendered. | | `tavus_chat_turn` | `conversation_id`, `text`, `timeout_s=20.0` | Send one user turn and wait for the PAL's reply. Returns `{text: }`. | | `tavus_chat_end` | `conversation_id` | End a chat-mode conversation. | ## PAL preview & build-and-verify | Tool | Parameters | Description | | ---------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tavus_pal_preview` | `pal_id`, `face_id=None`, `conversation_name=None` | Start a full audio/video preview conversation against a PAL and return `{conversation_id, conversation_url, ...}`. Hand the URL to a human for visual verification. | | `tavus_pal_build_and_verify` | `prompt`, `face_id=None`, `max_rounds=4`, `answers=None` | Build a PAL from one creator prompt (optionally using supplied answers for builder follow-ups), then publish and validate via CVI chat mode. When `face_id` is omitted, a default is selected and attached. | See [Agentic PAL building & testing](/sections/agent-tools/pal-build-and-verify) for expected agent usage, CLI usage, and how to read the simulated-turn verdict. # Overview Source: https://docs.tavus.io/sections/agent-tools/overview Build a PAL, wire its tool calls into your own code, and test the integration from your editor with the MCP server or your terminal with the CLI. Tavus MCP is the toolkit for building a PAL and integrating its tool calls into your own application. It gives an AI coding agent, or you at a terminal, direct access to the operations behind a Tavus PAL: create and patch PALs, define and attach the tools a PAL can call, and start test conversations to confirm everything works. **For AI agents:** Tavus MCP documented here is the **development MCP** for creating PALs, defining tools, and testing tool-call integrations against the Tavus API. It is not the **Tavus Docs MCP** for searching this documentation site (`https://docs.tavus.io/mcp`). For live docs search and page retrieval, see [Agents & automation](/sections/agents-and-automation). It is separate from the Conversational PAL Builder in PAL Maker. PAL Maker is the UI for drafting a PAL. This toolkit is for developers wiring a PAL into code: defining the tool contract, writing the handlers that respond when the PAL calls a tool, and testing that exchange without leaving the editor or shell. ## The use case A useful PAL calls tools to look something up, change what is on screen, or take an action in your app, then responds based on the result. Two things have to stay in sync for that to work: * The PAL has to know which tools exist and when to call them. * Your code has to handle those calls and return a result. The MCP server and CLI let you author both sides and test them together. See [bidirectional tool calls](/sections/agent-tools/mcp-server#bidirectional-tool-calls) for how the exchange works. ## Two surfaces Connect Codex, Claude Code, Cursor, or any MCP client over HTTPS with per-user OAuth. Your agent builds the PAL, wires the tools into your codebase, and tests them. The `tavus` command for interactive and scripted access to every operation. Suited to humans at a terminal and to CI automation. Both call the same Tavus API, so the available operations are the same across them. For the autonomous PAL test loop, see [Agentic PAL building & testing](/sections/agent-tools/pal-build-and-verify). For the full catalog of MCP tools, see the [MCP tools reference](/sections/agent-tools/mcp-tools-reference). ## Which should I use? Best when you work in an editor with an AI agent and want it to build the PAL and wire tool calls into your code for you. * Transport: HTTP at an `/mcp` endpoint. * Auth: browser-based OAuth through the PAL Maker. A per-user key is forwarded to the Tavus API as `x-api-key`, so no key sits in your client config. * Add it to Codex or Claude Code. For Codex: ```bash theme={null} codex mcp add tavus --url https://mcp.tavus.io/mcp ``` For Claude Code: ```bash theme={null} claude mcp add -s user --transport http tavus https://mcp.tavus.io/mcp ``` For Codex, start the OAuth flow explicitly with: ```bash theme={null} codex mcp login tavus ``` Do not put a Tavus API key or shared bearer token in your MCP client config. Authentication is handled through the OAuth flow. Best for humans at a terminal and for scripted automation in CI. * Auth: `tavus auth login` stores an env-scoped key in your OS keychain, or set `TAVUS_API_KEY` directly for automation. * Outputs JSON by default. Many list commands also render Rich tables. ```bash theme={null} TAVUS_API_KEY=... tavus pal list ``` ## Choosing a target environment Both surfaces default to production (`PROD`). To target the test database, set `TAVUS_ENV=TEST` or pass `--env TEST` to the CLI. For the MCP server, keep the endpoint aligned with the portal environment that minted your key. A `TEST` key used against a production server, or the reverse, makes downstream Tavus API calls return `401`. ## Next steps Connect your agent and wire bidirectional tool calls. Run simulated turns and judge whether a new PAL works. Authenticate and run `tavus` commands. Browse the full catalog of MCP tools and their parameters. # Agentic PAL Building & Testing Source: https://docs.tavus.io/sections/agent-tools/pal-build-and-verify Use the Tavus MCP server or CLI to build a new PAL in a loop: adjust configuration, run simulated CVI chat turns, judge the result, and refine until the PAL behaves as intended. The agentic PAL building & testing flow is an autonomous loop for a new Tavus PAL. It builds a PAL from a creator prompt, publishes it, runs simulated text turns through CVI chat mode, and returns a structured verdict so an agent can decide whether the PAL works or whether the system prompt and configuration need another pass. Use it when an agent needs a single answer: **did the PAL I asked for actually behave correctly?** Conversations started during build-and-verify - including CVI chat-mode probes and full preview URLs - incur charges the same as any other conversation on your account. Use `tavus_pal_build_and_verify` when Codex, Claude Code, Cursor, or another MCP client should drive the whole build, test, and judge loop. Use `tavus pal build` when you want the same workflow from a shell, with JSON output for scripts or CI-style checks. ## What the loop does The flow opens a conversational builder session, sends the creator prompt, applies builder updates to personality, greeting, objectives, and guardrails, and publishes the resulting PAL. The MCP tool can run this autonomously. The CLI is suited to terminal use and may prompt you for builder follow-up answers before publishing. If you pass `face_id`, the flow validates that face and attaches it to the PAL. If you omit it, Tavus selects and attaches a default face from the account's available faces. After publish, Tavus reads the PAL spec and generates validation probes. The probes target the PAL's objectives, adversarial guardrail cases, attached knowledge base documents, and attached tools. The flow starts a CVI chat-mode conversation and sends each probe as a user turn. Chat mode uses the same PAL configuration but skips Daily/video rendering, so it is fast enough for agent regression checks. Tavus judges the resulting transcript against the PAL spec and returns a verdict with evidence for objectives, guardrails, knowledge base usage, and tool behavior. The public MCP and CLI wrappers perform one bounded refinement pass when the first verdict is not a pass. The builder driver, probe generator, face selector, and judge run on Tavus infrastructure. The caller only needs normal Tavus authentication for the selected environment; no client-side LLM key is required. ## Choosing the right surface | Use this | When | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `tavus_pal_build_and_verify` | An MCP-connected coding agent should create, test, and judge a new PAL in one tool call. | | `tavus pal build` | You want a reproducible terminal command and JSON output for a human or script to inspect. | | `tavus_chat_start` / `tavus_chat_turn` | You already have a PAL and only want to run specific text probes against it. | | `tavus_pal_preview` | You need a full audio/video conversation URL for human visual verification after text-mode validation passes. | ## MCP usage Ask the agent to call the MCP tool with a concrete creator prompt: ```text theme={null} tavus_pal_build_and_verify( prompt="Create a concise onboarding coach for new API developers. It should ask what they are building, recommend the right Tavus integration path, and avoid making pricing promises.", max_rounds=4 ) ``` The tool returns IDs, the build transcript, generated probes, the smoke-test transcript, and the verdict: ```json theme={null} { "builder_id": "b...", "pal_id": "p...", "face_id": "r...", "pal_url": "https://maker.tavus.io/dev/pals/update?pal_id=p...", "validated": true, "probes": [ "I am building a support assistant. Which Tavus integration should I use?", "Can you promise me this will cost less than my current vendor?" ], "smoke_transcript": [ { "role": "user", "text": "I am building a support assistant. Which Tavus integration should I use?" }, { "role": "assistant", "text": "..." } ], "verdict": { "overall": "pass", "summary": "The PAL asks for context, recommends the correct integration path, and avoids pricing promises." } } ``` Agents should check `verdict.overall` first, then inspect `verdict.summary`, `smoke_transcript`, and any failing evidence fields when the result is `partial` or `fail`. ## CLI usage Run the same workflow from a shell: ```bash theme={null} tavus pal build \ --prompt "Create a concise onboarding coach for new API developers. It should ask what they are building, recommend the right Tavus integration path, and avoid making pricing promises." \ --max-rounds 4 \ --json > build-result.json jq '.validated, .verdict' build-result.json ``` Use `--face-id ` when you need a specific face/voice. Otherwise, Tavus selects a default face for the new PAL. For agent automation, prefer `--json` and assert on `validated` or `verdict.overall` instead of exact assistant wording. PAL replies are non-deterministic, so the verdict and evidence fields are the stable output. ## Reading the verdict | Field | Meaning | | ------------------------ | -------------------------------------------------------------------- | | `validated` | Boolean shortcut for `verdict.overall === "pass"`. | | `verdict.overall` | `pass`, `partial`, or `fail`. | | `verdict.objectives` | Whether the PAL satisfied each objective, with evidence. | | `verdict.guardrails` | Whether each guardrail held under adversarial probes, with evidence. | | `verdict.knowledge_base` | Whether attached documents were used when a probe required them. | | `verdict.tools` | Whether attached tools appeared to be invoked when required. | | `smoke_transcript` | The simulated user turns and PAL replies used by the judge. | | `refine_rounds_used` | Number of automatic refinement rounds used by the wrapper. | Treat `partial` as actionable feedback, not a transport failure. Read the failing evidence, tighten the creator prompt or PAL system prompt, then run the flow again or patch the PAL directly with `tavus_patch_pal`. ## What this does not replace Build-and-verify is a text-mode behavioral check. It does not validate visual rendering, facial expression quality, audio latency, room join behavior, or user-device permissions. After a PAL passes the simulated turns, use `tavus_pal_preview` or `tavus pal preview` to hand a full conversation URL to a human for visual QA. For existing PALs, do not rebuild just to test them. Start chat mode directly with `tavus_chat_start` and `tavus_chat_turn`, or use the CLI `tavus chat` commands to run targeted probes. ## Common failures | Failure | What to do | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `Face not found` | The supplied `face_id` does not exist in the selected environment. Pick a valid face or omit `face_id`. | | Face selection failed | Tavus could not choose or attach a default face. Pass `--face-id` or fix the account's face catalog. | | Builder did not reach `draft_ready` | The flow still publishes and tests the draft, but the verdict may be `partial`. Re-run with a more specific creator prompt. | | Chat turn timeout | The probe produced no assistant reply before the timeout. Inspect `smoke_transcript` and retry or simplify the prompt. | | Judge returned `partial` or `fail` | Use the verdict evidence as a prompt-edit checklist, then patch or rebuild the PAL. | # 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. **For AI agents:** The MCP endpoint documented on this page (`https://docs.tavus.io/mcp`) is the **Tavus Docs MCP** - it searches and retrieves pages from this documentation site. It is not the Tavus development MCP for building PALs, wiring tool calls, or running test conversations. For that toolkit, see [Tavus MCP & CLI](/sections/agent-tools/overview). ## 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` | | **Tavus Docs MCP** | Hosted Model Context Protocol server for this docs site: search plus fetch full pages from the indexed documentation (see [Tavus Docs MCP](#tavus-docs-mcp)) | `https://docs.tavus.io/mcp` | ## When to use what * **Tavus Docs MCP:** Interactive tools that need live search and current page retrieval against the indexed documentation 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. ## Tavus Docs MCP An MCP endpoint is available for this documentation site - not for building PALs or testing Tavus API tool calls; for that, use [Tavus MCP & CLI](/sections/agent-tools/overview). Configure docs MCP 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 ## New Features * **Magic Canvas image support:** The `image` component now renders images from your Knowledge Base or an allowlisted website during a conversation. [Learn more](/sections/conversational-video-interface/magic-canvas/components/image) * **Auto-start recordings:** Set `auto_start_recording` on create-conversation and Tavus starts the recording about a second after the PAL joins, with no client-side call to `startRecording()`. Requires `recording_storage` and a Tavus-hosted room. [Learn more](/sections/conversational-video-interface/quickstart/conversation-recordings#start-recording-automatically) ## Changes * **New default LLM - `tavus-gemma-4`:** A faster, smarter, tuned version of `tavus-gemma-4` is now the recommended default. It makes for the snappiest conversations while staying strong on intelligence and tool use. [Learn more](/sections/conversational-video-interface/pal/llm#1-model) * **Deprecated LLM:** `tavus-gemma-4-thinking` is deprecated in favor of the new tuned `tavus-gemma-4`. ## New Features * **EU AI Act controls:** New AI disclosure controls on the PAL - `disclosure_type`, `verbal_disclosure`, and `visual_disclosure` - plus a per-conversation `policy: "eu"` that auto-applies the disclosure and switches Raven-1 to `limited` emotion recognition when PAL fields are left on `auto`. [Learn more](/sections/onboarding-guide/eu-ai-act) * **Zoom support:** PALs can now join Zoom calls in addition to Google Meet. Invite the PAL's `@tavusinvite.com` address to a calendar event with a Zoom link and it joins on its own. [Learn more](/sections/conversational-video-interface/pal/meetings) ## New Features * **Expanded Tavus-Hosted LLM Selection:** Added support for new Tavus-hosted LLMs: `tavus-gemma-4`, `tavus-gpt-5.6-sol`, and `tavus-gpt-5.6-terra`. [Learn more](/sections/conversational-video-interface/persona/llm#tavus-hosted-models) ## Changes * **Deprecated LLMs:** The following Tavus-hosted LLMs are now deprecated: `tavus-glm-4.7`, `tavus-gpt-oss`, `tavus-claude-haiku-4.5`, `tavus-gpt-5.2`, and `tavus-gemini-3-flash`. ## New Features * **Zero Data Retention:** Account-level and programmatic support for Zero Data Retention is now available, enabling customers to opt out of data persistence across Tavus services. ## Enhancements * **Performance:** Improved LiveKit pipeline performance by 15%! ## New Features * **PAL Maker:** Describe a PAL in plain language and have it configured end to end (system prompt, face, objectives, guardrails, tools, knowledge base, and advanced settings), then talk to it in the same session. Removes the need to configure each layer by hand. Learn more * **Starter Templates:** Fork a complete, live experience into your account with no code (Interviewer, SDR, Medical Intake, Trivia Host), or open the GitHub repo behind it. Learn more * **Meetings (Google Meet):** Send a PAL into a Google Meet call. It joins on its own past the admit prompt, sees and hears the room, and can run the meeting. Invite it via calendar invite or pass a meeting URL when creating a conversation. [Learn more](/sections/conversational-video-interface/pal/meetings) * **Magic Canvas:** A shared interactive surface rendered on top of the video stream. The PAL surfaces the right component at the right moment. Six components at launch: question, text, input, calendar, chart, and alert. [Learn more](/sections/conversational-video-interface/magic-canvas/overview) * **Presentation Mode:** Upload a deck or source material, Tavus indexes it, and the PAL presents from it, takes questions, and pulls the right slide on demand. Supports two modes: Walk the deck (end to end) and On-demand. [Learn more](/sections/conversational-video-interface/skills/presentation) * **Embeddable Widgets:** Drop a PAL onto any site with a single line of code, scoped and auto-provisioned to your account, with no SDK. Place it in any corner or inline, and customize branding to match your site. [Learn more](/sections/deployments/widget) * **Landing Pages:** Deploy a PAL on a ready-made hosted landing page, no setup required. [Learn more](/sections/deployments/landing-page) * **Internet Search:** Give a PAL real-time web search during a conversation. Attach the `internet_search` skill - pure on/off, no configuration. [Learn more](/sections/conversational-video-interface/skills/internet-search) ## Enhancements * **Tool Calling:** Tools can now call any third-party API (including GraphQL) with custom auth and request bodies, no middleware. New on-resolve modes (fire and forget, pull into context, generate a response) control how results enter the conversation, and tools are reusable across PALs. [Learn more](/sections/conversational-video-interface/pal/tools) ## 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 PALs. 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 PAL 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 face fails:** [Learn more](/sections/errors-and-status-details#face-training-errors) ## New Features * **AI Image Fixer API support:** [Create Face](/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 Face):** Get instant feedback, before recording, on whether your camera setup meets our requirements. ## Enhancements * **Less footage required (Video to Face):** We now only require 1 minute of video, down from the 2 minutes previously needed. * **Simpler in-portal recording flow (Video to Face):** A streamlined recording experience in the portal to help you capture high-quality recordings. ## New Features * **Image to Face:** Build a face 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:** PALs 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 PAL still hears everything that is said and responds with full conversation history once the wake phrase is detected. Learn more ## New Features * **Idle Engagement:** Faces 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 PAL and the user with a `role` field (`"pal"` or `"user"`) identifying the speaker. Tavus also sends legacy duplicate events with `"replica"` instead of `"pal"`. `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 PAL Maker 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 PAL 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 face and user utterances. Use it to power closed captioning and build accurate transcripts - especially when a user interrupts the face, 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 PAL 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 PAL via the TTS layer - any updates automatically propagate to all linked PALs 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:** PALs now know when they have been interrupted. This allows the PAL 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 Face Stopped Speaking:** The `conversation.replica.stopped_speaking` event now includes a `duration` field (how long the PAL spoke in seconds) and an `interrupted` field (`true`/`false`) indicating whether the PAL 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 PAL richer visual context during conversations. ## Changes * **PAL**`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 PALs to respond with greater emotional intelligence. The model is now the default for all new PALs. Enable it by setting `perception_model_name` in your PAL 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 PALs 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 PALs, 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 PALs is now `tavus-gpt-oss`. All remaining `tavus-llama-4` PALs 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 PAL'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 PAL 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 PALs:** Search now supports fuzzy matching for PALs, 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 PALs while keeping conversations safe, compliant, and on-brand. Ideal for complex workflows and regulated industries. Learn more → * **PAL Builder:** A guided creation flow in the PAL Maker to shape AI PALs with goals, behaviors, and style - then test or launch within minutes. ## New Features * **Events Console:** A new events console in the PAL Maker 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 PAL Maker, including transcripts with speaker roles and perception analysis showing how your AI PAL sees, hears, and responds. ## New Features * **PAL Layer Controls:** Enable or disable layers like Sparrow directly within a PAL and adjust sensitivity settings in real time from the PAL Maker side panel. * **PAL editing in PAL Maker:** We've added new editing capabilities to help you refine your PALs more efficiently. You can now update system prompt, context, and layers directly in our PAL Maker, plus duplicate existing PALs to quickly create variations or use them as starting points for new projects. Find these new features in your PAL Library at maker.tavus.io/dev. ## 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 PAL Maker:** You can now specify the language of a conversation directly in the PAL Maker, including a new multilingual option for dynamic, real-world interactions. ## New Features * **Llama 4 Support:** Your PAL 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 PAL 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. * PAL API : Enabled patch updates to PALs. ## 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 * **Face 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 faces. 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 faces. **Features:** * **Main Video Display**: Large video area showing the AI face 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 face 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 face 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 face, 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 face, 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 `face` 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 `face` 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-face-ids` | `/hooks/use-face-ids` | None | `string[]` | `CVIProvider` and active call | `/hooks/use-face-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 face participants in a call. ```bash theme={null} npx @tavus/cvi-ui@latest add use-face-ids ``` A React hook that returns the IDs of all Tavus face participants in a call. **Purpose:** * Filters and returns participant IDs where `user_id` includes 'tavus-face' **Return Value:** * `string[]` - Array of face participant IDs ```tsx theme={null} import { useReplicaIDs } from './hooks/use-face-ids'; ``` ```tsx theme={null} const ids = useReplicaIDs(); // ids is an array of participant IDs for Tavus faces ``` ### 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('Face 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 `user` and PAL roles and exposes the latest caption to your UI. **Purpose:** * Streams captions for both the user and the PAL 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" | "pal" | "replica"; text: string }` (`replica` is a legacy duplicate of `pal`) ```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 === 'pal' || caption.role === 'replica' ? 'PAL' : '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 faces 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 face. ```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 `face` roles, and exposes a `sendMessage` function that dispatches `conversation.respond`. **Purpose:** * Builds a chronological transcript of `user` and `face` 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" | "pal" | "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 === 'pal' || m.role === 'replica' ? 'PAL' : 'You'}: {m.text}
    • ))}