Validate your setup

Run through a checklist of plugin, component, audio, and API key checks to confirm your Convai Unreal Engine setup is working before adding features.

Use this page to confirm that every part of your Convai setup is working before you proceed to add features. Work through each section in order. A failure at any step usually points to a specific problem with a clear fix.

Plugin check

Check	How to verify
Plugin is enabled	Go to Edit > Plugins, search for Convai, and confirm the Enabled checkbox is checked.
Toolbar icon is visible	The Convai icon appears in the Unreal Editor toolbar after the plugin loads.
No load errors	The Output Log does not show errors mentioning Convai or AudioCapture on editor startup.

API key check

Check	How to verify
Signed in	Open the Convai editor window (click the Convai toolbar icon) and confirm your account details are shown.
Key is stored	UConvaiSettings.API_Key is populated — readable under Edit > Project Settings > Plugins > Convai.

If you are not signed in, see Configure your API key.

Component check

Check	How to verify
Character has Convai Chatbot	Open the character Blueprint and confirm UConvaiChatbotComponent appears in the Components panel.
Character ID is set	Select the Convai Chatbot component and confirm the Character ID field is non-empty and matches a character in your dashboard.
Player pawn has Convai Player	Open the player pawn Blueprint and confirm UConvaiPlayerComponent appears in the Components panel.
Face Sync is present (if using lip sync)	Confirm UConvaiFaceSyncComponent is in the character Blueprint and Lip Sync Mode is correct for your rig.

Audio check

Check	How to verify
Microphone is available	Press F10 in Play mode to open the settings panel, then view and test available microphone devices. Alternatively, call GetAvailableCaptureDeviceNames() on UConvaiPlayerComponent at runtime and confirm the list is non-empty.
Default device opens	Enter Play mode and confirm that GetIsStreaming() returns true after triggering push-to-talk or enabling hands-free mode.
Android permission granted	On Android, confirm the android.permission.RECORD_AUDIO permission was requested and granted before starting a conversation.

Conversation check

Run this check after all others pass.

1

Enter Play mode

Press Play in the Unreal Editor toolbar.

2

Start a conversation

Hold push-to-talk (default: T) and speak a short phrase, then release. Alternatively, type a message in the chat widget and press Enter.

3

Observe the character state

While the character is speaking, GetIsTalking() ("Is Talking") on UConvaiChatbotComponent returns true. While a session is active, IsInConversation() returns true.

Add Print String nodes in Blueprint connected to these functions to observe state transitions in the viewport. IsListening() and IsProcessing() are exposed in Blueprint but currently return false in the plugin source.

4

Confirm audio output

The character speaks an audible response. If lip sync is configured, the character's mouth moves in sync with the speech.

When validation passes, the character responds with audio and — if configured — lip sync. Proceed to the feature pages to add actions, emotions, dynamic context, and other capabilities.

Common failure points

Character does not respond at all

Symptom: The character never generates a response to voice or text input.

Cause: API key not set, or Character ID missing.

Fix: See Configure your API key; confirm the Character ID field on the Chatbot component.

Verify: Enter Play mode and send a short phrase. The character speaks an audible response.

No audio from character

Symptom: The character appears to process input but produces no speech audio.

Cause: Audio output device issue or session not started.

Fix: Confirm bAutoInitializeSession is true on the Chatbot component, or call StartSession() manually.

Verify: GetIsTalking() returns true while the character responds.

Character does not hear the player

Symptom: The character never reacts to microphone input.

Cause: Microphone not captured, or Player component missing.

Fix: Confirm UConvaiPlayerComponent is on the pawn; see Configure the microphone.

Verify: GetIsStreaming() returns true after push-to-talk or VAD activation.

Lip sync does not play

Symptom: Audio plays but the character's mouth does not move.

Cause: Face Sync component missing or wrong lip sync mode.

Fix: Add UConvaiFaceSyncComponent and set the correct LipSyncMode for your rig.

Verify: Enter Play mode and confirm mouth movement during speech.

OnFailureEvent fires

Symptom: The OnFailureEvent delegate fires during conversation.

Cause: Network error or invalid Character ID.

Fix: Check the Output Log for details; verify network access and Character ID.

Verify: Retry after fixing the reported error.

Next steps

Configure the microphoneConfigure character audioConfigure conversation inputAdd the chat UI