> ## 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.

# API reference

> createSession, Session, Ad, and the full event list.

## `createSession(options)` → `Session`

Creates an ad session tied to a specific **user** and **conversation**.

**publisherToken** `string` *required*

Your unique publisher token.

**userId** `string` *required*

Unique identifier that remains the same for the user's lifetime (used for personalization, frequency capping, and rewarded ads).

**conversationId** `string` *required*

Unique ID of the conversation or chat thread.

**enabledPlacementCodes** `string[]`

Placement codes enabled for the conversation. Defaults to `['inlineAd']`.

**character** `object`

Character metadata used for contextual ad selection and personalization.

**Properties**

**id** `string` *required*

Unique ID of the character.

**name** `string` *required*

Name of the character.

**avatarUrl** `string` *required*

URL of the character's avatar.

**isNsfw** `boolean`

Indicates whether the character is NSFW.

**greeting** `string`

The character's greeting.

**persona** `string`

Description of the character's personality.

**tags** `string[]`

Tags describing the character.

**regulatory** `object`

Privacy / consent signals.

**Properties**

**gdpr** `integer`

Indicates whether the request is subject to GDPR regulations. (0 = No, 1 = Yes, null = Unknown)

**gdprConsent** `string`

The IAB Transparency and Consent Framework (TCF) consent string.

**coppa** `integer`

Indicates whether the request is subject to COPPA. (0 = No, 1 = Yes, null = Unknown)

**gpp** `string`

Global Privacy Platform (GPP) consent string.

**gppSid** `number[]`

IDs of the GPP sections that apply to this transaction.

**usPrivacy** `string`

Signals regarding consumer privacy under US privacy regulations (e.g. CCPA, LSPA).

**userEmail** `string`

Email of the user, used for frequency-cap deduplication.

**variantId** `string`

Publisher-provided identifier for the user cohort (for A/B testing).

**onEvent** `function`

Callback invoked for every ad lifecycle event. See [Supported events](#supported-events) below.

**onDebugEvent** `function`

Callback for SDK-internal diagnostic events. Receives `(name, data?)` — useful when investigating preload/session behaviour during integration. Off by default.

## `Session` methods

### `session.addMessage(message, options?)`

Register a chat message with the SDK. Triggers a debounced preload when appropriate.

**message** `Message` *required*

See [`Message` shape](#message-shape).

**options** `object`

**Properties**

**trackOnly** `boolean`

When `true`, the preload request is still sent (for analytics) but no ad will be shown for this message.

### `session.createAd(messageId, options?)` → `Ad`

Create an `Ad` bound to a specific assistant message. Doesn't wait for an ad — the ad will render as soon as one is available. Calling `createAd` twice for the same `messageId` + `code` returns the existing instance.

**messageId** `string` *required*

ID of the assistant message the ad belongs to.

**options** `object`

**Properties**

**code** `string`

Placement code (default: `'inlineAd'`).

**theme** `string`

Visual theme passed to the ad iframe (e.g. `'light'`, `'dark'`).

### `session.render(options)` → `Ad`

Convenience wrapper for `createAd` + `mount` in one call.

**messageId** `string` *required*

ID of the assistant message the ad belongs to.

**element** `HTMLElement` *required*

Host element into which the ad iframe will be rendered.

**code** `string`

Placement code (default: `'inlineAd'`).

**theme** `string`

Visual theme.

### `session.updateOptions(partial)`

Live-update preload-scoped configuration on an active session. Accepted fields: `variantId`, `regulatory`, `userEmail`, `advertisingId`, `vendorId`. Read at the next `/preload`, so the change takes effect on the next user message — no session recreation needed.

> [!WARNING]
>
> `publisherToken`, `userId`, `conversationId`, `enabledPlacementCodes`, and `character` are **not** live-updateable. Changing them mid-session would desync the `/init` registration from subsequent requests, or leave the accumulated message history targeted at the wrong persona. Recreate the session instead.

### `session.destroy()`

Cleans up internal state, cancels in-flight preloads, and stops further preload requests. Call this when the conversation ends or the page unmounts. After `destroy()`, mutator methods (`addMessage`, `createAd`, `render`) throw.

### `session.getSessionId()` → `string | null`

Server-assigned session ID. `null` until the first successful `/preload`.

### `session.isDisabled()` → `boolean`

`true` if the server has permanently disabled this session via the `/init` response (e.g. geo-restriction). Subsequent preloads are skipped.

### `session.isDestroyed()` → `boolean`

`true` after `destroy()` has been called.

### `session.getMessages()` → `readonly Message[]`

Snapshot of messages tracked by the session, in insertion order. Do not mutate; do not cache long-term — the internal array is replaced with a trimmed copy when message count exceeds the cap.

### `session.getPreloadTimeout()` → `number`

Current `/preload` request timeout in milliseconds. May be overridden by the server via the `/init` response.

## `Ad` methods

### `ad.mount(element)`

Mounts the ad iframe inside the given DOM element. Each `Ad` instance can only be mounted once — re-mounting throws.

**element** `HTMLElement` *required*

Host element for the ad iframe.

### `ad.destroy()`

Removes the iframe from the DOM and releases all listeners. Idempotent — safe to call multiple times.

## `Message` shape

**id** `string` *required*

Unique, stable ID of the message.

**role** `'user' | 'assistant'` *required*

Role of the message author.

**content** `string` *required*

Message text.

**createdAt** `Date` *required*

Timestamp when the message was created.

## Supported events

### `ad.clicked`

The user has clicked the ad.

**Payload**

**id** `string`

Ad ID.

**content** `string`

Generated ad content.

**messageId** `string`

Message ID.

**url** `string`

Click URL.

**format** `string`

Ad format.

**area** `string`

Click area within the creative.

### `ad.viewed`

The user has viewed the ad.

**Payload**

**id** `string`

Ad ID.

**content** `string`

Generated ad content.

**messageId** `string`

Message ID.

**format** `string`

Ad format.

**revenue** `number`

Ad revenue per impression (eCPM in USD).

### `ad.filled`

Ad is available.

**Payload**

**id** `string`

Ad ID.

**code** `string`

Placement code this ad was matched to.

**revenue** `number`

Ad revenue per impression (eCPM in USD).

### `ad.no-fill`

Ad is not available.

**Payload**

**skipCode** `string`

The code indicating the reason why the ad was skipped.

### `ad.render-started`

Triggered before the first token is received.

**Payload**

**id** `string`

Ad ID.

### `ad.render-completed`

Triggered after the last token is received.

**Payload**

**id** `string`

Ad ID.

### `ad.error`

Triggered when an error occurs.

**Payload**

**message** `string`

Error message.

**errCode** `string`

Error code.

### `video.started`

Triggered when video playback starts.

**Payload**

**id** `string`

Ad ID.

### `video.completed`

Triggered when video playback finishes.

**Payload**

**id** `string`

Ad ID.

### `reward.granted`

The user has earned a reward (rewarded ad flow).

**Payload**

**id** `string`

Ad ID.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.