Dynamic context Blueprint reference
Reference the Blueprint controls that send runtime state, event, reset, and timing updates from an Unreal character to Convai during a live session.
Most dynamic context functions are exposed on UConvaiChatbotComponent (Blueprint display name Convai Chatbot) under the Convai|DynamicContext category. Update Context is an advanced direct context-update node in the Convai category; it bypasses the tracked state/event helper API. Properties appear under Convai > DynamicContext (debounce settings) and Convai (DynamicEnvironmentInfo) in the Details panel.
Source of truth: Source/Convai/Public/ConvaiChatbotComponent.h, Source/Convai/Private/ConvaiChatbotComponent.cpp, Source/Convai/Public/DynamicContext/, and Source/Convai/Private/ConvaiSubsystem.cpp.
Functions
Set Context State
Set Context StateSets a single state property in the dynamic context. If a property with the same Name already exists, its value is replaced.
Use when: One current fact changes during gameplay — health, zone, equipment status.
Blueprint category: Convai|DynamicContext
Name
FString
—
Key identifying this state property. Case-sensitive.
Value
FString
—
Current value of the state property.
ShouldRespond
EC_RunLLMOption
Never
Contributes to batch aggregate run_llm.
bFlushImmediately
bool
false
Advanced. Bypass debounce and run the flush path in the current frame. Use after connection for data that must be delivered.
Flush behavior: One Replace context-update. New keys enter canonical when aggregate is Never; otherwise new keys are deferred to delta lines on first flush. Updated keys always appear in canonical; delta lines describe the transition when aggregate is not Never.
Pre-session: With default debounce, stages safely and flushes after the session connects and the debounce deadline elapses. Do not use bFlushImmediately = true before connection for data that must be delivered.
Set Context States
Set Context StatesSets multiple state properties at once. All keys share one canonical rebuild and one flush.
Use when: Several related facts change together — zone, equipment, and time of day after a scene transition.
Blueprint category: Convai|DynamicContext
States
TMap<FString, FString>
—
Map of key-value state properties to set or update.
ShouldRespond
EC_RunLLMOption
Never
Contributes to batch aggregate run_llm for all supplied keys.
bFlushImmediately
bool
false
Advanced. Bypass debounce and run the flush path in the current frame. Use after connection for data that must be delivered.
Behavior: Empty maps are ignored. Aggregate ShouldRespond merges with any other staged items in the same debounce window (Always > Auto > Never).
Pre-session: With default debounce, stages safely and flushes after the session connects and the debounce deadline elapses. Do not use bFlushImmediately = true before connection for data that must be delivered.
Add Context Event
Add Context EventAppends a chronological event string to the dynamic context.
Use when: Something happened once — an alarm, a milestone, a narrative beat.
Blueprint category: Convai|DynamicContext
Text
FString
—
Event description to append.
ShouldRespond
EC_RunLLMOption
Auto
Contributes to batch aggregate run_llm.
bFlushImmediately
bool
false
Advanced. Bypass debounce and run the flush path in the current frame. Use after connection for data that must be delivered.
Behavior: Identical Text values staged multiple times in the same debounce window are deduplicated. At flush, the event is committed to the tracker and included in canonical. Regular context events are not duplicated into a separate delta line.
Pre-session: With default debounce, stages safely and flushes after the session connects and the debounce deadline elapses. Do not use bFlushImmediately = true before connection for data that must be delivered.
Remove Context State
Remove Context StateRemoves a state property from the dynamic context and rebuilds canonical context without it.
Use when: A condition no longer applies — an item was used, an alert was cleared.
Blueprint category: Convai|DynamicContext
Name
FString
—
Key to remove. Case-sensitive.
bFlushImmediately
bool
false
Advanced. Bypass debounce and run the flush path in the current frame. Use after connection for data that must be delivered.
Returns: Nothing. If Name does not exist, the call is a no-op.
Behavior: Sets bForceReplace on the pending batch so the flush sends updated canonical context without the removed key. No delta lines are added.
Pre-session: With default debounce, stages safely and flushes after the session connects and the debounce deadline elapses. Do not use bFlushImmediately = true before connection for data that must be delivered.
Reset Dynamic Context
Reset Dynamic ContextClears all tracked state properties and events and resets remote context.
Use when: A simulation restarts or you need to discard all prior runtime context.
Blueprint category: Convai|DynamicContext
—
—
—
No parameters.
Behavior: Marks bPendingReset. Does not clear the tracker or discard staged updates up front. On flush: staged batch drains first, then a Reset context-update fires (mode: reset, run_llm: "false", with text omitted for the empty Reset payload), then the local tracker is cleared. Clears PendingTriggers when the reset is requested. When connected, calls the flush path immediately; when offline, queues until the first post-connect flush.
Get Context State Value
Get Context State ValueReturns the current client-side value of a tracked state property. Reads from the local tracker — does not query Convai.
Use when: A Blueprint condition needs the current local value before sending a redundant update.
Blueprint category: Convai|DynamicContext
Name
In
FString
—
Key to look up. Case-sensitive.
OutValue
Out
FString
—
Current value if the key exists.
Return value
Return
bool
—
true if the key was found.
Update Context
Update ContextAdvanced direct node. Sends a raw context-update with explicit Text, Mode, and ShouldRespond. Staged state/event flushes use the same transport message type during FlushDynamicContext() without updating the tracker through this node. Reset Dynamic Context uses the same C++ UpdateContext send path for the reset message.
Use when: The tracked node family does not cover your format requirements.
Blueprint category: Convai
Text
FString
—
Context text to apply. Optional when Mode is Reset.
Mode
EC_ContextUpdateMode
Append
How the context is applied: Append, Replace, or Reset.
ShouldRespond
EC_RunLLMOption
Auto
Maps to run_llm on the wire.
Use Update Context only when the tracked node family does not cover your format requirements. It does not update FConvaiDynamicContextTracker, so Get Context State Value cannot read values sent only through this node. Pass an empty string when Mode is Reset; the SDK omits text only for an empty Reset payload.
Default ShouldRespond reference
Function
Default ShouldRespond
Set Context State
Never
Set Context States
Never
Add Context Event
Auto
Remove Context State
(no ShouldRespond parameter)
Reset Dynamic Context
(Reset always uses Never on the wire)
Update Context
Auto
Properties
ContextDebounceWindow
ContextDebounceWindowType
float
Default
0.5
Clamp
≥ 0.1
Category
`Convai
Seconds to wait after the most recent staged context update before flushing. Each new update within the window resets this timer.
ContextMaxDebounceWindow
ContextMaxDebounceWindowType
float
Default
3.0
Clamp
≥ 0.1
Category
`Convai
Upper bound on how long the first update in a debounce burst can be delayed. Must be ≥ ContextDebounceWindow; smaller values are clamped at flush time.
DynamicEnvironmentInfo
DynamicEnvironmentInfoType
FString
Default
""
Category
Convai
Free-form text sent through update-dynamic-info on attendee connect and when the property changes on a connected session. Not tracked by FConvaiDynamicContextTracker. For runtime-changing facts, use Set Context State.
Enums
EC_RunLLMOption
EC_RunLLMOptionControls whether Convai generates a spoken response after receiving a context update.
Enumerator
Blueprint display name
Wire string (run_llm)
Behavior
EC_RunLLMOption::Auto
Auto
"auto"
Sends the update with automatic response handling requested.
EC_RunLLMOption::Always
Always
"true"
Sends the update with response handling requested.
EC_RunLLMOption::Never
Never
"false"
Sends the update without response handling requested.
EC_ContextUpdateMode
EC_ContextUpdateModeControls how a context string is applied when calling Update Context directly.
Enumerator
Blueprint display name
Wire value (mode)
Behavior
EC_ContextUpdateMode::Append
Append
append
Text is appended to existing context.
EC_ContextUpdateMode::Replace
Replace
replace
Full context is replaced with the supplied text.
EC_ContextUpdateMode::Reset
Reset
reset
Context is cleared. Pass empty Text for the standard Reset payload.
Transport messages
context-update
context-updateSent by UConvaiSubsystem::UpdateContext for tracked dynamic context flushes and direct Update Context calls.
mode
append, replace, or reset
run_llm
String value "auto", "true", or "false"
text
Assembled context string; omitted on empty Reset
current_attention_object
Optional attention object name when attention is folded into the flush
Tracked flushes from FlushDynamicContext always use mode: replace for staged batch content.
update-dynamic-info
update-dynamic-infoSent by UpdateDynamicInfo for DynamicEnvironmentInfo changes and on attendee connect.
dynamic_info.text
Free-form environment text
Connection helper
Get Chatbot Connection State
`Convai
Connection`
Next steps
Sync behavior and timingTroubleshoot dynamic contextLast updated
Was this helpful?