Skip to main content

​
Overview

<tavus-widget> renders a floating launcher that expands into a full Tavus conversation popup. It is the fastest way to put a deployment on a page: one script tag, one element, no backend. The widget validates the deployment, creates the conversation, and manages the entire call lifecycle. It renders in a shadow DOM, so it is isolated from your page styles.

​
Installation

Add the element and the script tag anywhere in your HTML:
<tavus-widget deployment-id="YOUR_DEPLOYMENT_ID"></tavus-widget>
<script src="https://unpkg.com/@tavus/widget"></script>
To pin an exact version instead of tracking the latest beta, use a versioned URL such as https://unpkg.com/@tavus/widget@0.1.0.

​
Attributes

AttributeTypeDescription
deployment-idstringThe Tavus deployment ID. Fetches configuration from /v2/deployments/:id/init.
conversational-contextstringExtra context injected into the conversation at start (maps to conversational_context). Use it to pass what the deployment should know about the current user or page.
custom-greetingstringOverrides the PAL’s opening line for this conversation (maps to custom_greeting).
memory-storesstringComma-separated list of memory store IDs (maps to memory_stores). Pass a stable per-user identifier to give that user consistent, persistent memory across every conversation with this PAL.

​
Context and greeting

conversational-context and custom-greeting let you tailor a single conversation at start time: 
<tavus-widget
  deployment-id="YOUR_DEPLOYMENT_ID"
  conversational-context="The user is Jane, on the Pro plan, viewing the billing page."
  custom-greeting="Hey Jane, welcome back - want to pick up where we left off?"
></tavus-widget>
<script src="https://unpkg.com/@tavus/widget"></script>
conversational-context overrides the deployment’s configured default context for this conversation; when omitted, the deployment default is used. custom-greeting sets the PAL’s opening line. Empty or whitespace-only values are ignored, so an empty attribute behaves the same as not setting it.

​
Persistent memory

memory-stores lets a returning user pick up where they left off. A store ID is a memory namespace: every conversation that uses the same store ID shares one bucket of memories, so the PAL can remember that user across sessions and devices. See Memories for how memory stores work on the API. Store IDs are global to your account, not scoped to a deployment. A bare user-12345 would share the same memory across every deployment that uses it. To keep memory specific to one deployment, combine the deployment ID with your user ID (similar to namespacing with PAL ID in the Memories guide): 
<tavus-widget
  deployment-id="YOUR_DEPLOYMENT_ID"
  memory-stores="YOUR_DEPLOYMENT_ID-user-12345"
></tavus-widget>
<script src="https://unpkg.com/@tavus/widget"></script>
Pass multiple stores as a comma-separated list (memory-stores="YOUR_DEPLOYMENT_ID-user-12345,team-acme"). Empty or whitespace-only values are ignored.
In the PAL Maker, open your deployment’s Settings and use Unique memory per visitor (maps to customization.conversation.unique_memory_tag; on by default). When that toggle is on and you omit memory-stores, the widget or embed generates an anonymous per-browser ID (stored in localStorage, scoped to that deployment) and sends it as memory_stores on each conversation start. Memory persists for that visitor in the same browser, but not across devices or after storage is cleared. Set memory-stores to your own stable user ID when you want memory to follow a logged-in user everywhere. With the toggle off and no memory-stores attribute, no memory store is sent.

​
Appearance

The launcher’s look and placement are part of the deployment’s configuration in the PAL Maker - no markup changes required:
SettingValuesDescription
Varianttiny, compact, fullSize and detail level of the collapsed launcher.
Positionbottom-right, bottom-left, top-right, top-left, top, bottomWhere the launcher floats on the page.
Expandabledefault, always, start-expandedHow and when the launcher expands into the conversation popup.
Avatarorb, imageThe launcher’s avatar treatment.

​
Interacting from the page

The widget emits lifecycle events (tavus:conversation-started, tavus:tool-call, …) and exposes an imperative API for starting, ending, and messaging the conversation. See Host communication for the full reference.
The widget positions itself relative to the viewport, so it can be placed anywhere in the document - typically just before the closing </body> tag.