🚀 Quickstart

⚡ Add this skill

One command

Add the shared Autoplay SDK foundation skill for credentials and live-activity reads.

uvx --from autoplay-sdk autoplay-install-skills

View the docs →

Agent onboarding

Fetch this skill directly so your coding agent gets the same Autoplay SDK setup instructions.

curl -s https://developers.autoplay.ai/autoplay-core/SKILL.md

View the skill →

Install the SDK

Prerequisites — Python 3.10 or later required.

Mac / Linux
Windows (PowerShell)

Check your Python version:

python3 --version

If Python is not installed, download it from python.org or install via Homebrew:

brew install python3

Then create and activate a virtual environment before installing:

python3 -m venv .venv
source .venv/bin/activate

Check your Python version:

python --version

If Python is not installed, download it from python.org and run the installer — check “Add Python to PATH” during setup.Then create and activate a virtual environment before installing:

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):

pip install autoplay-sdk
# OR
uv add autoplay-sdk

Install Agent skills for Cursor/Claude so your assistant follows the correct integration pattern for your stack. See 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

FullStoryComing Soon

Full setup guide coming soon

DatadogComing Soon

Full setup guide coming soon

PendoComing 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

AdaComing Soon

Connect via API

BotpressComing Soon

Connect via API

Dify→

Connect via MCP

Crisp AI→

Connect via MCP

LandbotComing Soon

Connect via API

Rasa→

Connect via API

Inkeep→

Connect via API

Tidio→

Connect via API

Plain→

Connect via API

ZendeskComing 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?”.

Connect Autoplay.js
Make your chatbot proactive

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.

Configure Autoplay.js — about 5 minutes

Before you start, add the credentials created when you registered your product in Step 1 to your server environment:

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:

{
  "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.

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:

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:

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:

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:

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:

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

Maven example

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:

Autoplay nudge card proactively offering to walk the user through setting their posting schedule right after they connect a social account

If you’re using Autoplay’s built-in nudge card instead of a tour provider, its copy is customizable with a couple of options:

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.

Connect visual guidance

Trigger Appcues, Pendo, Usertour, and more once a user asks for more guidance — optional

🗺️ What’s next

Go deeper on the SDK:

Typed payloads

Explore all fields on ActionsPayload and SummaryPayload

RAG pipeline

Embed events into a vector store in real time

MCP server

Connect any agent to pull live activity via the MCP tool

Proactive onboarding agent

Combine real-time events, memory, and golden paths

For structured logging and extra field conventions used across the SDK, see Logging. Release history is on the Changelog.

Who We Are

Get Started

Live User Activity

AI Support Agents

Visual User Tours

Receive events

🔌 Live activity via MCP

Build with events

Integration helpers

Context sources

Reference

⚡ Add this skill

One command

Agent onboarding

Install the SDK

🎯 Step 1 — Connect your session replay provider

🤖 Step 2 — Connect your AI support agent

🔔 Step 3 — Add the proactive layer

Configure your onboarding

1. Create a nudge-token endpoint

2. Connect the nudge stream

3. Dispatch nudges

4. Own your tour or chat surface (optional)

5. Verify the connection

Maven example

🗺️ Step 4 — Connect visual guidance

Connect visual guidance

🗺️ What’s next

Typed payloads

RAG pipeline

MCP server

Proactive onboarding agent

​⚡ Add this skill

One command

Agent onboarding

​Install the SDK

​🎯 Step 1 — Connect your session replay provider

​🤖 Step 2 — Connect your AI support agent

​🔔 Step 3 — Add the proactive layer

​Configure your onboarding

​1. Create a nudge-token endpoint

​2. Connect the nudge stream

​3. Dispatch nudges

​4. Own your tour or chat surface (optional)

​5. Verify the connection

Maven example

​🗺️ Step 4 — Connect visual guidance

Connect visual guidance

​🗺️ What’s next

Typed payloads

RAG pipeline

MCP server

Proactive onboarding agent

⚡ Add this skill

Install the SDK

🎯 Step 1 — Connect your session replay provider

🤖 Step 2 — Connect your AI support agent

🔔 Step 3 — Add the proactive layer

Configure your onboarding

1. Create a nudge-token endpoint

2. Connect the nudge stream

3. Dispatch nudges

4. Own your tour or chat surface (optional)

5. Verify the connection

🗺️ Step 4 — Connect visual guidance

🗺️ What’s next