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
- A student taps a lesson in your app or on your website.
- Your server calls
POST /v1/launchwith your key, your id for the student and what to open. - We answer with a launch link. It works once, within five minutes.
- Your app or website opens that link in the player.
- 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.
Ask for a launch link
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
| Field | Required | What it is |
|---|---|---|
userId | Yes | Your 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. |
mode | Yes | library for a lesson from your library, ask for a lesson made from the student’s question or topic. |
lessonId | For library | The Lesson ID, as it appears on your Library page. |
ask | For ask | Optional topic, subject and questionText. With none, the student is asked what they want to learn. |
entitlement | No | The plan’s API name, from your Plans page. Leave it out to keep the student’s current plan. |
context | No | language, depth, difficulty and delivery choose the recording; exam, course, year and level tell the tutor who it is teaching. |
attributes | No | cohort, batch, centre and planCode, for searching and grouping students in the console. |
validTill | No | A date when this student’s plan ends. |
consent | No | dpdpConsentAt (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.
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:
| Code | What to do |
|---|---|
mode_not_allowed | The student’s plan does not allow this mode. Until your plans include the library, library launches answer this. |
lesson_not_available | The Lesson ID is unknown, hidden, or has no approved recording yet. Check the Library page. |
variant_not_available | The lesson has approved recordings, but not in this language, depth, difficulty or delivery. |
lessons_per_day, trial_exhausted | The 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_entitlement | The plan name is not one of yours. Plan names are on your Plans page. |
Every code, with its status, is in the API reference.
The link rules
- Open the whole link exactly as you received it. The one change allowed is adding
?theme=darkbefore 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:
| When | The player | Counts as another lesson? |
|---|---|---|
| The student reloads the player in the tab or WebView that opened the link | Reconnects to the same lesson, paused where the student was | No |
| Your server asks for a new link to a library lesson the student started (its first step reached the board) and has not finished | Carries that lesson on, paused at the last step the student watched, however long ago they left it | No |
The same, but a newer approved recording of the lesson exists, or your context picks another language, depth, difficulty or delivery | Starts the lesson from the beginning | Yes |
| Your server asks for a new link to a library lesson the student finished | Starts the lesson from the beginning | Yes |
| Your server asks for a new Ask link | Starts a new lesson | Yes |
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:
| Rule | Why | Android | iOS |
|---|---|---|---|
| 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:
- Add the website on the console’s Integration page, under Websites allowed to show the player (see Allowed websites).
- 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:
| Type | Comes with | When |
|---|---|---|
lumi.started | sessionId | The lesson has opened. Sent again, with the same sessionId, when the player reloads or the lesson carries on. |
lumi.completed | sessionId, minutes, beats | The student reached the end of the lesson. |
lumi.blocked | reason, and sessionId once a lesson is running | A limit or a plan stopped something (the codes are below). |
lumi.error | error, and sessionId when known | The 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.closed | minutes, beats, and sessionId once a lesson started | The 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.rated | sessionId, scope, value | The 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.resize | height | The 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.
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 withnoopener(the default fortarget="_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.
reason | What happened | Lesson goes on? |
|---|---|---|
doubts_per_day | The student has used today’s questions. | Yes |
topic_question_limit | Enough questions on this topic for now; more after the topic. | Yes |
lessons_per_day | The student has used today’s lessons. | No |
trial_exhausted | The student has used their trial’s lessons. | No |
mode_not_allowed | The student’s plan does not include this kind of lesson. | No |
language_not_entitled | The student’s plan does not include this language. | No |
unknown_entitlement | The student’s plan is not set up. | No, unless it refused one question in a running lesson |
learner_suspended | This student is paused. | No, unless it refused one question in a running lesson |
lessons_paused | Lessons are paused for your institution. | No, unless it refused one question in a running lesson |
lesson_not_available | The lesson is not published for this student. | No |
variant_not_available | The 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. httpsonly, so a page onhttp://localhostcannot 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
| Limit | What happens |
|---|---|
| 6 launches a minute for one student | The seventh is refused with rate_limited and a Retry-After time. |
| 120 link exchanges a minute from one network address | A school lab behind one address shares this. Write to us before a large lab session. |
| 3 open lessons per student | A fourth shows “This lesson is already open in another tab or device”. |
| 120 API requests a minute per key | Refused with rate_limited and a Retry-After time. |
When something goes wrong
| What you see | Most 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 sound | The WebView still needs a tap for sound, or the frame is missing allow="autoplay; fullscreen". |
| A blank frame | We have not switched the website on for frames yet. The console says “Waiting for SketchMind to switch it on”. |
No lumi.* messages arrive | The 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 launch | Your plans do not include the library yet. Write to us to set them up. |