@tavus/widget 0.18.0 → 0.19.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +83 -12
- package/dist/index.iife.js +29 -29
- package/dist/index.mjs +5470 -5207
- package/package.json +17 -12
package/README.md
CHANGED
|
@@ -1,22 +1,27 @@
|
|
|
1
1
|
# @tavus/widget
|
|
2
2
|
|
|
3
|
-
Tavus
|
|
3
|
+
Add a face-to-face Tavus PAL to any website with the `<tavus-widget>` custom element. It renders a floating launcher that opens into Tavus Conversational Video Interface (CVI), the complete experience: preview, device check, the live call, captions, chat and the after-call screen. Tavus runs the conversation; your page needs no backend and no API key, only a deployment id.
|
|
4
4
|
|
|
5
|
-
Create and configure a deployment
|
|
5
|
+
Create and configure a deployment, and copy the widget snippet, in the [Tavus PAL Maker](https://maker.tavus.io). Launcher variant and position, theme, copy, modality, call limits, bot protection and allowed origins are all deployment settings; the element picks them up on load.
|
|
6
|
+
|
|
7
|
+
- Documentation: [Widget](https://docs.tavus.io/sections/deployments/widget) and [Host communication](https://docs.tavus.io/sections/deployments/host-communication)
|
|
8
|
+
- Working examples: [tavus-examples](https://github.com/Tavus-Engineering/tavus-examples/tree/main/examples#readme)
|
|
9
|
+
- Inline surface inside your layout instead of a launcher: [`@tavus/embed`](https://www.npmjs.com/package/@tavus/embed)
|
|
6
10
|
|
|
7
11
|
## Install
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
Serve the page over HTTPS: browsers only allow camera, microphone and WebRTC in a secure context. `http://localhost` counts as secure, so local development works. On a plain-http page the element shows its generic "PAL is unavailable" screen instead of starting, and the browser console names the HTTPS cause.
|
|
10
14
|
|
|
11
|
-
|
|
12
|
-
<script src="https://unpkg.com/@tavus/widget@latest"></script>
|
|
15
|
+
### CDN (static pages, site builders)
|
|
13
16
|
|
|
17
|
+
```html
|
|
14
18
|
<tavus-widget deployment-id="YOUR_DEPLOYMENT_ID"></tavus-widget>
|
|
19
|
+
<script src="https://unpkg.com/@tavus/widget@latest"></script>
|
|
15
20
|
```
|
|
16
21
|
|
|
17
|
-
For a pinned version, use `https://unpkg.com/@tavus/widget@0.
|
|
22
|
+
For a pinned version, use a versioned URL such as `https://unpkg.com/@tavus/widget@0.19.0`. On Webflow, Framer, Wix or Squarespace, paste both lines into the site's custom code before `</body>` and publish.
|
|
18
23
|
|
|
19
|
-
### npm (bundler
|
|
24
|
+
### npm (bundler and framework apps)
|
|
20
25
|
|
|
21
26
|
```bash
|
|
22
27
|
npm install @tavus/widget
|
|
@@ -26,18 +31,84 @@ npm install @tavus/widget
|
|
|
26
31
|
import "@tavus/widget";
|
|
27
32
|
```
|
|
28
33
|
|
|
29
|
-
Importing the package registers the `<tavus-widget>` custom element as a side effect
|
|
34
|
+
Importing the package registers the `<tavus-widget>` custom element as a side effect and ships JSX typings, so the tag type-checks in React:
|
|
30
35
|
|
|
31
36
|
```tsx
|
|
32
37
|
<tavus-widget deployment-id="YOUR_DEPLOYMENT_ID" />
|
|
33
38
|
```
|
|
34
39
|
|
|
40
|
+
Keep the import static rather than a lazy `import("@tavus/widget")`, which makes Vite's dev server re-optimise dependencies mid-session and can leave the page with two copies of React. In a server-rendered framework (Next.js, Remix, Nuxt, SvelteKit) the element is browser-only. Import it inside a client component (`"use client"` in Next.js) or after mount.
|
|
41
|
+
|
|
35
42
|
## Attributes
|
|
36
43
|
|
|
37
|
-
| Attribute
|
|
38
|
-
|
|
|
39
|
-
| `deployment-id`
|
|
40
|
-
| `override-config`
|
|
44
|
+
| Attribute | Type | Description |
|
|
45
|
+
| ------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
46
|
+
| `deployment-id` | string | The Tavus deployment id. The element fetches its configuration from `/v2/deployments/:id/init`. |
|
|
47
|
+
| `override-config` | JSON string | Deep-merged over the fetched configuration for page-specific copy or behaviour, for example `{"customization":{"show_haircheck":false}}`. |
|
|
48
|
+
| `conversational-context` | string | Text the PAL knows during this conversation: who the visitor is, what the page is about. |
|
|
49
|
+
| `custom-greeting` | string | The PAL's first line. |
|
|
50
|
+
| `memory-stores` | string | Comma-separated memory tags, each a stable identifier for this visitor (a user id, not a display name), so the PAL remembers that visitor across conversations. One shared value would give every visitor the same memory. |
|
|
51
|
+
| `camera-on-start` | `"on" \| "off"` | Whether the visitor's camera is on when the call starts. Defaults to `on`. |
|
|
52
|
+
|
|
53
|
+
The launcher's variant, position and avatar are deployment settings, not attributes. Attribute shapes and defaults are kept current in the [Widget reference](https://docs.tavus.io/sections/deployments/widget).
|
|
54
|
+
|
|
55
|
+
## Talking to the element
|
|
56
|
+
|
|
57
|
+
The element dispatches events the page can listen to and installs methods the page can call. Everything below is documented in full, with payloads and types, in [Host communication](https://docs.tavus.io/sections/deployments/host-communication).
|
|
58
|
+
|
|
59
|
+
Events bubble from the element to `document`:
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
const el = document.querySelector("tavus-widget");
|
|
63
|
+
el.addEventListener("tavus:ready", (e) => {}); // { deploymentId } — methods are installed from here on
|
|
64
|
+
el.addEventListener("tavus:conversation-started", (e) => {}); // { conversationId }
|
|
65
|
+
el.addEventListener("tavus:conversation-ended", (e) => {}); // { conversationId }
|
|
66
|
+
el.addEventListener("tavus:error", (e) => {}); // { code, message }
|
|
67
|
+
el.addEventListener("tavus:tool-call", (e) => {}); // { name, arguments, tool_call_id?, seq?, turn_idx? }
|
|
68
|
+
el.addEventListener("tavus:protocol-message", (e) => {}); // every protocol event, e.g. conversation.utterance
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Also `tavus:conversation-created`, `tavus:state-change` and `tavus:mode-change`. `tavus:chat-message` and `tavus:message` are in the type definitions for compatibility and never fire.
|
|
72
|
+
|
|
73
|
+
Methods exist once `tavus:ready` has fired. The widget adds `open()` and `close()` for the popup; a start from the page also opens it, so a host button can be the only thing the visitor touches:
|
|
74
|
+
|
|
75
|
+
```js
|
|
76
|
+
el.open();
|
|
77
|
+
el.close();
|
|
78
|
+
el.startConversation(); // same path as the visitor pressing Start; never rejects. Most failures arrive as tavus:error;
|
|
79
|
+
// the daily limit, a busy PAL and a bot check that cannot run arrive as tavus:mode-change with mode "unavailable"
|
|
80
|
+
await el.createConversation(); // create the room now so the next start joins without the wait
|
|
81
|
+
el.endConversation();
|
|
82
|
+
el.sendMessage({
|
|
83
|
+
event_type: "conversation.respond",
|
|
84
|
+
properties: { text: "Tell me about pricing" },
|
|
85
|
+
});
|
|
86
|
+
el.updateConfig({ customization: { style: { mode: "dark" } } });
|
|
87
|
+
el.destroy();
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Interactions you can send: `conversation.respond`, `conversation.echo`, `conversation.interrupt`, `conversation.append_llm_context`, `conversation.overwrite_llm_context` and `conversation.tool_result` (the reply to a `tavus:tool-call`).
|
|
91
|
+
|
|
92
|
+
In a bundled app, `TavusIntegration` wraps the same methods with typed event subscriptions. Create it after the element is in the DOM:
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
import { TavusIntegration } from "@tavus/widget";
|
|
96
|
+
|
|
97
|
+
const tavus = new TavusIntegration(); // defaults to "tavus-widget"
|
|
98
|
+
// tavus:ready fires once; if the element is already ready when this runs, start right away.
|
|
99
|
+
const el = document.querySelector("tavus-widget");
|
|
100
|
+
if (typeof el?.startConversation === "function") tavus.startConversation();
|
|
101
|
+
else tavus.on("tavus:ready", () => tavus.startConversation());
|
|
102
|
+
tavus.on("tavus:conversation-started", (e) => {
|
|
103
|
+
console.log(e.detail.conversationId);
|
|
104
|
+
// Messages are accepted only while the call is live; plain strings are wrapped as conversation.respond.
|
|
105
|
+
tavus.sendMessage("Tell me about pricing");
|
|
106
|
+
});
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Examples
|
|
110
|
+
|
|
111
|
+
The widget and the embed share the same host API, so the [embed examples](https://github.com/Tavus-Engineering/tavus-examples/tree/main/examples#readme) show every integration pattern that applies here too: starting from the page's own button, pre-creating the conversation, reading a transcript from protocol events, and resetting between visitors. The documentation index for coding agents is at [docs.tavus.io/llms.txt](https://docs.tavus.io/llms.txt).
|
|
41
112
|
|
|
42
113
|
## License
|
|
43
114
|
|