Skip to main content

​
Overview

<tavus-embed> renders a Tavus conversation inline, inside your own layout. It uses the same managed deployment flow as the widget, but instead of a floating launcher the experience lives where you put the element - a product page, a demo section, a dashboard panel. The embed renders in a shadow DOM and adapts to its container: it maintains a 16:9 aspect ratio in wide containers and switches to a compact 9:16 portrait layout in narrow ones. PALs with a Magic Canvas skill render cards in the embed automatically. See Hosted embed & widget for Canvas-specific behavior.

​
Installation

<div style="width: 720px; aspect-ratio: 16 / 9;">
  <tavus-embed deployment-id="YOUR_DEPLOYMENT_ID"></tavus-embed>
</div>
<script src="https://unpkg.com/@tavus/embed"></script>
To pin an exact version instead of tracking the latest beta, use a versioned URL such as https://unpkg.com/@tavus/embed@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: 
<div style="width: 720px; aspect-ratio: 16 / 9;">
  <tavus-embed
    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-embed>
</div>
<script src="https://unpkg.com/@tavus/embed"></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): 
<div style="width: 720px; aspect-ratio: 16 / 9;">
  <tavus-embed
    deployment-id="YOUR_DEPLOYMENT_ID"
    memory-stores="YOUR_DEPLOYMENT_ID-user-12345"
  ></tavus-embed>
</div>
<script src="https://unpkg.com/@tavus/embed"></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.

​
Sizing

<tavus-embed> fills its parent: the host element is width: 100%; height: 100%; max-height: 100vh; overflow: hidden. Give it a parent with a definite size, or wrap it in a container with aspect-ratio: 
<div style="width: 720px; aspect-ratio: 16 / 9;">
  <tavus-embed deployment-id="YOUR_DEPLOYMENT_ID"></tavus-embed>
</div>
If the parent has no resolved height - for example a chain of auto-height flex containers - the embed cannot size itself. Give the parent an explicit height or an aspect-ratio, or ensure the full chain (html, body, root element, container) resolves to a real height.

​
Interacting from the page

The embed 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.