Payload schema - Autoplay SDK

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:

Concern	Canonical structure	Notes
Session routing state	`SessionState` (`agent_state.v2`)	`session_id` is primary scope; `conversation_id` is derived state
Conversation link transition	`ConversationLink` + `ConversationEventType`	`NEW` and `REPLY_EXISTING` semantics are applied by `SessionState.on_conversation_linked(...)`
Reverse lookup	`ConversationLinkStore`	Persistent `conversation_id -> session_id` index for webhook resolution
Inbound webhook parse	`ConversationWebhookEvent`	Parsed from platform webhook topic/payload
Outbound stream payloads	`ActionsPayload`, `SummaryPayload`, `SlimAction`	Used for delivery, summarization, and embedding context
Proactive trigger input	`ProactiveTriggerContext`	Built from recent payloads + optional summary/context extras
Proactive trigger output	`ProactiveTriggerResult`	Returns `body`, optional `reply_option_labels`, and timing hints
Proactive choice/tour mapping	`TriggerMessage`, `TourRegistry`, `TourDefinition`	Maps 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

Delivery surface sends back the selected quick-reply/chip id.
Resolve that id to TriggerMessage (id, label, user_tour_exists, user_tour_id).
Update SessionState interaction path (record_option_click() and related state updates).
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.
Continue routing by session-owned state (session_id primary; conversation_id derived).

Event type reference

SSE frame/event type	Description	SDK handling
`actions`	Batch of UI actions for one session	Parsed as `ActionsPayload`; dispatched via `on_actions`
`summary`	LLM summary replacing many actions	Parsed as `SummaryPayload`; dispatched via `on_summary`
`usertour_trigger`	Trigger metadata for user-tour flows	Not parsed into SDK payload models yet; ignored by default stream clients
`heartbeat` (SSE `event` field)	Keep-alive ping frame	Ignored 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

Field	Type	Description
`type`	string	Always `"actions"`
`product_id`	string	Connector product identifier
`session_id`	string \| null	User session identifier
`user_id`	string \| null	External user identifier passed at session boot
`email`	string \| null	User email from the identity store
`count`	int	Number of actions in this batch
`forwarded_at`	float	Unix timestamp when the connector forwarded this batch
`actions`	array	Ordered list of action objects

Action object fields

Field	Type	Description
`index`	int	0-based position in the session sequence
`type`	string	Lowercase event type: `"pageview"`, `"click"`, `"submit"`, `"type"`, `"focus"`, `"blur"`
`title`	string	Human-readable label for the event
`description`	string	Natural-language description of what the user did
`timestamp_start`	float	Unix timestamp when the action began
`timestamp_end`	float	Unix timestamp when the action ended (next action’s start, or same for last)
`raw_url`	string	Original URL before canonicalization
`canonical_url`	string	Normalised page URL (dynamic segments → `:id`)
`session_id`	string \| null	PostHog session id for this action (matches batch-level when known)
`user_id`	string \| null	Distinct id / identified user id for this action
`email`	string \| null	User 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

Field	Type	Description
`type`	string	Always `"summary"`
`product_id`	string	Connector product identifier
`session_id`	string \| null	User session identifier
`summary`	string	Prose description of the session
`replaces`	int	Number of individual actions this summary condenses
`forwarded_at`	float	Unix 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.

​Data structure boundaries

​If the user selects a proactive option

​Event type reference

​actions event

​Top-level fields

​Action object fields

​summary event

​Fields

​SSE frame format