Typed payloads - Autoplay SDK

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

product_id

string

required

Connector product identifier.

session_id

string | None

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

user_id

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.

actions

list[SlimAction]

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

count

int

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

forwarded_at

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

product_id

string

required

Connector product identifier.

session_id

string | None

User session identifier.

summary

string

Prose description of what the user did during this session.

replaces

int

Number of individual actions this summary condenses.

forwarded_at

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

index

int

default:"0"

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

type

string

default:"\"\""

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

title

string

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

description

string

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

timestamp_start

float

default:"0.0"

Unix timestamp when this action began.

timestamp_end

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.

raw_url

string

default:"\"\""

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

canonical_url

string

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

session_id

string | None

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

user_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)

​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