> 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/react.md).

# Get started with React

Install the Convai Web SDK in a React app and add a ready-made chat and voice widget, with optional camera and screen sharing for your character.

Add a Convai character to a React app with the `useConvaiClient` hook and the `ConvaiWidget` component. Use this page when setting up the React bindings for the first time. At the end, the page shows a widget button that opens a voice and text conversation with your character.

### Prerequisites

* A React 18 or 19 app with a bundler. `react` and `react-dom` 18 or 19 are peer dependencies of the SDK.
* A Convai account and an API key from <code class="expression">space.vars.dashboard\_url</code>.
* The ID of the character to connect to.

### Install the package

The React bindings ship in `@convai/web-sdk` and are imported from the `@convai/web-sdk/react` subpath. There is no separate React package.

{% tabs %}
{% tab title="npm" %}

```bash
npm install @convai/web-sdk
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm add @convai/web-sdk
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn add @convai/web-sdk
```

{% endtab %}
{% endtabs %}

### Add the widget

`useConvaiClient` creates one client for the component and stores the config. `ConvaiWidget` renders the conversation UI and connects with that stored config when someone first selects its button, so the browser asks for the microphone only after a user action.

{% code title="src/App.tsx" %}

```tsx
import { useConvaiClient, ConvaiWidget } from '@convai/web-sdk/react';

export default function App() {
  const convaiClient = useConvaiClient({
    apiKey: 'YOUR_API_KEY',
    characterId: 'YOUR_CHARACTER_ID',
    endUserId: 'user-123',
  });

  return <ConvaiWidget convaiClient={convaiClient} />;
}
```

{% endcode %}

The widget plays the character's voice, captures the microphone in voice mode, and shows the conversation as it streams.

`endUserId` is optional. Pass a stable, unique ID for each person, such as a UUID, to enable long-term memory and per-user analytics. Without it the session is anonymous. See [Use long-term memory](/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/long-term-memory.md).

{% hint style="danger" %}
An API key in client code is readable by anyone who opens the page. For a public page, create a short-lived auth token on your server and pass `authToken` instead of `apiKey`. See [Connect with an auth token](/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/auth-tokens.md).
{% endhint %}

### Enable camera and screen sharing

Set `enableVideo: true` to connect with the `"video"` connection type, which carries audio, camera video, and screen share. `startWithVideoOn` turns the camera on at connect; it defaults to `false`. The widget shows camera and screen share buttons in its settings tray when the connection type is `"video"`; hide either with `showVideo={false}` or `showScreenShare={false}`.

```tsx
const convaiClient = useConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  enableVideo: true,
  startWithVideoOn: false,
});

return <ConvaiWidget convaiClient={convaiClient} showVideo showScreenShare />;
```

### Verify the integration

Start your dev server and open the page. Select the widget button, allow microphone access, and say something to the character.

{% hint style="success" %}
The widget opens in voice mode, your speech appears as a message, and the character answers in text and speech.
{% endhint %}

### Next steps

<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>useConvaiClient hook reference</strong><br>Everything the hook returns, including its React-only state.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react/useconvaiclient-hook.md">useConvaiClient hook reference</a></td></tr><tr><td><strong>ConvaiWidget component reference</strong><br>Props, defaults, and what the widget does on your behalf.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react/convaiwidget.md">ConvaiWidget component reference</a></td></tr><tr><td><strong>Add lip sync in React</strong><br>Drive a 3D face from the blendshape stream in a render loop.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react/real-time-lipsync.md">Add lip sync in React</a></td></tr><tr><td><strong>Build a custom UI in React</strong><br>Replace the widget with your own messages and controls.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react/custom-ui-and-advanced-usage.md">Build a custom UI in React</a></td></tr><tr><td><strong>Add an audio visualizer in React</strong><br>Draw the character's voice level with the Web Audio API.</td><td><a href="/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react/audio-visualizer-optional.md">Add an audio visualizer in React</a></td></tr></tbody></table>


---

# 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/react.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.