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.

​
Data structure boundaries

Payload frames are only one part of the full session-linking model:
ConcernCanonical structureNotes
Session routing stateSessionState (agent_state.v2)session_id is primary scope; conversation_id is derived state
Conversation link transitionConversationLink + ConversationEventTypeNEW and REPLY_EXISTING semantics are applied by SessionState.on_conversation_linked(...)
Reverse lookupConversationLinkStorePersistent conversation_id -> session_id index for webhook resolution
Inbound webhook parseConversationWebhookEventParsed from platform webhook topic/payload
Outbound stream payloadsActionsPayload, SummaryPayload, SlimActionUsed for delivery, summarization, and embedding context
Proactive trigger inputProactiveTriggerContextBuilt from recent payloads + optional summary/context extras
Proactive trigger outputProactiveTriggerResultReturns body, optional reply_option_labels, and timing hints
Proactive choice/tour mappingTriggerMessage, TourRegistry, TourDefinitionMaps selected quick reply to optional tour metadata and per-tour timing overrides
Hot-path rule: delivery decisions should read session-owned fields (conversation_linked, conversation_id) from SessionState, not query ConversationLinkStore on every send. See Typed payloads, Agent session states, and BaseChatbotWriter.

​
If the user selects a proactive option

  1. Delivery surface sends back the selected quick-reply/chip id.
  2. Resolve that id to TriggerMessage (id, label, user_tour_exists, user_tour_id).
  3. Update SessionState interaction path (record_option_click() and related state updates).
  4. If user_tour_exists=True, resolve the matching TourDefinition in TourRegistry (by id or user_tour_id) and start visual guidance with the tour id.
  5. Continue routing by session-owned state (session_id primary; conversation_id derived).

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