> 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/convai-unreal-engine-plugin/getting-started/set-up-a-metahuman-character.md).

# Set up a MetaHuman character

This guide walks through connecting a MetaHuman to the Convai Unreal Engine plugin so it speaks with real-time lip sync and facial animation.

{% embed url="<https://youtu.be/4fMCKkrfyaA>" %}
MetaHuman character setup walkthrough
{% endembed %}

### Prerequisites

* The Convai plugin is installed and your API key is configured — see [Install the Convai plugin](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md) and [Configure your API key](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md).
* Unreal Engine and the **MetaHuman** plugin are available in your project.
* You have a Convai character ID from the dashboard.

### Import a MetaHuman

{% hint style="info" %}
In **Unreal Engine 5.4 and later**, MetaHumans are managed through the **Fab** plugin rather than Quixel Bridge. The import experience is similar — use **Window > Fab** or the **Fab** button in the toolbar to open the panel and navigate to the MetaHuman section. Refer to the [Unreal Engine MetaHuman documentation](https://dev.epicgames.com/documentation/en-us/metahuman/importing-metahumans-to-unreal-engine-projects) for the current import path for your engine version. The Convai setup steps after import are the same regardless of how the MetaHuman is imported.
{% endhint %}

{% stepper %}
{% step %}

#### Open Quixel Bridge or Fab

In the Unreal Editor menu bar, select **Window > Quixel Bridge** (UE 5.3 and earlier) or **Window > Fab** (UE 5.4 and later). Navigate to the **MetaHuman** section.
{% endstep %}

{% step %}

#### Add a MetaHuman to your project

Select the MetaHuman you want to use and click to add it to your project. The first download may take a few minutes while textures and assets download. When the download completes, a `MetaHumans` folder appears in the **Content Browser**.
{% endstep %}

{% step %}

#### Open the MetaHuman Blueprint

In the **Content Browser**, open the `MetaHumans` folder, find your MetaHuman, and double-click the Blueprint (`.uasset`) file. If Unreal Engine prompts you to enable missing plugins required by the MetaHuman, click **Yes** and restart the editor. After restart, reopen the MetaHuman Blueprint.
{% endstep %}
{% endstepper %}

### Add the Convai components

{% stepper %}
{% step %}

#### Add the Convai Chatbot component

In the Blueprint editor for your MetaHuman, click **Add** in the **Components** panel. Search for `BP Convai ChatBot Component` and select it.

In the **Details** panel for the component, paste your **Character ID** from the Convai dashboard into the **Character ID** field under the **Convai** category.
{% endstep %}

{% step %}

#### Add the Convai Face Sync component

Click **Add** again in the **Components** panel. Search for `Convai Face Sync` and add `UConvaiFaceSyncComponent`.

In the **Details** panel, confirm that **Lip Sync Mode** is set to **MetaHuman Blendshapes**. This is the default value and the correct setting for MetaHuman characters.
{% endstep %}
{% endstepper %}

### Assign the Convai animation blueprints

MetaHuman characters use separate animation blueprints for body and face. The Convai plugin ships two assets at `MetaHumans/Animations/` (`ConvAI > MetaHumans > Animations` in the Content Browser) that wire lip sync data into the MetaHuman skeleton.

{% stepper %}
{% step %}

#### Set the body animation class

In the Blueprint editor, select the **Body** skeletal mesh component. In the **Details** panel, find the **Anim Class** field under **Animation**. Set it to `Convai_MetaHuman_BodyAnim`.
{% endstep %}

{% step %}

#### Set the face animation class

Select the **Face** skeletal mesh component. In the **Details** panel, find the **Anim Class** field. Set it to `Convai_MetaHuman_FaceAnim`.
{% endstep %}

{% step %}

#### Compile and save

Click **Compile** and then **Save** in the Blueprint editor toolbar.
{% endstep %}
{% endstepper %}

### Add the MetaHuman to the level

Drag the MetaHuman Blueprint from the **Content Browser** into the level viewport and position it where you want.

### Add the Convai Player component to the player pawn

If you have not already done this, open your player pawn Blueprint and add `UConvaiPlayerComponent`. See [Add your first Convai character](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/add-your-first-convai-character.md) for the steps.

### Test the setup

Enter Play mode. Use push-to-talk (default: **T**) or the chat widget to start a conversation.

{% hint style="success" %}
When the setup is working, the MetaHuman's mouth moves in sync with the character's spoken response and facial expressions change dynamically during the conversation. If the character does not respond, see [Validate your setup](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/validate-your-setup.md).
{% endhint %}

### Gesture and gaze animations

Starting in plugin version 4.0.0-beta.20, the plugin ships gaze and pointing Animation Blueprints plus a gesture motion library under `MetaHumans/Animations/`. When the Actions system issues an LLM gesture command, these assets activate through `BPI_Convai_Animation` without extra Blueprint wiring beyond the lip sync animation Blueprint setup above.

#### Lip sync animation blueprints

| Asset                       | Content path             | Purpose                                                                            |
| --------------------------- | ------------------------ | ---------------------------------------------------------------------------------- |
| `Convai_MetaHuman_BodyAnim` | `MetaHumans/Animations/` | Body animation — assign to the **Body** skeletal mesh **Anim Class**.              |
| `Convai_MetaHuman_FaceAnim` | `MetaHumans/Animations/` | Face animation and lip sync — assign to the **Face** skeletal mesh **Anim Class**. |

#### Gaze and pointing Animation Blueprints

| Asset            | Content path                    | Purpose            |
| ---------------- | ------------------------------- | ------------------ |
| `A1D_MH_BEye`    | `MetaHumans/Animations/AnimBP/` | Eye blink and gaze |
| `A2D_MH_EyeLook` | `MetaHumans/Animations/AnimBP/` | Eye look direction |
| `B2D_F_HeadLook` | `MetaHumans/Animations/AnimBP/` | Female head look   |
| `B2D_M_HeadLook` | `MetaHumans/Animations/AnimBP/` | Male head look     |
| `B2D_F_Pointing` | `MetaHumans/Animations/AnimBP/` | Female pointing    |
| `B2D_M_Pointing` | `MetaHumans/Animations/AnimBP/` | Male pointing      |

#### LLM gesture library

Each gesture ships female (`Anim_F_*`) and male (`Anim_M_*`) animation sequences plus Animation Montage counterparts (`*_Montage`). All paths are under `MetaHumans/Animations/Motion/Gestures/`.

| Gesture | Folder            | Key assets (per gender)                                                                                                                                                                                  |
| ------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bye     | `Gestures/Bye/`   | `Anim_F_Bye`, `Anim_F_Bye_Montage` / `Anim_M_Bye`, `Anim_M_Bye_Montage`                                                                                                                                  |
| Hi      | `Gestures/Hi/`    | `Anim_F_Hi`, `Anim_F_Hi_Montage` / `Anim_M_Hi`, `Anim_M_Hi_Montage`                                                                                                                                      |
| Like    | `Gestures/Like/`  | `Anim_F_Like`, `Anim_F_Like_Montage` / `Anim_M_Like`, `Anim_M_Like_Montage`                                                                                                                              |
| No      | `Gestures/No/`    | `Anim_F_No`, `Anim_F_No_Montage` / `Anim_M_No`, `Anim_M_No_Montage`                                                                                                                                      |
| Think   | `Gestures/Think/` | `Anim_F_Think`, `Anim_F_Think_In`, `Anim_F_Think_Loop`, `Anim_F_Think_Out`, `Anim_F_Think_Montage` / male equivalents (`Anim_M_Think_*`)                                                                 |
| Wink    | `Gestures/Wink/`  | Body: `Anim_F_Wink_Body`, `Anim_F_Wink_Body_Montage` / `Anim_M_Wink_Body`, `Anim_M_Wink_Body_Montage`. Face: `AnimFace_F_Wink`, `AnimFace_F_Wink_Montage` / `AnimFace_M_Wink`, `AnimFace_M_Wink_Montage` |
| Yes     | `Gestures/Yes/`   | `Anim_F_Yes`, `Anim_F_Yes_Montage` / `Anim_M_Yes`, `Anim_M_Yes_Montage`                                                                                                                                  |

The plugin also ships additional body-action animations under `MetaHumans/Animations/Motion/Actions/` (Clap, Dance\_Disco, Dance\_Groove, Dance\_GStyle, Jump360) and locomotion assets under `Motion/Idle/`, `Motion/Walk/`, `Motion/Jog/`, and `Motion/Talk/`.

The animation interface `BPI_Convai_Animation` at `Interfaces/BPI_Convai_Animation` connects the Actions system to these assets.

### Troubleshooting

#### MetaHuman mouth does not move during speech

**Symptom:** Audio plays but the mouth does not animate.

**Cause:** **Lip Sync Mode** is set to the wrong target, or the face and body animation classes are not the Convai MetaHuman variants.

**Fix:** Confirm **Lip Sync Mode** on `UConvaiFaceSyncComponent` is **MetaHuman Blendshapes**. Confirm **Anim Class** on the **Face** mesh is `Convai_MetaHuman_FaceAnim` and on the **Body** mesh is `Convai_MetaHuman_BodyAnim`.

**Verify:** Enter Play mode and speak to the character. Open **Window > Output Log**, filter on `ConvaiFaceSync` or `ConvaiChatbotComponentLog`, and confirm no errors appear while the character speaks.

#### Character does not respond to voice or text

**Symptom:** The MetaHuman is in the level but does not react to input.

**Cause:** The **Character ID** is missing or incorrect, the API key is not configured, or `UConvaiPlayerComponent` is absent from the player pawn.

**Fix:** Verify the **Character ID** on the **Convai Chatbot** component matches a character in your Convai dashboard. Confirm your API key is set (see [Configure your API key](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md)). Confirm the player pawn has `UConvaiPlayerComponent` added.

**Verify:** Open **Window > Output Log** and filter on `ConvaiChatbotComponentLog` or `ConvaiConnectionManagerLog`. Look for connection or authentication errors when you enter Play mode and attempt a conversation.

### Next steps

{% content-ref url="/pages/GjMgGIpOc6IFNfXiyJTr" %}
[Set up a Reallusion (CC) character](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/set-up-a-reallusion-cc-character.md)
{% endcontent-ref %}

{% content-ref url="/pages/wO1MGAXD0InYM2apk7cV" %}
[Configure conversation input](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/configure-conversation-input.md)
{% endcontent-ref %}

{% content-ref url="/pages/g8UGNK2Dicyeh9I9zZ6x" %}
[Validate your setup](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/validate-your-setup.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/set-up-a-metahuman-character.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.