> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk.md).

# Convai Web SDK

Find the setup guides, feature how-tos, and API reference for the Convai Web SDK, which connects web apps to Convai characters by voice and text.

The Convai Web SDK, published on npm as `@convai/web-sdk`, connects a web page to a Convai character for real-time voice and text conversation, with optional camera, screen share, lip sync, actions, and emotions. It ships React bindings, a framework-free client, and a prebuilt chat widget for both. These pages describe release <code class="expression">space.vars.web\_sdk\_version</code>.

{% embed url="<https://youtu.be/fK8R0SzuvNI>" %}
Build browser-based conversational avatars with the Convai Web SDK, three.js, and React.
{% endembed %}

### Start here

The quickstart builds a first conversation in React. The two getting-started pages cover installation and the widget for each path; pick the one that matches your app.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Web SDK quickstart</strong><br>Connect to a character from React, send a message, and read its reply.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/quickstart.md">Web SDK quickstart</a></td></tr><tr><td><strong>Get started with React</strong><br>Install the package, add the chat widget, and turn on camera and screen share.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react.md">Get started with React</a></td></tr><tr><td><strong>Get started with vanilla TypeScript</strong><br>Create a client without a framework and mount the vanilla widget.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/vanilla-typescript.md">Get started with vanilla TypeScript</a></td></tr></tbody></table>

### Build a use case

Each use case builds a complete application from several features, step by step.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Build a website assistant</strong><br>Add a character to every page that knows where the visitor is and can navigate, highlight, and fill in forms.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/use-cases/website-assistant.md">Build a website assistant</a></td></tr></tbody></table>

### Add features

Each feature page shows the configuration and the client calls for one capability, for React and vanilla code alike.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Drive facial animation with blendshapes</strong><br>Stream lip sync frames and apply them to a 3D character's morph targets.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/lipsync-and-blendshape.md">Drive facial animation with blendshapes</a></td></tr><tr><td><strong>Handle character actions</strong><br>Receive semantic actions or run client tools and return their results.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/actions.md">Handle character actions</a></td></tr><tr><td><strong>Use character emotions</strong><br>Read the character's emotion and set its state of mind.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/emotions.md">Use character emotions</a></td></tr><tr><td><strong>Update character context at runtime</strong><br>Send scene state, template keys, and files during a session.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/dynamic-context.md">Update character context at runtime</a></td></tr><tr><td><strong>Use long-term memory</strong><br>Let a character remember each person across sessions, and manage those memories.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/long-term-memory.md">Use long-term memory</a></td></tr><tr><td><strong>Connect with an auth token</strong><br>Keep the API key on your server and connect the browser with a token.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/auth-tokens.md">Connect with an auth token</a></td></tr><tr><td><strong>Handle errors and disconnects</strong><br>Tell failures, disconnect reasons, and acknowledgments apart, and reconnect.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/error-handling.md">Handle errors and disconnects</a></td></tr><tr><td><strong>Choose a transport</strong><br>Pick SSE, WebRTC or WebSocket, or combine SSE chat with a realtime voice mode.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/choose-a-transport.md">Choose a transport</a></td></tr><tr><td><strong>Chat over the SSE transport</strong><br>Stream text and optional speech over HTTP, with no WebRTC or microphone.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/sse-transport.md">Chat over the SSE transport</a></td></tr><tr><td><strong>Use the WebSocket transport</strong><br>Connect over WebSocket instead of WebRTC.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/websocket-transport-layer.md">Use the WebSocket transport</a></td></tr><tr><td><strong>Connect to a self-hosted deployment</strong><br>Point the SDK at your own hosts instead of api.convai.com.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/self-hosted-deployments.md">Connect to a self-hosted deployment</a></td></tr><tr><td><strong>Mute the character's voice</strong><br>Silence the character for the listener while it keeps speaking.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/mute-the-characters-voice.md">Mute the character's voice</a></td></tr><tr><td><strong>Host several characters in one room</strong><br>Connect a roster, switch who answers, and change members live (beta).</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/multi-character-rooms.md">Host several characters in one room</a></td></tr><tr><td><strong>Connect to a character version</strong><br>Use a draft, the latest release, or a tag, and manage versions (beta).</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/character-versioning.md">Connect to a character version</a></td></tr><tr><td><strong>Connect to a published text chat</strong><br>Run a credential-free, text-only chat from a publication grant.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/published-text-chat.md">Connect to a published text chat</a></td></tr><tr><td><strong>Render links and link previews</strong><br>Show links the character sends, with optional site cards.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/link-previews.md">Render links and link previews</a></td></tr></tbody></table>

### Look up the API

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>ConvaiClient reference</strong><br>Every property, method, and control interface on the client.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/vanilla-typescript/convaiclient-core-api.md">ConvaiClient reference</a></td></tr><tr><td><strong>Configuration and type reference</strong><br>Every connection option, the package entry points, and the shared types.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/vanilla-typescript/best-practices-and-type-definitions.md">Configuration and type reference</a></td></tr><tr><td><strong>Web SDK event reference</strong><br>Every event the client emits, with its payload.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/event-reference.md">Web SDK event reference</a></td></tr><tr><td><strong>Read raw transport messages</strong><br>Inspect every incoming frame on each transport through rawMessage.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/raw-messages.md">Read raw transport messages</a></td></tr><tr><td><strong>useConvaiClient hook reference</strong><br>What the React hook returns and which fields re-render.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react/useconvaiclient-hook.md">useConvaiClient hook reference</a></td></tr></tbody></table>

The SDK is not the legacy `convai-web-sdk` package documented under [Convai Web SDK (Legacy)](/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk-1.md). The two have different APIs, so code written for one does not run on the other.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
