← Lumi for institutions GUIDES FOR YOUR TEAM

Integration: embed the tutor in your app or website

Add the tutor to your app or website. One call from your server gets a launch link; the player opens it in a WebView, a frame or a new tab.

Last updated: 18 November 2026

Opening a lesson takes one call from your server and one link in your app or website. This guide walks through both, then what the player tells your page while the lesson runs. Every route is in the API reference.

How a lesson opens

  1. A student taps a lesson in your app or on your website.
  2. Your server calls POST /v1/launch with your key, your id for the student and what to open.
  3. We answer with a launch link. It works once, within five minutes.
  4. Your app or website opens that link in the player.
  5. The player trades the one-time code in the link for the lesson (we call this the exchange), signs the student in for this lesson only, and starts teaching, or carries on a library lesson the student left unfinished (see Coming back to a lesson). You do nothing for this step.

Ask for a new link each time a student opens a lesson, at the moment they tap. Never store links, and never fetch one ahead of time: a link that is opened (even by a link preview or a retry) is used up.

The examples use $LUMI_API for your environment’s API address and $LUMI_KEY for a key with the launch scope. The addresses are on the Overview.

A lesson from your library:

curl -X POST "$LUMI_API/launch" \
  -H "Authorization: Bearer $LUMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "stu_48213", "mode": "library", "lessonId": "concave-mirror-images",
        "entitlement": "school_plan", "context": { "language": "hi-IN" } }'

A lesson made from the student’s own question or topic (an Ask lesson):

curl -X POST "$LUMI_API/launch" \
  -H "Authorization: Bearer $LUMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "stu_48213", "mode": "ask", "ask": { "topic": "Refraction of light" },
        "entitlement": "school_plan" }'

The answer:

{
  "launchUrl": "https://embed-lumi.sketchmind.ai/#launch=…",
  "expiresIn": 300,
  "learner": {
    "entitlement": "school_plan",
    "caps": { "lessonsLeftToday": 4, "doubtsLeftToday": 20 }
  }
}

caps says what the student has left today: lessons they can start, and questions they can ask during lessons. Show it in your app if you like; the player shows it too.

The fields you send

FieldRequiredWhat it is
userIdYesYour id for the student: 1 to 128 letters, digits, dots, underscores, colons or hyphens, starting with a letter or digit. Never an email or phone number.
modeYeslibrary for a lesson from your library, ask for a lesson made from the student’s question or topic.
lessonIdFor libraryThe Lesson ID, as it appears on your Library page.
askFor askOptional topic, subject and questionText. With none, the student is asked what they want to learn.
entitlementNoThe plan’s API name, from your Plans page. Leave it out to keep the student’s current plan.
contextNolanguage, depth, difficulty and delivery choose the recording; exam, course, year and level tell the tutor who it is teaching.
attributesNocohort, batch, centre and planCode, for searching and grouping students in the console.
validTillNoA date when this student’s plan ends.
consentNodpdpConsentAt (when consent was given) and guardianConsent (true or false).

language takes a language name such as English (India), Hinglish or Hindi, a short id (hindi) or a locale tag (hi-IN; hi-Latn for Hinglish). A language we do not teach in your environment is refused with language_unsupported, and the answer lists the ones we do.

No personal data

Never send a name, phone number, email, date of birth, address or image, anywhere in the body. A launch that carries one is refused with pii_not_accepted, and the answer names the field. An id that looks like an email or a phone number is refused with pii_in_id.

When a launch is refused

A refused launch changes nothing: no student is added and no setting is stored. The ones you will meet first:

CodeWhat to do
mode_not_allowedThe student’s plan does not allow this mode. Until your plans include the library, library launches answer this.
lesson_not_availableThe Lesson ID is unknown, hidden, or has no approved recording yet. Check the Library page.
variant_not_availableThe lesson has approved recordings, but not in this language, depth, difficulty or delivery.
lessons_per_day, trial_exhaustedThe student has used today’s lessons (they start again at midnight, India time), or every lesson of their trial (that does not start again). A library lesson the student started and has not finished is never refused with these: it carries on (see Coming back to a lesson).
unknown_entitlementThe plan name is not one of yours. Plan names are on your Plans page.

