For the complete documentation index, see llms.txt. This page is also available as Markdown.

Add a 3D character to a React app

Install Convai Embody in a React app and render a Convai character that speaks with lip sync, gaze, and blinking from its character ID.

Render a Convai character as a 3D body in a React app with one component. Use this page when adding Convai Embody to a project for the first time. At the end, the character stands on the page, follows the camera with its eyes, and moves its mouth in sync with its voice.

Prerequisites

  • A React 18 or later app with a bundler, and Node.js 18 or later.

  • A Convai account, an API key from https://convai.com, 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.

Install the packages

@convai/web-sdk and three are peer dependencies, so install them alongside @convai/embody. The React path also needs react and @react-three/fiber.

npm install @convai/embody @convai/web-sdk three @react-three/fiber
pnpm add @convai/embody @convai/web-sdk three @react-three/fiber
yarn add @convai/embody @convai/web-sdk three @react-three/fiber

Render the character

ConvaiCharacter brings its own canvas, camera, lights, and orbit controls. It resolves the character's body, opens the Convai Web SDK connection, plays the character's audio, and drives its face.

src/App.tsx
import ConvaiCharacter from '@convai/embody/react'

export default function App() {
  return (
    <ConvaiCharacter
      apiKey={import.meta.env.VITE_CONVAI_API_KEY}
      characterId="YOUR_CHARACTER_ID"
    />
  )
}

The component fills its parent and is at least as tall as the viewport. Drag to turn around the character and scroll to move closer. Pass orbit={false} for a fixed camera.

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".

Place the character in your own scene

When the character joins a scene you already compose with @react-three/fiber, use CharacterModel inside your <Canvas> instead. It takes the same credential and character props, and adds no canvas, camera, or lights of its own.

Verify the character

Load the page and wait for the model to download. Then talk to the character, for example through the chat widget described in Add a chat widget to a character.

To observe loading in code, pass onReady, which receives the character handle once the body is loaded and the connection is live, and onError, which receives the error that stopped it.

Troubleshooting

The character never appears

Symptom: onError receives an error whose message ends with the reason Convai gave:

Cause: The character's avatar has no published web body, and no default body applies to it.

Fix: Choose a character whose avatar has a published web body. If none of your characters has one, contact Convai support.

Verify: Reload the page. The character renders.

A credential error is thrown before anything loads

Symptom: Creating the character throws:

Cause: Neither token, authToken, nor apiKey was set, or the variable that should hold it is empty at build time.

Fix: Pass a credential. Check that the environment variable is defined for the build you are running.

Verify: The error no longer appears and the character loads.

The model fails to load on a page with a strict Content Security Policy

Symptom: The body never renders, and the browser console reports a blocked request to https://www.gstatic.com/draco/.

Cause: Character models are Draco-compressed, and Convai Embody loads the Draco decoder from https://www.gstatic.com/draco/versioned/decoders/1.5.7/ by default.

Fix: Allow that origin in your policy, or host the decoder files yourself and pass their URL as dracoDecoderPath.

Verify: The character renders and the console shows no blocked decoder request.

Next steps

Add a chat widget to a characterReact API reference

Last updated

Was this helpful?