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
- CDN (static pages)
- npm (bundler / framework apps)
Add the element and the script tag anywhere in your HTML: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
Context and greeting
conversational-context and custom-greeting let you tailor a single conversation at start time:
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):
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: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.