> 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-embody/get-started.md).

# Get started with Convai Embody

Create a new React app, render a Convai character as a 3D body with Convai Embody, and talk to it through the Convai chat widget over one connection.

Build a page that shows a Convai character as a 3D body and lets you talk to it. Use this page for a first project: it starts from an empty folder and ends with a character that answers you by voice, with lip sync. The chat widget is part of the setup, not an extra, because a body you cannot talk to is a picture of one.

### Prerequisites

* Node.js 18 or later and a package manager.
* A Convai account, an API key from <code class="expression">space.vars.dashboard\_url</code>, and a character ID.
* A character whose avatar has a published web body, or a default body that applies to it. A character with neither cannot be rendered. See [Troubleshooting](https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-embody/add-a-3d-character-to-a-react-app.md#troubleshooting).

### Create the app

Create a React app with Vite and install Convai Embody, the chat widget, and their peers. `@convai/web-sdk` holds the connection, `three` and `@react-three/fiber` draw the body, and `@convai/web-widget` is the chat panel.

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

```bash
npm create vite@latest my-character -- --template react
cd my-character
npm install @convai/embody @convai/web-widget @convai/web-sdk three @react-three/fiber
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm create vite my-character --template react
cd my-character
pnpm add @convai/embody @convai/web-widget @convai/web-sdk three @react-three/fiber
```

{% endtab %}
{% endtabs %}

### Add your credentials

Put the API key and character ID in a `.env` file at the project root. Vite exposes variables that start with `VITE_` to the page.

{% code title=".env" %}

```bash
VITE_CONVAI_API_KEY=YOUR_API_KEY
VITE_CONVAI_CHARACTER_ID=YOUR_CHARACTER_ID
```

{% endcode %}

{% hint style="danger" %}
An API key is a workspace-wide credential. Anyone who opens a page that ships it can read it. It is right for a local project like this one. For a public page, create a short-lived auth token on your server and pass `token` instead of `apiKey`. See [Auth Tokens](https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/auth-tokens.md).
{% endhint %}

### Render the character and the chat widget

Replace the generated `src/App.jsx` with the component below. `ConvaiCharacter` brings its own canvas, camera, lights, and orbit controls, resolves the character's body, opens the connection, and drives the face. `onReady` hands you the character once its body is loaded and its connection is live. The widget takes that same connection, so chat and lip sync share one session.

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

```jsx
import { useState } from 'react'
import ConvaiCharacter from '@convai/embody/react'
import { ConvaiWidget } from '@convai/web-widget/react'

export default function App() {
  const [client, setClient] = useState(null)

  return (
    <>
      <ConvaiCharacter
        apiKey={import.meta.env.VITE_CONVAI_API_KEY}
        characterId={import.meta.env.VITE_CONVAI_CHARACTER_ID}
        onReady={(character) => setClient(character.client)}
      />
      {client && <ConvaiWidget convaiClient={client} />}
    </>
  )
}
```

{% endcode %}

If the character has Long-Term Memory turned on, the connection also needs an end-user id so the character can tell your users apart. Pass a stable id for the person using your app: `session={{ endUserId: user.id }}`. Without it, connecting fails with "Missing end\_user\_id".

Do not create the widget's client with the Web SDK's `useConvaiClient`. That hook constructs a second `ConvaiClient`, which opens a second connection: the widget would talk to one session while the character lip-syncs to another, so the character stays silent.

Remove the generated styles so the character fills the window. Replace `src/index.css` with:

{% code title="src/index.css" %}

```css
html, body, #root { margin: 0; height: 100%; }
```

{% endcode %}

### Run the app

```bash
npm run dev
```

Open the printed URL. The body downloads first, which takes a few seconds on a first visit. The character then stands at eye level in the middle of the page with its idle animation playing, and its eyes follow the camera as you drag to turn around it or scroll to move closer. The chat launcher sits in the bottom-right corner.

### Talk to the character

Click the launcher. The widget opens in voice mode with the character's name and portrait. To type instead, click **Exit Voice Mode**, write a message in the **Conversation** box, and press Enter. Voice mode asks for microphone access the first time you use it.

{% hint style="success" %}
The reply appears in the widget, the character speaks it, and the character's mouth moves in time with its voice.
{% endhint %}

### Next steps

{% content-ref url="/pages/ICSKo34R2rL5oAYvm7pM" %}
[Add a 3D character to a React app](https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-embody/add-a-3d-character-to-a-react-app.md)
{% endcontent-ref %}

{% content-ref url="/pages/CNRIrVYbzZ53QpYCXQCV" %}
[React API reference](https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-embody/react-api-reference.md)
{% endcontent-ref %}


---

# 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-embody/get-started.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.
