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

<ParamField path="publisherToken" type="string" required>
  Your unique publisher token.
</ParamField>

<ParamField path="userId" type="string" required>
  Unique identifier that remains the same for the user's lifetime (used for personalization, frequency capping, and rewarded ads).
</ParamField>

<ParamField path="conversationId" type="string" required>
  Unique ID of the conversation or chat thread.
</ParamField>

<ParamField path="enabledPlacementCodes" type="string[]" optional>
  Placement codes enabled for the conversation. Defaults to `['inlineAd']`.
</ParamField>

<ParamField path="character" type="object" optional>
  Character metadata used for contextual ad selection and personalization.

  <Expandable title="Properties">
    <ParamField path="id" type="string" required>Unique ID of the character.</ParamField>
    <ParamField path="name" type="string" required>Name of the character.</ParamField>
    <ParamField path="avatarUrl" type="string" required>URL of the character's avatar.</ParamField>
    <ParamField path="isNsfw" type="boolean" optional>Indicates whether the character is NSFW.</ParamField>
    <ParamField path="greeting" type="string" optional>The character's greeting.</ParamField>
    <ParamField path="persona" type="string" optional>Description of the character's personality.</ParamField>
    <ParamField path="tags" type="string[]" optional>Tags describing the character.</ParamField>
  </Expandable>
</ParamField>

<ParamField path="regulatory" type="object" optional>
  Privacy / consent signals.

  <Expandable title="Properties">
    <ParamField path="gdpr" type="integer" optional>Indicates whether the request is subject to GDPR regulations. (0 = No, 1 = Yes, null = Unknown)</ParamField>
    <ParamField path="gdprConsent" type="string" optional>The IAB Transparency and Consent Framework (TCF) consent string.</ParamField>
    <ParamField path="coppa" type="integer" optional>Indicates whether the request is subject to COPPA. (0 = No, 1 = Yes, null = Unknown)</ParamField>
    <ParamField path="gpp" type="string" optional>Global Privacy Platform (GPP) consent string.</ParamField>
    <ParamField path="gppSid" type="number[]" optional>IDs of the GPP sections that apply to this transaction.</ParamField>
    <ParamField path="usPrivacy" type="string" optional>Signals regarding consumer privacy under US privacy regulations (e.g. CCPA, LSPA).</ParamField>
  </Expandable>
</ParamField>

<ParamField path="userEmail" type="string" optional>
  Email of the user, used for frequency-cap deduplication.
</ParamField>

<ParamField path="variantId" type="string" optional>
  Publisher-provided identifier for the user cohort (for A/B testing).
</ParamField>

<ParamField path="onEvent" type="function" optional>
  Callback invoked for every ad lifecycle event. See [Supported events](#supported-events) below.
</ParamField>

<ParamField path="onDebugEvent" type="function" optional>
  Callback for SDK-internal diagnostic events. Receives `(name, data?)` — useful when investigating preload/session behaviour during integration. Off by default.
</ParamField>

## `Session` methods

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

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

<ParamField path="message" type="Message" required>
  See [`Message` shape](#message-shape).
</ParamField>

<ParamField path="options" type="object" optional>
  <Expandable title="Properties">
    <ParamField path="trackOnly" type="boolean" optional>
      When `true`, the preload request is still sent (for analytics) but no ad will be shown for this message.
    </ParamField>
  </Expandable>
</ParamField>

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

<ParamField path="messageId" type="string" required>
  ID of the assistant message the ad belongs to.
</ParamField>

<ParamField path="options" type="object" optional>
  <Expandable title="Properties">
    <ParamField path="code" type="string" optional>Placement code (default: `'inlineAd'`).</ParamField>
    <ParamField path="theme" type="string" optional>Visual theme passed to the ad iframe (e.g. `'light'`, `'dark'`).</ParamField>
  </Expandable>
</ParamField>

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

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

<ParamField path="messageId" type="string" required>ID of the assistant message the ad belongs to.</ParamField>
<ParamField path="element" type="HTMLElement" required>Host element into which the ad iframe will be rendered.</ParamField>
<ParamField path="code" type="string" optional>Placement code (default: `'inlineAd'`).</ParamField>
<ParamField path="theme" type="string" optional>Visual theme.</ParamField>

### `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.
</Warning>

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

<ParamField path="element" type="HTMLElement" required>Host element for the ad iframe.</ParamField>

### `ad.destroy()`

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

## `Message` shape

<ParamField path="id" type="string" required>Unique, stable ID of the message.</ParamField>
<ParamField path="role" type="'user' | 'assistant'" required>Role of the message author.</ParamField>
<ParamField path="content" type="string" required>Message text.</ParamField>
<ParamField path="createdAt" type="Date" required>Timestamp when the message was created.</ParamField>

## Supported events

### `ad.clicked`

The user has clicked the ad.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
  <ParamField path="content" type="string">Generated ad content.</ParamField>
  <ParamField path="messageId" type="string">Message ID.</ParamField>
  <ParamField path="url" type="string">Click URL.</ParamField>
  <ParamField path="format" type="string">Ad format.</ParamField>
  <ParamField path="area" type="string">Click area within the creative.</ParamField>
</Expandable>

### `ad.viewed`

The user has viewed the ad.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
  <ParamField path="content" type="string">Generated ad content.</ParamField>
  <ParamField path="messageId" type="string">Message ID.</ParamField>
  <ParamField path="format" type="string">Ad format.</ParamField>
  <ParamField path="revenue" type="number" optional>Ad revenue per impression (eCPM in USD).</ParamField>
</Expandable>

### `ad.filled`

Ad is available.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
  <ParamField path="code" type="string">Placement code this ad was matched to.</ParamField>
  <ParamField path="revenue" type="number" optional>Ad revenue per impression (eCPM in USD).</ParamField>
</Expandable>

### `ad.no-fill`

Ad is not available.

<Expandable title="Payload">
  <ParamField path="skipCode" type="string">The code indicating the reason why the ad was skipped.</ParamField>
</Expandable>

### `ad.render-started`

Triggered before the first token is received.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
</Expandable>

### `ad.render-completed`

Triggered after the last token is received.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
</Expandable>

### `ad.error`

Triggered when an error occurs.

<Expandable title="Payload">
  <ParamField path="message" type="string">Error message.</ParamField>
  <ParamField path="errCode" type="string">Error code.</ParamField>
</Expandable>

### `video.started`

Triggered when video playback starts.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
</Expandable>

### `video.completed`

Triggered when video playback finishes.

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
</Expandable>

### `reward.granted`

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

<Expandable title="Payload">
  <ParamField path="id" type="string">Ad ID.</ParamField>
</Expandable>