Step 1 — Connect real-time events

⚡ Add this skill

One command

Add the Autoplay Ada skill for an existing Ada AI support agent setup.

uvx --from autoplay-sdk autoplay-install-skills --chatbot ada

View the docs →

Agent onboarding

Fetch this skill when a customer already uses Ada and wants its AI support agent to consume Autoplay live user activity.

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

View the skill →

Pull a user’s live activity from Autoplay on demand and inject it into Ada’s AI Agent via metaFields — so every conversation is grounded in what the user is actually doing in your product.

✨ Final result

Without real-time context
With real-time context

User: Is there a way to automatically notify my team when a task is done?

Ada: Yes! You can use Automations for this. Go to the Automations centre
on your board and set up a rule like "When status changes to Done, notify someone."

User: Where is the Automations centre?

No idea the user has already done this manually 9 times. Forces a follow-up.

Live context: Board 4452109 · status → "Done" × 9 · no automation visits

User: Is there a way to automatically notify my team when a task is done?

Ada: Looks like you've been marking items Done manually — you can automate
that with one rule. Click the ⚡ lightning bolt at the top of this board →
search "status changes" → pick "When status changes to Done, notify someone"
and select your team. Takes 30 seconds.

Spots the repetitive behaviour, gives the exact click path, skips the follow-up.

How this works — PostHog or Amplitude sends events to Autoplay’s ingest endpoint as users act in your product. There’s no stream to subscribe to: your backend pulls a user’s recent activity on demand — a single REST call to Autoplay’s live-activity endpoint, keyed by product_id + user_id — the moment a user opens Ada. That response is formatted into metaFields and passed to the Ada embed before — or during — a chat session. Ada’s AI Agent reads these variables inside your bot’s Processes to personalise responses.

📋 Prerequisites

Before starting, confirm the following:

Ada already integrated on your web app — the Ada embed script is installed, your bot handle is configured, and Ada is opening chat sessions successfully.
PostHog or Amplitude already set up — complete the Quickstart first, with posthog.identify(user.id) (or amplitude.setUserId(user.id)) setting a stable user_id on login.
Your product_id and mcp_key — printed by onboard_product in the Quickstart.
autoplay-sdk installed — pip install autoplay-sdk
A backend you can add one route to — FastAPI is shown below, but any framework that can make an outbound HTTP call works.

How identity works — Autoplay keys a user’s live activity by the stable user_id your activity source identifies them with — the same id you pass to posthog.identify(user.id) or amplitude.setUserId(user.id). There’s no session id in the read API: every lookup is GET /users/{product_id}/{user_id}/live-activity, scoped only by product and user.When the user opens Ada, your frontend passes that same user_id to your /context/{user_id} endpoint (Step 2 below), which fetches their live activity and returns it as metaFields.If a user is anonymous (not yet identified), your activity source still records events under an anonymous id — Autoplay will have context for that id, but it won’t be linked to a real user account until you call identify / setUserId.

PostHog
Amplitude

posthog.identify(user.id); // same id you must pass to /context/{user_id}

amplitude.setUserId(user.id); // same id you must pass to /context/{user_id}

How the pieces fit: your app identifies the user in PostHog/Amplitude → Autoplay stores activity under that user_id → your frontend passes the same user_id to /context/{user_id} before opening Ada → the returned metaFields are populated with that user’s real activity.

The building blocks

Define Variables in Ada — Create the Variables your bot Processes will read. Done once in the Ada dashboard.
Serve context to the Ada SDK — Expose a lightweight endpoint that pulls a user’s live activity from Autoplay on demand (a single REST call — no listener process, no local cache) and passes it as metaFields.
Use Variables in your Ada Processes (Step 2 — coming soon) — Reference the injected variables in your bot’s Process conditions and responses.

🔧 Step 1 — Define Variables in Ada

When you pass metaFields to the Ada embed, those keys become Variables your bot Processes can read. Create these in your Ada dashboard under Build → Variables → + New Variable.

Variable name (= `metaFields` key)	Type	Description
`user_id`	String	Stable id from your activity source — keys the backend lookup
`current_page`	String	URL the user is on, taken from their most recent action
`recent_actions`	String	User’s recent in-app actions as a numbered list

