Add your first Convai character

Build a talking Convai character in Unreal Engine by adding Chatbot and Player components, setting a Character ID, and testing in Play mode.

We will add a Convai character to an existing Unreal Engine project and have a live voice conversation with it. By the end, you will have a character that listens, generates a response, and speaks back using your microphone.

Add your first Convai character walkthrough

Before you start

• The Convai plugin is installed and enabled (see Install the Convai plugin).
• Your API key is configured (see Configure your API key).
• You have an existing character in your Convai dashboard, or you will create one during this tutorial.
• Your project already has an NPC Actor Blueprint and a player pawn Blueprint.

Get a character ID from the Convai dashboard

1

Open the Convai dashboard

In a browser, go to convai.com and sign in.

2

Choose or create a character

Select an existing character from your character list, or create a new one. Manage the character's profile and behavior in the dashboard. You can update dashboard configuration without changing anything in Unreal Engine.

3

Copy the character ID

On the character's detail page, copy the Character ID string. You will paste this into the editor in the next section.

Add the Convai Chatbot component to your NPC

1

Open the character Blueprint

In the Outliner, click on your NPC Actor. In the Details panel, click Edit Blueprint to open the Blueprint editor. You can also open the Blueprint asset directly from the Content Browser.

2

Add the Convai Chatbot component

In the Components panel inside the Blueprint editor, click Add. Search for BP Convai ChatBot Component and select it. This adds the Blueprint-wrapped chatbot component, which comes pre-wired with push-to-talk input and the chat UI widget.

3

Set the character ID

Select the Convai Chatbot component in the Components panel. In the Details panel, find the Character ID field under the Convai category and paste your character ID into it.

4

Add the Convai Face Sync component (optional)

If your character has a facial rig and you want lip sync, click Add again, search for Convai Face Sync, and add it. Select the component and set Lip Sync Mode to match your rig:

• MetaHuman Blendshapes — for MetaHuman and Reallusion CC5 characters.
• CC4 Extended Blendshapes — for Reallusion CC4 characters.
• Viseme Based — for custom rigs using OVR visemes.

Skip this step if your character has no facial rig.

5

Compile and save the Blueprint

Click Compile and then Save in the Blueprint editor toolbar.

6

Set a starting expression (optional)

To start the character with a specific expression, open the Event Graph, add an Event BeginPlay node, get a reference to the Convai Chatbot component, and call Force Set Emotion. Set Basic Emotion to Happy, Intensity to Basic, and Reset Other Emotions to true. Emotions update dynamically as the conversation evolves. See Emotion examples.

Add the Convai Player component to the player pawn

1

Find the player pawn Blueprint

The fastest way to find it is through Window > World Settings. Expand Game Mode > Selected Game Mode and note the Default Pawn Class. Click the Browse icon next to it to locate the Blueprint in the Content Browser, then open it.

Alternatively, from Play mode: press Shift+F1 to release the mouse, click Detach in the toolbar, click the player character in the viewport, then click Edit Blueprint.

2

Add the Convai Player component

In the Blueprint editor for the player pawn, click Add in the Components panel. Search for BP Convai Player Component and select it. This adds the Blueprint-wrapped player component, which includes push-to-talk input and the chat UI widget pre-configured.

3

Compile and save

Click Compile and then Save.

If you do not have an existing player pawn, the plugin ships a ready-made one: BP_ConvaiSamplePlayer at ConvAI > ConvaiConveniencePack > Sample. Drop it into the level and set BP_SampleGameMode (same folder) as the GameMode Override in World Settings. It already has BP_ConvaiPlayerComponent and a chat widget pre-configured. This setup is suitable for prototyping — for production, add BP Convai Player Component directly to your own player pawn Blueprint as described above.

Test the conversation

1

Enter Play mode

Press Play in the Unreal Editor toolbar. A chat widget appears in the viewport.

2

Talk to the character

Hold the push-to-talk key (default: T), speak into your microphone, then release the key. The character processes your speech, generates a response, and speaks back.

To use hands-free (VAD) mode instead, open the player pawn Blueprint, select the Convai Player component (BP_ConvaiPlayerComponent), expand the Convai category in the Details panel, and disable Enable Push to Talk (EnablePushToTalk — a variable on the Blueprint wrapper, not the bare C++ component). Alternatively, call UpdateVadBP(true) from Blueprint. See Configure conversation input for full VAD tuning options.

When the setup is working, the character speaks an audible response and the chat widget shows a transcript of the exchange. If the character does not respond, see Validate your setup for a checklist of common failure points.

Next steps

Validate your setupSet up a MetaHuman characterSet up a Reallusion (CC) characterConfigure conversation inputScene components reference