Skip to main content
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.

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

    # 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.
​
email
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.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).

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