Ada metaFields keys must not include whitespace, emojis, special characters, or periods. Use underscores as shown above. Keys are case-sensitive and must match exactly between the backend response and the frontend metaFields object.

We dropped session_summary from this table. The live-activity endpoint already returns a bounded, recent window (the limit query param), so there’s no separate summarisation step to run or store. If you want a narrative summary for longer histories, generate it inside your own /context/{user_id} handler and add it back as a metaField — it’s optional, not required for this integration to work.

🌐 Step 2 — Serve context to the Ada SDK

Your backend exposes one route: GET /context/{user_id}. It calls Autoplay’s live-activity endpoint synchronously, formats the result, and returns it. No stream to consume, no worker process, no Redis — the call happens the moment your frontend needs it.

Install dependencies

pip install autoplay-sdk fastapi uvicorn httpx

FastAPI context endpoint

# api.py
import httpx
from fastapi import FastAPI

app = FastAPI()

CONNECTOR_URL = "https://mcp.autoplay.ai"   # origin of your mcp_url, without /mcp
PRODUCT_ID    = "your-product-id"           # from onboard_product (Quickstart)
MCP_KEY       = "your-mcp-key"              # from onboard_product (Quickstart)

@app.get("/context/{user_id}")
async def context_for_user(user_id: str):
    async with httpx.AsyncClient() as client:
        res = await client.get(
            f"{CONNECTOR_URL}/users/{PRODUCT_ID}/{user_id}/live-activity",
            params={"limit": 10},
            headers={"Authorization": f"Bearer {MCP_KEY}"},
        )

    if res.status_code != 200:
        return {"user_id": user_id, "current_page": "", "recent_actions": ""}

    actions = res.json().get("actions", [])

    current_page = actions[-1]["canonical_url"] if actions else ""
    recent_actions = "\n".join(
        f"[{i + 1}] {a['title']} — {a['description']}"
        for i, a in enumerate(actions)
    )

    return {
        "user_id":        user_id,
        "current_page":   current_page,
        "recent_actions": recent_actions,
    }

Protect this endpoint in production. Validate with a session cookie or short-lived signed token tied to the logged-in user — not the raw user_id alone, which would let any caller read any user’s context.

Add the Ada embed script

Add data-lazy to your Ada embed script. This prevents Ada from initialising until you call adaEmbed.start(), so you can fetch the user’s live activity context first and pass it in on the first open.

<!-- In <head>. Replace YOUR-BOT-HANDLE. -->
<script
  id="__ada"
  data-handle="YOUR-BOT-HANDLE"
  data-lazy
  src="https://static.ada.support/embed2.js"
></script>

Open Ada with live context

// support.js

// ── User identity ───────────────────────────────────────────────────────
// This MUST be the same stable id you pass to posthog.identify(user.id) or
// amplitude.setUserId(user.id) — not a session id, not an email. Resolve it
// from your own auth/session state.
function getCurrentUserId() {
  return window.currentUser?.id ?? null;
}

// ── Ada initialisation state ──────────────────────────────────────────────
// Do NOT use `window.adaEmbed` to check if Ada is ready.
// With data-lazy, window.adaEmbed exists as soon as the embed script loads —
// BEFORE start() is called. Calling setMetaFields() or toggle() at that point
// silently fails and the widget never opens.
// Use this flag instead, set only inside adaReadyCallback.
let adaReady = false;

// ── Main: wire to your "Contact Support" button ───────────────────────────
async function openAdaWithContext() {
  const userId = getCurrentUserId();

  let meta = {
    user_id:        userId ?? 'anonymous',
    current_page:   window.location.pathname,
    recent_actions: '',
  };

  if (userId) {
    try {
      const res = await fetch(`/context/${userId}`);
      if (!res.ok) throw new Error(`Context endpoint ${res.status}`);
      const ctx = await res.json();
      meta = { ...meta, ...ctx };
    } catch (e) {
      // Fail open — Ada opens without extra context rather than not opening at all
      console.warn('Autoplay context unavailable:', e);
    }
  }

  if (adaReady) {
    // Ada already initialised — update metaFields in-place then toggle open
    await window.adaEmbed.setMetaFields(meta);
    await window.adaEmbed.toggle();
    return;
  }

  // First open — initialise Ada with metaFields pre-loaded
  await window.adaEmbed.start({
    handle: 'YOUR-BOT-HANDLE',
    metaFields: meta,
    adaReadyCallback: () => {
      adaReady = true;           // mark ready BEFORE toggling
      window.adaEmbed.toggle();
    },
  });
}

