Typed payloads

All callbacks receive typed dataclass instances, not raw dicts. Your IDE will autocomplete every field, and each model has a .to_text() method that returns an embedding-ready string.

Data structures at a glance

Use this map to understand which structure owns which concern:

Structure	Layer	Primary key / scope	Write path	Read path
`SessionState`	`agent_state.v2`	`session_id`	`SessionState` transitions + `on_conversation_linked(link)`	Delivery routing and state-machine decisions
`ConversationLink`	`chat`	(`session_id`, `conversation_id`, `event`)	Created by `link_conversation(...)`	Transition input to `SessionState` and store sync
`ConversationLinkStore`	`chat`	`conversation_id -> session_id`	`store.save(link)` inside `link_conversation(...)`	Webhook/reverse lookup only (not delivery hot path)
`ConversationWebhookEvent`	`chat` webhook parsing	inbound platform payload	`extract_conversation_event(...)` parser output	Identity/session resolution before linking
`ActionsPayload`	event stream payload	session batch	connector emits `actions` frame	`on_actions` callbacks, context writers, embeddings
`SummaryPayload`	event stream payload	session summary	summarizer emits `summary` frame	`on_summary` callbacks and retrieval context
`SlimAction`	action item payload	per-action within batch	included in `ActionsPayload.actions`	formatting, embeddings, and downstream replay
`ProactiveTriggerContext`	proactive trigger evaluation	`session_id`, `product_id`, optional `conversation_id`	built each proactive tick from recent payloads	input to `ProactiveTriggerRegistry.evaluate_first(...)`
`ProactiveTriggerResult`	proactive trigger output	`trigger_id` + delivery fields	returned by matching trigger	delivery layer (`body`, `reply_option_labels`, timings)
`TriggerMessage`	proactive trigger config	stable chip `id` + `label`	configured in `ProactiveTriggerConfig.messages`	maps user chip selection to optional tour launch
`TourDefinition` / `TourRegistry`	proactive visual-guidance registry	`id` / `user_tour_id`	parsed from `integration_config.tour_registry`	resolves per-tour timeout/cooldown and launch metadata

Directionality rules:

Session-owned routing state: SessionState.conversation_linked + SessionState.conversation_id
Reverse index lookup: ConversationLinkStore (conversation_id -> session_id)
Inbound webhook parse DTO: ConversationWebhookEvent
Outbound action/summary transport: ActionsPayload, SummaryPayload, SlimAction
Proactive decision input/output: ProactiveTriggerContext and ProactiveTriggerResult
Proactive choice-to-tour mapping: TriggerMessage with TourRegistry/TourDefinition

ActionsPayload

Delivered when the connector forwards a batch of UI actions from a user session.

from autoplay_sdk import ActionsPayload

def on_actions(payload: ActionsPayload):
    print(payload.session_id)   # identify the session
    print(payload.email)        # tie to a user identity
    print(payload.count)        # number of actions in this batch

    for action in payload.actions:
        print(action.title)
        print(action.description)
        print(action.canonical_url)
        print(action.session_id, action.user_id, action.email)

    # embedding-ready string — pass directly to your embedding API
    text = payload.to_text()

to_text() example output:

Session ps_abc123 — 3 actions
[0] pageview: User landed on the dashboard page — https://app.example.com/dashboard
[1] click: User clicked Export CSV button — https://app.example.com/dashboard
[2] click: User opened billing settings — https://app.example.com/settings/billing

Fields

string

required

Connector product identifier.

string | None

User session identifier. None for anonymous sessions before identity linking.

string | None

External user identifier passed at session boot. None when the session is fully anonymous.

string | None

User email if available from the identity store.

list[SlimAction]

Ordered list of UI actions in this batch. See SlimAction below.

int

Number of actions in this batch. Equals len(actions).

float

Unix timestamp (float) when the connector forwarded this batch.

`ActionsPayload.merge(payloads)`

Merges a non-empty list of ActionsPayload objects for the same session into one.

