For the complete documentation index, see llms.txt. This page is also available as Markdown.

Static context at connection time

Understand which verified connection data is fixed at session start and how live context updates use separate runtime messages.

Some context is sent once when the session starts. Other context can change during gameplay through separate update paths. This page explains what is fixed at connect time and what you can update live.

What is sent at connection time

When Start Session runs, UConvaiChatbotComponent opens a realtime session using connection parameters from the component and the active environment data. The source-verified realtime connection path includes the following data:

Data

Source on UConvaiChatbotComponent

Notes

Character ID

CharacterID

Determines which character configuration Convai loads.

Action config

EnvironmentData when bEnableActions is true and at least one action is configured

Serialized as a JSON action_config block. Action set, object list, and character list are fixed until reconnect.

End user identity

EndUserID and EndUserMetadata

Used by long-term memory. Changing them mid-session has no effect on the current session.

These values establish the session. They do not change when you push dynamic context during gameplay.

What updates live

After the session is connected, six mechanisms can deliver updated context to Convai:

Mechanism
RTVI message
What it carries

Dynamic context pipeline

context-update

Tracked states and events from Set Context State, Set Context States, Add Context Event, Remove Context State, and Reset Dynamic Context

Direct context update

context-update

Explicit text sent through Update Context, bypassing the tracked state/event helper API

Scene metadata pipeline

update-scene-metadata

New or removed environment entries from AddObject, RemoveObject, AddCharacter, RemoveCharacter, and related environment mutations

Dynamic environment info

update-dynamic-info

Free-form text from DynamicEnvironmentInfo

Narrative template keys

update-template-keys

Current NarrativeTemplateKeys values after connect and when updated through UpdateNarrativeTemplateKeys

Attention folding

context-update (same message)

Optional current_attention_object when attention is staged with a context flush

See How dynamic context works for the tracked pipeline and How scene metadata works for environment updates.

DynamicEnvironmentInfo

DynamicEnvironmentInfo is a FString property in the Convai category of the Details panel. It carries free-form text that is not tracked by FConvaiDynamicContextTracker.

The plugin sends it through update-dynamic-info in two cases:

  1. On attendee connectOnAttendeeConnected calls UpdateDynamicInfo with the current property value.

  2. On property change while connected — assigning a new value triggers UpdateDynamicEnvironmentInfo, which calls UpdateDynamicInfo when a session proxy exists.

The wire payload shape is:

DynamicEnvironmentInfo does not pass through the debounce batch. It does not use canonical state/event assembly. For values that change frequently during gameplay, use Set Context State instead.

Use case
Recommended path

Session-level briefing set once or changed infrequently

DynamicEnvironmentInfo

Runtime facts that change during gameplay

Set Context State or Add Context Event

Relationship between connection data and live updates

Connection data establishes the realtime session and, when actions are enabled, the initial action configuration. Live updates carry information that changes after the session begins.

A dynamic state update like Health is 50 informs Convai about a current runtime fact. It does not edit the action_config that was sent at connection time. Push only what changes during play instead of re-sending the same connection data through the dynamic context pipeline.

Reconnect and the dynamic layer

With the default connection-proxy settings, calling Stop Session followed by Start Session creates a new realtime connection. If connection proxy reuse is enabled with a positive ConnectionProxyTTL, a same-character restart can reuse an orphaned connection. A new connection uses the current CharacterID, end-user identity fields, and action configuration at that moment. FConvaiDynamicContextTracker is an in-memory client-side structure; it is not automatically reset when the session restarts.

Call Reset Dynamic Context before reconnecting if you want a clean dynamic context tracker.

Pre-session dynamic context queuing

Default debounced calls to Set Context State, Set Context States, Add Context Event, and Remove Context State made before the session connects are safe from BeginPlay. Each call accumulates in PendingContextBatch. After the session becomes connected, the plugin flushes that batch on the first tick where the debounce deadline has elapsed.

Reset Dynamic Context before connect does not discard staged updates immediately — it marks a pending Reset that fires after any staged content drains at the first post-connect flush. To start from empty dynamic context, let the reset flush complete before staging new updates.

SessionID and realtime sessions

SessionID exists on UConvaiChatbotComponent, but the verified realtime /connect path in the current source does not send it as part of FConvaiConnectionParams. Do not rely on SessionID to control dynamic context reset behavior. Use Reset Dynamic Context for the tracked dynamic context layer.

Next steps

How dynamic context worksDynamic context quick start

Last updated

Was this helpful?