// ── SPA: update current_page on every navigation ─────────────────────────
// React Router and other SPA frameworks navigate via history.pushState(),
// which does NOT fire the popstate event. Patch pushState to emit a custom
// event so all navigations are caught — not just browser back/forward.
(function patchHistory() {
  const _push = history.pushState.bind(history);
  history.pushState = function (...args) {
    _push(...args);
    window.dispatchEvent(new Event('spa:navigate'));
  };
})();

window.addEventListener('spa:navigate', async () => {
  if (!adaReady) return;
  await window.adaEmbed.setMetaFields({ current_page: window.location.pathname });
});

// ── Ada event subscriptions ───────────────────────────────────────────────
// adaSettings must be defined BEFORE the <script> tag that loads embed2.js
// to guarantee onAdaEmbedLoaded fires before any events are triggered.
window.adaSettings = {
  onAdaEmbedLoaded: () => {
    // Stop pushing context updates once a live agent joins —
    // the human agent already has the context they need
    window.adaEmbed.subscribeEvent('ada:agent:joined', () => {
      window.removeEventListener('spa:navigate', () => {});
    });
    window.adaEmbed.subscribeEvent('ada:end_conversation', (data) => {
      console.log('Ada conversation ended:', data.chatter_id);
    });
  },
};

📋 What the context looks like

The recent_actions string your /context/{user_id} endpoint builds from the live-activity response (Ada reads this as a Variable):

user_id: user_48213
current_page: https://app.example.com/boards/8821034/views/timeline

[1] Page Load: Boards Table View — User landed on the boards table view page
[2] Click Add View — User clicked the "Add view" button on the board toolbar
[3] Click Timeline — User clicked "Timeline" in the Add view panel
[4] Page Load: Boards Timeline View — User landed on the boards timeline view page
[5] Click Set Dates — User clicked "Set dates" button on item "Q2 Feature Launch"
[6] Click Timeline Column — User clicked "Timeline column" on item "Q2 Feature Launch"
[7] Click Automate — User clicked the "⚡ Automate" button on the board toolbar

Wire these in onAdaEmbedLoaded for guaranteed delivery:

Event key	When	Useful for
`ada:end_conversation`	User closes or ends chat	Clear or archive session context on the backend
`ada:agent:joined`	Live agent joins	Stop pushing `setMetaFields` updates (human agent has context)
`ada:agent:left`	Live agent leaves	Resume `setMetaFields` updates
`ada:conversation:message`	New message received	Push a fresh context snapshot via `setMetaFields`
`ada:minimize_chat`	User minimises chat	Pause non-critical context updates

Next: Step 2 — Define proactive triggers (coming soon)Step 2 will cover using Autoplay’s proactive trigger system to automatically open Ada with a targeted greeting when a user performs a high-signal action — for example, surfacing a retention message when recent_actions indicates cancellation intent.

​⚡ Add this skill

One command

Agent onboarding

​✨ Final result

​📋 Prerequisites

​The building blocks

​🔧 Step 1 — Define Variables in Ada

​🌐 Step 2 — Serve context to the Ada SDK

​Install dependencies

​FastAPI context endpoint

​Add the Ada embed script

​Open Ada with live context

​📋 What the context looks like

​📣 Useful Ada events to subscribe to

⚡ Add this skill

✨ Final result

📋 Prerequisites

The building blocks

🔧 Step 1 — Define Variables in Ada

🌐 Step 2 — Serve context to the Ada SDK

Install dependencies

FastAPI context endpoint

Add the Ada embed script

Open Ada with live context

📋 What the context looks like

📣 Useful Ada events to subscribe to