Quick start

Prerequisites: the Appilot widget is embedded on your page with an identified user (sessions are always attributable), and an administrator has created a Session Template in the Backoffice (say role-play-unhappy-customer, with variables role and difficulty and an outcome schema requiring score and summary).

1. Start the session

import { startFocusedSession } from 'appilot';

const session = await startFocusedSession({
  template_id: 'role-play-unhappy-customer',
  variables: {
    role: 'Sam, a customer whose car repair took three weeks',
    difficulty: 'hard',
  },
});

The SDK delegates to the embedded widget, which already holds the credentials, so you pass no API keys or tokens. If the widget is not present the call rejects after a few seconds.

If you load the widget from a script tag without a bundler, install the appilot package anyway and import startFocusedSession from it: the package is the API, and it delegates to whichever surface is present. It is the same package that carries client actions.

2. Let the user work

The conversation happens in the assistant panel as usual. The assistant stays inside the mission: it plays the role, follows the boundaries, and will not drift into general assistance.

3. Receive the outcome

const stop = session.onOutcome((outcome) => {
  // Shape is guaranteed by your template's outcome schema.
  saveEvidence({
    activityId,
    score: outcome.score,
    summary: outcome.summary,
  });
});

The outcome fires once, when the assistant judges the mission's completion criteria met and produces a schema-valid result. Route it through your own review logic before treating it as truth.

4. Or end it yourself

await session.end(); // abandons the session; no outcome will be produced

Sessions also end server-side when the template's turn budget is exhausted.

Errors you may see

Error	Meaning
Session template not found	Wrong template_id, template inactive, or the page domain is not registered for the app
Missing required session variable '...'	A required variable was not supplied
Runtime missions are disabled...	You sent an inline mission on a deployment where only templates are allowed
No Appilot assistant surface available	The widget did not load on this page