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 '@betterknow/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, the same API is available once the widget boots; call it through the shared global registry exactly like registerTool.

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