Every code, with its status, is in the API reference.

  • Open the whole link exactly as you received it. The one change allowed is adding ?theme=dark before the # (see Dark mode).
  • Keep the part after #launch=. That is the one-time code. Browsers never send it to any server, so it stays out of logs, but a router, redirect or deep-link handler that drops the part after # breaks the launch.
  • Open it once, within five minutes. A late open, or a second open anywhere else (another tab, a link preview, a retry), shows “This link has expired”. Ask your server for a new link. Reloading the player in the tab that opened it is fine: it goes back to the same lesson.

Coming back to a lesson

A student can leave a lesson and come back to it later. What the player does:

WhenThe playerCounts as another lesson?
The student reloads the player in the tab or WebView that opened the linkReconnects to the same lesson, paused where the student wasNo
Your server asks for a new link to a library lesson the student started (its first step reached the board) and has not finishedCarries that lesson on, paused at the last step the student watched, however long ago they left itNo
The same, but a newer approved recording of the lesson exists, or your context picks another language, depth, difficulty or deliveryStarts the lesson from the beginningYes
Your server asks for a new link to a library lesson the student finishedStarts the lesson from the beginningYes
Your server asks for a new Ask linkStarts a new lessonYes

You ask for the link exactly as usual; the player decides. A lesson that carries on is never refused with lessons_per_day or trial_exhausted, because it was counted when it started. Every other refusal still applies: a paused student, lessons paused for your institution, or a mode or language the student’s plan does not include.

A reload cannot reconnect after the student pressed Close, or where the browser keeps no data for the page (a private window, or blocked site data). The player then says the link has expired or was already used. Ask your server for a new link: an unfinished library lesson carries on from there.

Open the player

The player works in three places. All three take the same link.

In a new tab or a full page

Open the link as a page of its own. Nothing to set up, and it works in both environments from your first key.

In your app, in a WebView

Native apps show the player in a WebView. Four rules:

RuleWhyAndroidiOS
Let sound play without a tap.The lesson speaks as soon as it starts.Turn on JavaScript and DOM storage, and call setMediaPlaybackRequiresUserGesture(false).Set allowsInlineMediaPlayback = true and an empty mediaTypesRequiringUserActionForPlayback.
Load the whole link.The one-time code rides after #launch=.Pass the link to webView.loadUrl(…) as received.Load it with webView.load(URLRequest(url:)).
Keep the view on screen while the lesson starts.A hidden player waits, on purpose, and carries on when it is shown again.Do not load a lesson in a WebView that is gone or behind another screen.Do not load a lesson in a WKWebView that is hidden or off screen.
Open it inside your app.An outside browser loses the student’s place in your app.Use a WebView, not an Intent to Chrome or a Custom Tab.Use a WKWebView, not SFSafariViewController or openURL.

On your website, in a frame

<iframe
  src="LAUNCH_URL_FROM_YOUR_SERVER"
  allow="autoplay; fullscreen"
  style="border: 0; width: 100%; height: 640px"
  title="Lesson"></iframe>

allow="autoplay; fullscreen" lets the lesson speak and the student go full-screen. The player never asks for the microphone.

A page may show the player in a frame only once two things are done:

  1. Add the website on the console’s Integration page, under Websites allowed to show the player (see Allowed websites).
  2. Write to us at support@sketchmind.ai so we switch that website on at our end. The console shows “Waiting for SketchMind to switch it on” until we have, then “Shows in a frame”.

Until then, the browser refuses to draw the frame. The same link still works opened in a new tab or full page.

The helper script (optional)

If you would rather not build the frame yourself, our helper script makes it and passes the player’s events to you:

<div id="lesson"></div>
<script src="https://embed-lumi.sketchmind.ai/sdk.js"></script>
<script>
  const player = LumiEmbed.mount({
    container: "#lesson",
    launchUrl: launchUrlFromYourServer,
    theme: "light",          // or "dark"
    height: "auto",          // follows the lesson's height; or a fixed "640px"
    onEvent: (event) => console.log(event.type, event),
  });
  // player.close() removes the frame. It is also removed when the student presses Close.
</script>

In the sandbox, load it from https://embed-lumi-staging.sketchmind.ai/sdk.js. The script needs no key and must never be given one.

Dark mode

The player is light unless the link says ?theme=dark. Put it after the address and before #launch=, never at the end, where it would break the one-time code:

https://embed-lumi.sketchmind.ai/?theme=dark#launch=…

Only the exact word dark works; anything else, or nothing, is light. The player does not follow the phone’s setting and does not remember a choice, so send dark whenever your app is in dark mode. Add it with a URL builder, never by joining text:

// Web or Node: the theme lands before #launch=…, which stays untouched
const url = new URL(launchUrl);
url.searchParams.set("theme", "dark");
frame.src = url.toString();
// Kotlin: Uri.Builder keeps the #launch=… part as it is
val url = Uri.parse(launchUrl).buildUpon()
    .appendQueryParameter("theme", "dark")
    .build().toString()
webView.loadUrl(url)
// Swift: URLComponents keeps the #launch=… part as it is
var parts = URLComponents(string: launchUrl)!
parts.queryItems = (parts.queryItems ?? []) + [URLQueryItem(name: "theme", value: "dark")]
webView.load(URLRequest(url: parts.url!))

The theme is read when the player page loads.

What the player sends back

While a lesson runs, the player posts short messages to the page that shows it, with the browser’s postMessage. Every message has source: "lumi" and a type:

TypeComes withWhen
lumi.startedsessionIdThe lesson has opened. Sent again, with the same sessionId, when the player reloads or the lesson carries on.
lumi.completedsessionId, minutes, beatsThe student reached the end of the lesson.
lumi.blockedreason, and sessionId once a lesson is runningA limit or a plan stopped something (the codes are below).
lumi.errorerror, and sessionId when knownThe lesson could not open, or stopped, for a reason that is not a limit. error is a short code such as launch_expired or network.
lumi.closedminutes, beats, and sessionId once a lesson startedThe student closed or left the player (Close, Leave, or Go back on a notice), or your page opened a new launch link in the same player.
lumi.ratedsessionId, scope, valueThe student rated something, or changed a rating: the lesson (scope session, value 1 to 5), an answer to their question (doubt: resolved, partial or unresolved), or one step of the board (beat: helpful or unclear). Never the student’s words.
lumi.resizeheightThe player’s content height changed, in pixels. Use it to size a frame to its content.

sessionId is our id for that one lesson; it matches sessionId in the session.completed webhook. beats is how many steps of the board the student saw.

One lesson can send these messages more than once. A lesson keeps its sessionId when the player reloads or the lesson carries on (see Coming back to a lesson), and each sitting sends its own lumi.started, and lumi.completed or lumi.closed, with that same sessionId. Count a lesson once per sessionId, never once per message: a sessionId you have seen before is the same lesson, not a new one.

minutes in these messages covers this sitting only, counted from its lumi.started. For the whole lesson, use minutes in the session.completed webhook.

Minutes run a little longer

Before each spoken line, the board waits 0.9 seconds so it can follow the tutor’s voice. This makes a lesson about 3% longer on average (6 to 38 seconds a lesson when we measured it), so minutes, here and in the session.completed webhook, read a little higher than the same lesson did before. The number of lessons does not change.

Listen for them like this, checking the sender’s address first:

const PLAYER = "https://embed-lumi.sketchmind.ai"; // the player address for your environment