Actions are concatenated and re-indexed sequentially from 0
user_id / email resolved from the first non-None value across all inputs
forwarded_at set to the latest timestamp across all inputs
Raises ValueError if payloads is empty

merged = ActionsPayload.merge([payload_a, payload_b])
# merged.actions == [*payload_a.actions, *payload_b.actions]  (re-indexed)
# merged.count   == len(merged.actions)

Used internally by AsyncAgentContextWriter when debounce_ms > 0 to combine payloads that arrive within the accumulation window before calling write_actions.

SummaryPayload

Delivered when the connector’s LLM summariser produces a prose description of a session. Replaces the raw action list for context-window efficiency in RAG pipelines.

from autoplay_sdk import SummaryPayload

def on_summary(payload: SummaryPayload):
    print(payload.session_id)
    print(payload.replaces)    # how many actions this summary replaces

    # the prose summary string — pass directly to your embedding API
    text = payload.to_text()

to_text() example output:

The user navigated to the Dashboard, exported a CSV report, then opened
account settings to update their billing plan.

Fields

string

required

Connector product identifier.

string | None

User session identifier.

string

Prose description of what the user did during this session.

int

Number of individual actions this summary condenses.

float

Unix timestamp when the connector forwarded this summary.

SlimAction

A single UI action inside ActionsPayload.actions.

for action in payload.actions:
    action.index            # 0, 1, 2 ... position in the session
    action.type             # "pageview", "click", "submit", "type", ...
    action.title            # "Page Load: Dashboard" or "Click Export CSV button"
    action.description      # "User landed on the dashboard page"
    action.timestamp_start  # unix float — when the action began
    action.timestamp_end    # unix float — when the next action began
    action.raw_url          # "https://app.example.com/dashboard?ref=email"
    action.canonical_url    # "https://app.example.com/dashboard"
    action.session_id       # PostHog session id (or None)
    action.user_id          # distinct id / user id (or None)
    action.email            # email from PostHog properties (or None)
    action.to_text()        # "[0] pageview: User landed on the dashboard page — ..."

Fields

int

default:"0"

0-based position of this action in the session sequence.

string

default:"\"\""

Lowercase event type. One of "pageview", "click", "submit", "type", "focus", "blur".

string

Human-readable label for the event (e.g. "Page Load: Dashboard" or "Click Export CSV button").

string

Natural-language description of what the user did (e.g. "User landed on the dashboard page").

float

default:"0.0"

Unix timestamp when this action began.

float

default:"0.0"

Unix timestamp when this action ended (equals the next action’s timestamp_start). For the last action in a batch this equals timestamp_start.

string

default:"\"\""

Original URL as captured, before canonicalization (includes query strings and fragments).

string

Normalised page URL with dynamic path segments collapsed to :id (e.g. https://app.example.com/projects/:id).

string | None

PostHog session id for this action. None when unknown (same semantics as batch-level session_id).

string | None

Distinct id or identified user id for this action. None when anonymous.

string | None

User email from PostHog identity properties when present.

Using `.to_text()` for embeddings

Both payload types expose .to_text() so you can embed either without branching:

from autoplay_sdk import ActionsPayload, SummaryPayload

def embed_any(payload: ActionsPayload | SummaryPayload):
    text = payload.to_text()         # works on both types
    embedding = embed_api.encode(text)
    vector_store.upsert(id=payload.session_id, vector=embedding)

Who We Are

Get Started

Live User Activity

AI Support Agents

Visual User Tours

Receive events

🔌 Live activity via MCP

Build with events

Integration helpers

Context sources

Reference

Data structures at a glance

ActionsPayload

Fields

`ActionsPayload.merge(payloads)`

SummaryPayload

Fields

SlimAction

Fields

Using `.to_text()` for embeddings

​Data structures at a glance

​ActionsPayload

​Fields

​ActionsPayload.merge(payloads)

​SummaryPayload

​Fields

​SlimAction

​Fields

​Using .to_text() for embeddings

Data structures at a glance

ActionsPayload

Fields

`ActionsPayload.merge(payloads)`

SummaryPayload

Fields

SlimAction

Fields

Using `.to_text()` for embeddings