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
- CDN (static pages)
- React
- Next.js
https://unpkg.com/@tavus/embed@0.19.0. The package is also on npm: @tavus/embed.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. If you omit it, the PAL’s greeting or dynamic_greeting applies. 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 tag is a memory namespace: every conversation that uses the same tag shares one bucket of memories, so the PAL can remember that user across sessions and devices.
Tags 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:
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.Page-specific overrides
Everything the element shows is configured on the deployment in the PAL Maker.override-config lets one page differ without changing the deployment: pass a JSON string and it is deep-merged over the saved configuration at load time. The keys mirror the deployment’s customization object. The ones pages reach for most are show_haircheck (false skips the device check so a start goes straight into the call), preview.title, preview.description and preview.btn_title (the preview screen copy), after_call.title and after_call.description, style.mode ("light", "dark" or "system") and magic_canvas.accent_color.
updateConfig() applies the same kind of patch at runtime; see Host communication.
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:
16 / 9 as the recommended default; a kiosk, a phone layout or a tall sidebar is portrait, with 9 / 16 recommended. Below 56.25rem (900px) of container width the element switches to its compact portrait layout, and when the parent has no definite height it falls back to 16 / 9 above that width and 9 / 16 below. On phones give a landscape wrapper a 9 / 16 box with a media query rather than leaving a short landscape strip. The element’s type scale follows the root font size, so a larger root font gives larger controls on a big screen.
layout="full-screen" is for a section that gives the embed the whole viewport, for example a call page of its own in a multi-step app. It changes the arrangement of the preview screen only: the greeting moves to the top-left corner, the start button is centered above the lower edge, and the in-call fullscreen toggle is dropped since the page is already the app. Sizing stays the page’s, same as inline.
Expanded overlay
expand-options lifts the embed out of your layout into a modal overlay for the conversation, so a small inline card can become a full call without you building a modal. The card returns to the page when the call ends.
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.