Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.autoplay.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Autoplay connector emits JSON events over the SSE stream (and the same actions object shape is POSTed to customer webhooks in push mode). The SDK parses these automatically into typed Python objects — you rarely need to work with the raw JSON directly, but this reference is useful when debugging or building your own client.

​
Event type reference

SSE frame/event typeDescriptionSDK handling
actionsBatch of UI actions for one sessionParsed as ActionsPayload; dispatched via on_actions
summaryLLM summary replacing many actionsParsed as SummaryPayload; dispatched via on_summary
usertour_triggerTrigger metadata for user-tour flowsNot parsed into SDK payload models yet; ignored by default stream clients
heartbeat (SSE event field)Keep-alive ping frameIgnored by SDK clients

​
actions event

Emitted when the connector extracts and forwards a batch of UI actions from a user session. 
{
  "type":       "actions",
  "product_id": "prod_abc",
  "session_id": "ps_abc123",
  "user_id":    "distinct_id_xyz",
  "email":      "user@example.com",
  "count":      3,
  "forwarded_at": 1700000000.0,
  "actions": [
    {
      "index":           0,
      "type":            "pageview",
      "title":           "Page Load: Dashboard",
      "description":     "User landed on the dashboard page",
      "timestamp_start": 1700000000.0,
      "timestamp_end":   1700000005.2,
      "raw_url":         "https://app.example.com/dashboard?ref=email",
      "canonical_url":   "https://app.example.com/dashboard",
      "session_id":      "ps_abc123",
      "user_id":         "distinct_id_xyz",
      "email":           "user@example.com"
    },
    {
      "index":           1,
      "type":            "click",
      "title":           "Click Export CSV button",
      "description":     "User clicked Export CSV button on the dashboard page",
      "timestamp_start": 1700000005.2,
      "timestamp_end":   1700000012.8,
      "raw_url":         "https://app.example.com/dashboard",
      "canonical_url":   "https://app.example.com/dashboard",
      "session_id":      "ps_abc123",
      "user_id":         "distinct_id_xyz",
      "email":           "user@example.com"
    },
    {
      "index":           2,
      "type":            "click",
      "title":           "Click billing settings link",
      "description":     "User clicked billing settings link on the settings page",
      "timestamp_start": 1700000012.8,
      "timestamp_end":   1700000012.8,
      "raw_url":         "https://app.example.com/settings/billing",
      "canonical_url":   "https://app.example.com/settings/billing",
      "session_id":      "ps_abc123",
      "user_id":         "distinct_id_xyz",
      "email":           "user@example.com"
    }
  ]
}

​
Top-level fields

FieldTypeDescription
typestringAlways "actions"
product_idstringConnector product identifier
session_idstring | nullUser session identifier
user_idstring | nullExternal user identifier passed at session boot
emailstring | nullUser email from the identity store
countintNumber of actions in this batch
forwarded_atfloatUnix timestamp when the connector forwarded this batch
actionsarrayOrdered list of action objects

​
Action object fields

FieldTypeDescription
indexint0-based position in the session sequence
typestringLowercase event type: "pageview", "click", "submit", "type", "focus", "blur"
titlestringHuman-readable label for the event
descriptionstringNatural-language description of what the user did
timestamp_startfloatUnix timestamp when the action began
timestamp_endfloatUnix timestamp when the action ended (next action’s start, or same for last)
raw_urlstringOriginal URL before canonicalization
canonical_urlstringNormalised page URL (dynamic segments → :id)
session_idstring | nullPostHog session id for this action (matches batch-level when known)
user_idstring | nullDistinct id / identified user id for this action
emailstring | nullUser email from PostHog when present

​
summary event

Emitted when the connector’s LLM summariser produces a prose description of a session. This is intended to replace raw action embeddings for context-window efficiency. 
{
  "type":         "summary",
  "product_id":   "prod_abc",
  "session_id":   "ps_abc123",
  "summary":      "The user navigated to the Dashboard, exported a CSV report, then opened account settings to update their billing plan.",
  "replaces":     12,
  "forwarded_at": 1700000060.0
}

​
Fields

FieldTypeDescription
typestringAlways "summary"
product_idstringConnector product identifier
session_idstring | nullUser session identifier
summarystringProse description of the session
replacesintNumber of individual actions this summary condenses
forwarded_atfloatUnix timestamp when the connector forwarded this summary

​
SSE frame format

Events arrive as standard SSE frames. The data field contains the JSON payload above. 
data: {"type":"actions","product_id":"prod_abc","session_id":"ps_abc123",...}

data: {"type":"summary","product_id":"prod_abc","session_id":"ps_abc123",...}

event: heartbeat
data:
The SDK silently ignores heartbeat frames — they are keep-alive pings sent every 30 seconds.