Event system
Reference for core runtime Blueprint delegates on Convai components and the subsystem, organized by category with timing details.
The Convai Unreal Engine plugin communicates core runtime results to Blueprint through UPROPERTY(BlueprintAssignable) delegates on components and the subsystem. Bind these in your character or player Blueprint to drive animations, update UI, dispatch actions, or react to connection changes. This page focuses on the core runtime component and subsystem delegates; async proxy, test, and vision-base delegates are outside this core-concepts reference.
Inherited delegates (both components)
UConvaiChatbotComponent and UConvaiPlayerComponent both inherit from UConvaiConversationComponent, which in turn inherits from UConvaiAudioStreamer. The delegates below are available on every conversation component.
Audio playback
These three delegates are defined on UConvaiAudioStreamer and are available on both the chatbot and player components. None carry parameters. On chatbot components, the talking delegates mark character audio playback boundaries. On player components, the same delegates are broadcast from the player speech callbacks and represent user speech start/stop events.
OnStartedTalkingDelegate
Convai
Chatbot: character audio playback starts. Player: user speech starts.
OnFinishedTalkingDelegate
Convai
Chatbot: character audio playback finishes. Player: user speech stops.
OnFacialDataReadyDelegate
Convai|LipSync
A new batch of pre-computed facial animation data has arrived and is ready for the lip-sync pipeline to consume.
OnStartedTalkingDelegate and OnFinishedTalkingDelegate are the low-level talking boundary events. For chatbot playback awareness, use UConvaiChatbotComponent::GetIsTalking with these delegates. For interruption-specific handling, bind to OnInterruptedEvent.
Transcription
OnTranscriptionReceivedDelegate — category Convai|Transcription
Fires each time a transcription update arrives during or after an utterance. The delegate fires multiple times per turn: once for each intermediate partial result and once more when the final transcription is ready.
Speaker
UConvaiConversationComponent*
The component whose audio produced the transcription.
Listener
UConvaiConversationComponent*
Present in the delegate signature. Current broadcast sites pass nullptr.
Transcription
FString
The transcription text at this point in the utterance.
IsTranscriptionReady
bool
true when the text is ready to display.
IsFinal
bool
true when this is the last update for the utterance.
Attendee connection state
OnAttendeeConnectionStateChangedEvent — category Convai|Connection
Fires whenever an attendee's connection state changes on the chatbot or player component.
ConvaiConversationComponent
UConvaiConversationComponent*
The component that owns this event.
AttendeeID
FString
Identifier for the attendee whose state changed.
ConnectionState
EC_ConnectionState
The new state. The enum defines Disconnected, Connecting, Connected, and Reconnecting; the current runtime path drives Disconnected, Connecting, and Connected.
Chatbot component delegates
These delegates are on UConvaiChatbotComponent and are only relevant when you are working with an AI character.
Actions received
OnActionReceivedEvent_V2 — display name On Actions Received — category Convai (current version)
Fires when Convai sends a sequence of one or more character actions in response to the player's input or a narrative trigger. The actions are available through the SequenceOfActions parameter and the chatbot's ActionsQueue, so you can either iterate the event parameter directly or use FetchFirstAction and HandleActionCompletion to drive a queue-based execution model.
ChatbotComponent
UConvaiChatbotComponent*
The chatbot that received the actions.
InteractingPlayerComponent
UConvaiPlayerComponent*
The player whose input triggered the actions.
SequenceOfActions
TArray<FConvaiResultAction>
The full ordered list of actions to perform.
Emotion state changed
OnEmotionStateChangedEvent — display name On Emotion State Changed — category Convai
Fires when Convai returns an updated emotion state for the character. The EmotionState property on the chatbot component is already updated when this fires. Use GetEmotionScore to read the current value for a specific basic emotion and apply it to your animation system.
ChatbotComponent
UConvaiChatbotComponent*
The chatbot whose emotion changed.
InteractingPlayerComponent
UConvaiPlayerComponent*
The player whose input triggered the emotion update.
Character data loaded
OnCharacterDataLoadEvent_V2 — display name On Character Data Loaded — category Convai (current version)
Fires after the plugin attempts to load character data for the chatbot component. This happens during component startup and after LoadCharacter is called, including when CharacterID is changed through the Blueprint setter. Use the Success parameter to decide whether character-dependent UI or setup logic should continue.
ChatbotComponent
UConvaiChatbotComponent*
The chatbot that loaded data.
Success
bool
true if the fetch succeeded; false if it failed (for example, invalid character ID).
Narrative section received
OnNarrativeSectionReceivedEvent — display name On Narrative Section Received — category Convai
Fires when the AI transitions to a new section of the Narrative Design graph defined in the Convai dashboard. Use this to synchronize in-game state — unlock doors, advance a quest marker, or trigger cutscene logic — in response to the narrative branch the character has entered.
ChatbotComponent
UConvaiChatbotComponent*
The chatbot that moved to the new section.
NarrativeSectionID
FString
The ID of the narrative section as defined in the dashboard.
Interaction ID received
OnInteractionIDReceivedEvent — display name On Interaction ID Received — category Convai
Fires at the start of each distinct interaction (turn) between a player and a character. The interaction ID uniquely identifies this exchange and can be used for logging, analytics, or matching action sequences to the turn that produced them.
ChatbotComponent
UConvaiChatbotComponent*
The chatbot involved in the interaction.
InteractingPlayerComponent
UConvaiPlayerComponent*
The player involved in the interaction.
InteractionID
FString
Unique identifier for this interaction.
Interrupted
OnInterruptedEvent — display name On Interrupted — category Convai
Fires after InterruptSpeech is applied and the audio fade-out begins. Use this to transition the character's animation to a "listening" or "idle" pose, reset subtitle UI, or clear any "talking" state indicators.
ChatbotComponent
UConvaiChatbotComponent*
The chatbot that was interrupted.
InteractingPlayerComponent
UConvaiPlayerComponent*
Present in the delegate signature. The current InterruptSpeech implementation passes nullptr.
Failure
OnFailureEvent — display name On Failure — category Convai
Declared as a BlueprintAssignable chatbot delegate with no parameters. UConvaiChatbotComponent::OnFailure() broadcasts this event when that handler is invoked. Do not use it as the primary signal for character-load failures; use OnCharacterDataLoadEvent_V2 and its Success parameter for character data loading.
Player component delegates
These delegates are on UConvaiPlayerComponent and cover gaze attention transitions. The microphone API on the player component is function-based (GetIsStreaming, GetIsRecording, UnmuteStreamingAudio, etc.) rather than event-based — there are no microphone-specific BlueprintAssignable delegates.
Gaze and attention
All four gaze delegates carry the same signature: the player component and the object component involved in the transition.
OnGazeBegin
—
Convai|Gaze Attention|Events
The player's gaze cursor enters the bounds of a UConvaiObjectComponent for the first time. Fires before any attention threshold.
OnGazeEnd
—
Convai|Gaze Attention|Events
The player's gaze leaves a UConvaiObjectComponent, regardless of whether the object had been promoted to "in attention".
OnAttentionGained
—
Convai|Gaze Attention|Events
A gazed-at object has been held in gaze for longer than GazeAttentionDelay seconds and the attention notification is sent to eligible registered chatbots.
OnAttentionLost
—
Convai|Gaze Attention|Events
The attention release notification is sent — either because the player looked away for longer than GazeAttentionLossDelay seconds, another object took the slot, or the attention target was destroyed.
Gaze delegate signature:
PlayerComponent
UConvaiPlayerComponent*
The player whose gaze changed.
ObjectComponent
UConvaiObjectComponent*
The object involved in the transition.
New gaze begin and attention-gained events require bEnableGazeAttention to be true on the player component. If gaze attention is disabled while an object is already in attention, the current attention can be released and an attention-lost event can still broadcast.
The promotion and release thresholds are configurable on UConvaiPlayerComponent: OnAttentionGained fires after the object has been held in continuous gaze for GazeAttentionDelay seconds (default 1.0 s). OnAttentionLost fires after gaze has been absent for GazeAttentionLossDelay seconds (default 5.0 s). Both values can be tuned in the Details panel to match the intended interaction speed of the experience.
Object component events
UConvaiObjectComponent exposes four gaze events that mirror the player component's gaze delegates from the object's perspective. Use these to react to player focus directly on the object's Blueprint without polling the player component.
OnGazedIn
Convai|Object|Gaze
The player's gaze cursor enters this object. Fires before any attention threshold.
OnGazedOut
Convai|Object|Gaze
The player's gaze leaves this object, regardless of attention state.
OnAttentionGained
Convai|Object|Gaze
This object sends an attention-gained notification to eligible registered chatbots after the sustained-gaze threshold.
OnAttentionLost
Convai|Object|Gaze
This object sends an attention-lost notification when the loss timer elapses or gaze swaps to another object. Destroyed-target paths are handled by the player-level attention-lost delegate with a nullable object parameter.
Object gaze event signature:
ObjectComponent
UConvaiObjectComponent*
The object whose gaze state changed.
PlayerComponent
UConvaiPlayerComponent*
The player whose gaze triggered the transition. May be null in destroyed-target paths — always null-check before use.
These events only fire when bGazeable is true on the object component (the default). Set bGazeable to false on objects that should exist in the chatbot's environment for action or context purposes but should not be reachable via player gaze.
Subsystem events
UConvaiSubsystem exposes two BlueprintAssignable delegates that monitor the global connection state across all sessions in the game instance. Access the subsystem from any Blueprint via Get Game Instance → Get Subsystem (Convai Subsystem).
OnServerConnectionStateChangedEvent
Convai|Connection
EC_ConnectionState ConnectionState
The global WebRTC connection state changes. Use the ConnectionState parameter to react to driven states such as Connecting or Connected.
OnUserIdleWarning
Convai|Event
int32 RemainingSeconds
Convai detects that the user has been idle. RemainingSeconds is the time remaining before the connection closes automatically. Call ResetIdleTimer on the subsystem to prevent the disconnection.
Bind to OnServerConnectionStateChangedEvent for UI overlays or logging that should react to any session state change. Bind to OnUserIdleWarning to prompt the user or reset the timer programmatically — for example, in a training simulation, reset the timer whenever the learner completes a task step, regardless of whether they spoke.
Event binding patterns
Blueprint
Use the Assign node on the component reference to bind any BlueprintAssignable delegate. For chatbot events, bind inside the owning character Blueprint's BeginPlay. If your handler depends on character data being loaded first (for example, displaying the character name), bind from inside the OnCharacterDataLoadEvent_V2 handler instead. For subsystem events, bind after retrieving the subsystem from the game instance.
Bind each delegate exactly once — typically in BeginPlay. Avoid binding inside a delegate callback or inside any function that may be called more than once per actor lifetime. Each call to Assign adds a new binding; duplicate bindings cause the same handler to fire multiple times per event.
C++
In C++, use AddDynamic in BeginPlay and RemoveDynamic in EndPlay to match the Blueprint binding pattern.
Remove dynamic delegates in EndPlay when binding actor-owned handlers, especially for subsystem events whose owner outlives individual actors.
Usage examples
Emotion-driven animation
A character that updates its facial expression each time Convai returns a new emotion state.
In Blueprint, Assign to On Emotion State Changed in the character's BeginPlay event. The handler node receives the chatbot component reference — call Get Emotion Score on it to read current emotion values and forward them to your animation system or Anim Blueprint.
In C++, bind with AddDynamic in BeginPlay:
Expected result: The character's facial expression updates within the same audio response that carries the emotion data.
Connection state UI overlay
A HUD that shows a "Connecting…" overlay while the Convai session is not yet ready.
In Blueprint, get the Convai Subsystem from the game instance in the HUD's BeginPlay, then Assign to On Server Connection State Changed. In the handler, show or hide the overlay widget based on whether the incoming state is Connected.
Expected result: The overlay is visible during Connecting and hides automatically when the session reaches Connected — without polling on Tick.
Action dispatch system
A character that executes a sequence of physical actions — move, interact, speak — in order.
In Blueprint, Assign to On Actions Received in BeginPlay. In the handler, call Fetch First Action to read the first action from the queue, execute the corresponding game logic (move the character, trigger an animation, open a prop), then call Handle Action Completion with true. A successful completion dequeues the current action and makes the next action ready to fetch.
Expected result: Actions execute in order as each prior action reports completion, and the character's speech plays in parallel.
Troubleshooting
Delegate never fires
Binding was never established, or was created after the event already fired
Bind in the character Blueprint's BeginPlay using the Assign node, or use AddDynamic in C++. For events that depend on character data, bind from inside an OnCharacterDataLoadEvent_V2 handler instead of in BeginPlay.
Add a Print String to the handler; it should output when the expected condition occurs.
Handler fires multiple times per event
The delegate was bound more than once — for example, Assign is inside a function called on every StartSession
Ensure each Assign call is reached exactly once per actor lifetime. If re-binding is intentional, call Remove (Blueprint) or RemoveDynamic (C++) before re-assigning.
Log a counter inside the handler; it should increment by exactly 1 per event.
Character data setup fails at session start
Invalid CharacterID or API key configuration issue
Verify that CharacterID in the chatbot component matches a character in your Convai dashboard. Confirm and save the API key in the Convai Editor window.
OnCharacterDataLoadEvent_V2 fires with Success = true after a valid session start.
Gaze events never fire
bEnableGazeAttention is false on the player component, or the target actor has no UConvaiObjectComponent
Set Enable Gaze Attention to true on the player component. Confirm the target actor has a UConvaiObjectComponent with bGazeable enabled.
OnGazeBegin fires on both the player component and the object component when the player looks at the target.
Related concepts
Use these pages to connect delegate timing with turn behavior, component ownership, and session lifecycle decisions.
Last updated
Was this helpful?