window.addEventListener("message", (event) => {
  if (event.origin !== PLAYER) return;
  const message = event.data;
  if (!message || message.source !== "lumi") return;

  if (message.type === "lumi.completed") markLessonDone(message.sessionId); // may repeat: key on sessionId
  if (message.type === "lumi.blocked") showYourOwnNotice(message.reason);
  if (message.type === "lumi.closed") goBackToYourScreen();
});

Where the messages go

  • In a frame, they go to the page that holds the frame. Once your allowed list has websites on it, only those pages get them.
  • In a new tab your page opened with window.open, they go to the page that opened it. A link opened with noopener (the default for target="_blank") has no opener, so nothing is sent.
  • In a WebView, or any page with no frame around it and no opener, nothing is sent. Native apps should rely on webhooks (session.completed, session.blocked) for what happened.

Two moments send nothing: closing the tab or the WebView itself (only the player’s own buttons send lumi.closed), and a student opening a lesson they already have open in three other tabs or devices (the player says “This lesson is already open in another tab or device”).

The codes in lumi.blocked

The student always sees a plain card explaining what happened; the code is for your page. Some limits stop only a question, and the lesson carries on: a lumi.blocked that comes with a sessionId during a lesson means one question was refused.

reasonWhat happenedLesson goes on?
doubts_per_dayThe student has used today’s questions.Yes
topic_question_limitEnough questions on this topic for now; more after the topic.Yes
lessons_per_dayThe student has used today’s lessons.No
trial_exhaustedThe student has used their trial’s lessons.No
mode_not_allowedThe student’s plan does not include this kind of lesson.No
language_not_entitledThe student’s plan does not include this language.No
unknown_entitlementThe student’s plan is not set up.No, unless it refused one question in a running lesson
learner_suspendedThis student is paused.No, unless it refused one question in a running lesson
lessons_pausedLessons are paused for your institution.No, unless it refused one question in a running lesson
lesson_not_availableThe lesson is not published for this student.No
variant_not_availableThe lesson is not ready in this language or level.No

Allowed websites

The list on the console’s Integration page, Websites allowed to show the player, does two jobs: it names the pages we may switch on for frames, and once it has websites on it, the player sends its messages only to those pages.

  • Write each website as https:// and the host only, one per line: https://learn.yourschool.in. No path and no slash at the end.
  • https only, so a page on http://localhost cannot be listed. Test frames with the sandbox player from a real https page, or open the link in a new tab while you build.
  • At most 20 websites per environment. Owners and admins edit the list; removing one asks for a reason, which goes into Activity.
  • Apps need nothing here. The list is only for web pages that show the player in a frame.

Limits that protect your students

LimitWhat happens
6 launches a minute for one studentThe seventh is refused with rate_limited and a Retry-After time.
120 link exchanges a minute from one network addressA school lab behind one address shares this. Write to us before a large lab session.
3 open lessons per studentA fourth shows “This lesson is already open in another tab or device”.
120 API requests a minute per keyRefused with rate_limited and a Retry-After time.

When something goes wrong

What you seeMost likely cause
“This link has expired” or “This link was already used”The link was opened twice (a link preview, a retry in a new tab or WebView, a router loading the page two times), opened more than five minutes after you asked for it, or its code was changed on the way. A reload after Close, or in a private window, shows it too. Ask at the moment the student taps, and open the link once. A reload of the tab that opened it reconnects instead (see Coming back to a lesson).
“No lesson to open”The part after #launch= was dropped on the way.
The lesson plays with no soundThe WebView still needs a tap for sound, or the frame is missing allow="autoplay; fullscreen".
A blank frameWe have not switched the website on for frames yet. The console says “Waiting for SketchMind to switch it on”.
No lumi.* messages arriveThe page is not on your allowed list, the player is in a WebView or a tab with no opener, or your listener checks a different player address.
mode_not_allowed on every library launchYour plans do not include the library yet. Write to us to set them up.