> ## 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.
# π Quickstart
> Stream real-time user events into your support AI agents in a couple lines of code.
## β‘ Add this skill
Add the shared Autoplay SDK foundation skill for credentials and live-activity reads.
```bash CLI theme={null}
uvx --from autoplay-sdk autoplay-install-skills
```
View the docs β
Fetch this skill directly so your coding agent gets the same Autoplay SDK setup instructions.
```bash cURL theme={null}
curl -s https://developers.autoplay.ai/autoplay-core/SKILL.md
```
View the skill β
## Install the SDK
**Prerequisites β Python 3.10 or later required.**
Check your Python version:
```bash theme={null}
python3 --version
```
If Python is not installed, download it from [python.org](https://www.python.org/downloads/) or install via Homebrew:
```bash theme={null}
brew install python3
```
Then create and activate a virtual environment before installing:
```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
```
Check your Python version:
```powershell theme={null}
python --version
```
If Python is not installed, download it from [python.org](https://www.python.org/downloads/) and run the installer β check **"Add Python to PATH"** during setup.
Then create and activate a virtual environment before installing:
```powershell theme={null}
python -m venv .venv
.venv\Scripts\Activate.ps1
```
If you see a permissions error, run this once first:
`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
Run this command once from your project root (with your venv active):
```bash theme={null}
pip install autoplay-sdk
# OR
uv add autoplay-sdk
```
Install [Agent skills](/get-started/agent-skills) for Cursor/Claude so your assistant follows the correct integration pattern for your stack. See [Pricing](/who-we-are/pricing) for plans.
## π― Step 1 β Connect your session replay provider
Autoplay needs a live stream of what each user is doing before anything downstream can use it as context. Pick whichever tool you already have β already wired up? The tool's page tells you how to confirm it in seconds instead of redoing setup.
PostHog
β
Connect an existing PostHog project
Amplitude
β
Connect an existing Amplitude project
FullStory
Coming Soon
Full setup guide coming soon
Datadog
Coming Soon
Full setup guide coming soon
Pendo
Coming Soon
Full setup guide coming soon
## π€ Step 2 β Connect your AI support agent
This is where Autoplay actually does its job β giving your existing chatbot live context on what the user's been doing, pulled over MCP the moment it needs it.
Intercom
β
Connect Fin via MCP
Maven
β
Connect via MCP
Ada
Coming Soon
Connect via API
Botpress
Coming Soon
Connect via API
Dify
β
Connect via MCP
Crisp AI
β
Connect via MCP
Landbot
Coming Soon
Connect via API
Rasa
β
Connect via API
Inkeep
β
Connect via API
Tidio
β
Connect via API
Plain
β
Connect via API
Zendesk
Coming Soon
Full setup guide coming soon
## π Step 3 β Add the proactive layer
Steps 1 and 2 make your AI support agent **reactive** β it can answer with live context, but only when a user asks. This step makes it **proactive**: Autoplay.js watches the same activity stream in the browser and surfaces the next best action β a message or a tour β the moment a milestone happens, without the user asking "what's next?".
Autoplay.js is the piece that actually listens for nudges and dispatches them β through your configured tour provider, or as Autoplay's own nudge card when no provider is set up. Every proactive path (your chatbot's prompt, a plain nudge card, a tour) flows through this one connection.
Before you start, add the credentials created when you registered your product in Step 1 to your server environment:
```bash theme={null}
AUTOPLAY_PRODUCT_ID=your-product-id
AUTOPLAY_MCP_KEY=your-mcp-key
AUTOPLAY_MCP_BASE_URL=https://mcp.autoplay.ai
```
* `AUTOPLAY_PRODUCT_ID` is the issued `product_id` returned by Autoplay registration, not your PostHog or Amplitude project id.
* `AUTOPLAY_MCP_KEY` is the `mcp_key` returned by `onboard_product` during that same setup. Retrieve it from the saved terminal output or the secure 1Password link. If you no longer have it, contact Autoplay rather than registering a second product.
Keep `AUTOPLAY_MCP_KEY` server-side. Never expose it in frontend code or a public environment variable.
### Configure your onboarding
Autoplay uses one onboarding config, keyed by your `product_id`, to decide which milestones to detect and which experience to deliver:
```json theme={null}
{
"product_id": "your-product-id",
"workflows": [
{
"key": "connect_account",
"title": "Connect a social account",
"sort_order": 10,
"required": true,
"detect": "The user connected a social account β e.g. picked a platform and confirmed connecting a handle."
}
],
"tours": [
{
"workflow_key": "connect_account",
"name": "Connect your account",
"flow_id": "your-provider-flow-id"
}
],
"tour_provider": "appcues",
"exploration_gate": {
"min_seconds_on_app": 60,
"min_distinct_features": 3,
"welcome_cooldown_s": 600,
"max_proactive_support": 3
},
"nudge_delivery": {
"default": { "provider": "autoplay" }
}
}
```
`workflows` define the milestones Autoplay detects from live activity. `tours` map each workflow to a flow in your configured `tour_provider`; omit them if you only want Autoplay nudge cards.
Onboarding configuration is not self-serve yetβshare this JSON with the Autoplay team in [Discord](https://discord.gg/jCbR2tQA5).
### 1. Create a nudge-token endpoint
Add a server route that exchanges your MCP key for a short-lived token scoped to the current user:
```jsx theme={null}
export async function POST(request) {
const { userId } = await request.json();
const response = await fetch(
`${process.env.AUTOPLAY_MCP_BASE_URL}/nudges/${process.env.AUTOPLAY_PRODUCT_ID}/token`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.AUTOPLAY_MCP_KEY}`,
},
body: JSON.stringify({ user_id: userId }),
}
);
return Response.json(await response.json());
}
```
### 2. Connect the nudge stream
In your frontend, load Autoplay.js and connect it for the signed-in user. `AUTOPLAY_MCP_BASE_URL` is the production MCP origin, without the `/mcp` transport path:
```javascript theme={null}
const AUTOPLAY_MCP_BASE_URL = "https://mcp.autoplay.ai";
const { Autoplay } = await import(`${AUTOPLAY_MCP_BASE_URL}/autoplay.js`);
const nudgeHandle = Autoplay.connectNudges({
baseUrl: AUTOPLAY_MCP_BASE_URL,
productId: "your-product-id",
userId: "your-signed-in-user-id",
getToken: async () => {
const response = await fetch("/api/nudge-token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ userId: "your-signed-in-user-id" }),
});
const { token } = await response.json();
return token;
},
onNudge: handleNudge,
onError: (error) => console.warn("[autoplay] nudge stream error:", error),
});
```
Use the same stable user ID your app sends to the session replay provider. `getToken` should fetch a fresh token whenever it is called.
If you use a third-party tour provider, load and identify its SDK before calling `connectNudges` so it is ready when a tour arrives.
### 3. Dispatch nudges
Every nudge includes a `nudge_type`. Tour nudges hand off to the provider and flow configured above; other nudges render an Autoplay card:
```javascript theme={null}
function handleNudge(nudge) {
if (nudge.nudge_type === "tour") {
Autoplay.dispatchNudge(nudge);
nudgeHandle.report("chat_closed");
return;
}
Autoplay.dispatchNudge(nudge, {
onOpen: () => nudgeHandle.report("proactive_accepted_chat"),
onDismiss: () => nudgeHandle.report("proactive_dismissed"),
});
}
```
`Autoplay.dispatchNudge` returns a boolean indicating whether an experience rendered, which is useful to log during setup. A nudge card is the provider-agnostic fallback: Autoplay can offer help without requiring you to build a tour flow.
### 4. Own your tour or chat surface (optional)
By default Autoplay drives the built-in tour providers (Usertour, Appcues) and renders its own nudge card. If you own your tour system or chat UI, register callbacks with `Autoplay.configure` **before** `connectNudges`, and Autoplay routes nudges to them instead:
```javascript theme={null}
Autoplay.configure({
providers: {
// Your own tour system (Joyride, a custom highlighter, β¦).
tour: {
// Each callback also receives the full `nudge` payload as a second arg
// (nudge_type, next_workflow, delivery.ask, β¦) if you want to branch on it.
launch(delivery, nudge) { yourTours.start(delivery.flow_id); },
},
// A chat surface you built on your agent's API.
chat: {
deliver(content, nudge) { chat.injectAssistantMessage(content); }, // show authored copy β NO LLM call
dispatch(text, nudge) { chat.openAndSend(text); }, // send a real user turn to your agent
close(opts) { chat.hide(); }, // dismiss for a tour handoff
},
},
});
```
Resolution order per nudge: your `tour.launch` / `chat.deliver` first, then the built-in providers, then the Autoplay card as a fallback. A callback that returns `false` (or throws) falls through to the next option; returning nothing counts as handled. `chat.deliver` must **not** trigger an LLM turn β it only displays the pre-authored copy; use `chat.dispatch` for a real turn (e.g. when the user accepts a nudge). Register `chat.close` so a tour can dismiss your chat during handoff.
Registering a chat surface **takes over chat nudges from the card in Step 3**: when `chat.deliver` handles a nudge, the Autoplay card is suppressed, so the card's `onOpen` / `onDismiss` reporting (`proactive_accepted_chat` / `proactive_dismissed`) no longer fires for chat nudges. Emit those from your own callbacks instead, using the `report()` handle returned by `connectNudges` β e.g. `nudgeHandle.report("proactive_accepted_chat")` inside `chat.dispatch` (the user accepted), and `nudgeHandle.report("proactive_dismissed")` when the user dismisses your surface. Tour nudges still report as before.
### 5. Verify the connection
Sign in to your app, open the browser console, and confirm the nudge stream connects without calling `onError`. Autoplay can now dispatch provider-backed experiences and its own nudge cards. If you add visual guidance in Step 4, initialize that provider before calling `connectNudges`.
Autoplay.js only delivers the nudge at the right moment β something still has to decide *what to say* and *what shows up on screen*. Most AI support agents (Maven, Intercom's Fin, and others) don't do this on their own: they answer when asked, but they don't watch live activity or open a message by themselves.
To make your chatbot proactive:
1. **Add the proactive prompt for your chatbot platform.** This teaches the agent to offer the next step instead of only answering questions β follow the recipe for your platform from Step 2 above (e.g. Maven's **Add proactive layer** step).
2. **Add a way to show the offer.** Most chatbot platforms don't render their own proactive UI, so use a **user tour provider** (e.g. Appcues) to display the box the user actually sees and can accept or dismiss β or skip the tour provider and let Autoplay's own nudge card handle it (see the **Connect Autoplay.js** tab).
Full walkthrough β the proactive prompt plus the Appcues tour hand-off β in Maven β Add proactive layer.
Once connected, a dispatched nudge card looks like this β Autoplay offering the next step right after the AI agent confirms a milestone, with the user free to accept or dismiss:
If you're using Autoplay's built-in nudge card instead of a tour provider, its copy is customizable with a couple of options:
```javascript theme={null}
Autoplay.dispatchNudge(nudge, {
brandName: "Acme", // replaces the "Autoplay" label on the card β default "Autoplay"
ctaLabel: "Show me", // replaces the accept-button text β default "Show me how"
onOpen: () => nudgeHandle.report("proactive_accepted_chat"),
onDismiss: () => nudgeHandle.report("proactive_dismissed"),
});
```
The card's body text comes from `nudge.message` if your onboarding config sets one; otherwise Autoplay generates it from the milestone (e.g. "Nice progress! π Want me to walk you through **Setting your posting schedule**?"). Position, color, and layout are fixed today β `brandName` and `ctaLabel` are the only visual customization available.
## πΊοΈ Step 4 β Connect visual guidance
Optional. If you want to give your users the ultimate level of guidance, add visual guidance on top β pop-up tours today, and browser agents soon. Wire up a tour provider β Appcues, Usertour, Pendo, and more β so that once a user asks for more help from Step 3's proactive message, the right tour launches from the same event stream.
Trigger Appcues, Pendo, Usertour, and more once a user asks for more guidance β optional
## πΊοΈ What's next
Go deeper on the SDK:
Explore all fields on ActionsPayload and SummaryPayload
Embed events into a vector store in real time
Connect any agent to pull live activity via the MCP tool
Combine real-time events, memory, and golden paths
For structured logging and `extra` field conventions used across the SDK, see [Logging](/sdk/logging). Release history is on the [Changelog](/changelog).