Session lifecycle

Documentation Index

Fetch the complete documentation index at: https://docs.kontext.so/llms.txt

Use this file to discover all available pages before exploring further.

A Session represents a single chat conversation. It is the unit of work the SDK is organized around — it holds the conversation context, the ad cache, the active network calls, and the event stream. Every Kontext integration creates, uses, and disposes of sessions following the same lifecycle, even if the exact API surface differs slightly between SDKs.

​

One session per conversation

A session is bound to one user in one conversation. When the user starts a new conversation, you create a new session with a new conversationId. Do not reuse a session across conversations.

​

The four stages

Every session goes through the same four stages, regardless of SDK.

​

1. Create

You create a session by supplying the IDs and options that describe the conversation:

• publisherToken — issued during onboarding, identifies your account.
• userId — a stable identifier for this user that does not change between conversations.
• conversationId — unique to this conversation.
• Optional: character, regulatory, variantId, callbacks for events and debug output.

The full list and exact field names per SDK live on the SDK pages. See IDs and tokens for what each identifier is for. As part of creation, the SDK calls POST /init in the background. The response carries server-controlled flags: whether the session is enabled at all, the preloadTimeout, and the two telemetry toggles (reportErrors, reportDebug). These are stable for the lifetime of the session — recreate the session if you need them refreshed.

​

2. Feed messages

As the conversation progresses, your app calls addMessage for each new message. Both user and assistant messages should go through this call — the SDK uses the full conversation, not just the last message, to find a contextually relevant ad. Each addMessage triggers a debounced POST /preload. The SDK pairs the returned ads with assistant message ids and emits a filled or no-fill event for each. See Messages for what each message must contain and why stable IDs matter.

​

3. Listen for events

The session is also the channel through which the SDK reports back to your app. Events flow on a single stream:

• Preload-time events — filled and no-fill per messageId, as soon as /preload resolves.
• Render-time events — viewed, clicked, error, plus video and rewarded events when applicable, while a mounted ad component is showing the ad.

How you subscribe depends on the SDK: a callback closure, a Combine publisher, a Kotlin Flow, a React event prop, etc. See Ad lifecycle events for the complete event list and what each one means.

​

4. Close

When the conversation ends, close the session. Closing:

• Cancels any in-flight /preload, /error, or /debug requests.
• Releases the ad cache.
• Stops the event stream.

Imperative SDKs (Swift, Kotlin, JS) expose this as an explicit close() call. Declarative SDKs (React, React Native, Vue, Flutter) close the session automatically when the AdsProvider unmounts — there is nothing extra for you to call. Forgetting to close an imperative session leaks resources, but it is not catastrophic — the next session created for the same user will work normally.

​

Mutable vs. immutable options

Most options you pass at creation time are immutable — to change them, close the session and create a new one. A few options are mutable at runtime; common ones include the regulatory object (consent strings can change after the CMP prompt) and, in some SDKs, the character. The mutable surface is intentionally small to keep the ad cache and the conversation context consistent. Refer to the SDK page for which options on your platform are mutable and how to update them.

​

Where to next