> ## 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. # Payload schema > Full JSON wire format for actions and summary events from the SSE stream. 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](/sdk/typed-payloads), [Agent session states](/sdk/agent-states), and [BaseChatbotWriter](/sdk/support-agent-writer). ### 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 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. ```json theme={null} { "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. ```json theme={null} { "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.