HTML widget (iframe)
The HTML widget shows a slide in an <iframe> that you paste into a web page, a page of your LMS or an HTML block of a course. This page covers the generated iframe, the URL parameters, how to identify learners and the messages learners may see. The last section is for developers who build their own logic around the iframe.
When to use it
Section titled “When to use it”- Your page, LMS or tool accepts HTML or an embed block, and you want SlideMind to provide the screen: a ready-made Q&A or Chat panel.
- You want the widget’s features: appearance, Q&A layouts, AI notice and Learner language. See What learners see.
- For a course built in Rise 360 or Storyline, prefer their own destinations (Articulate Rise 360, Articulate Storyline (Web Object)). They read the learner from the published course for you, which the HTML widget cannot do. See Identify the learner.
In a Chat, the widget answers in plain text: return fields do not apply. In a Q&A, the widget can show a score and a verdict. See Results: plain text or structured.
Choose the HTML widget
Section titled “Choose the HTML widget”- Open the slide in the slide editor.
- In the Activity box, select Change.
- In the Activity and destination dialog, set Interface to SlideMind widget and Destination to HTML Widget (iframe).
- Select Done.
The last step of the slide editor is now called Add it to your web page.
Add the widget to your page
Section titled “Add the widget to your page”Before you start, publish the slide (“Your course gets no answer from a draft”) and add the site that will show the widget to Settings › Integrations › Allowed origins, unless the list is empty. See Allowed websites.
The Installation step shows these steps:
- Copy the iframe with Copy the code. If the slide has unsaved changes, the button reads Save & copy the code.
- Paste it into an HTML or embed block of your page, LMS or course.
- Open the page to try it: learners use the activity right there.
The generated code looks like this:
<!-- === SlideMind HTML Widget: Coaching feedback === --><iframe src="https://api.slidemind.app/widget/abc123?mode=qa" width="100%" height="480" frameborder="0" title="Coaching feedback" allow="clipboard-write"></iframe>The widget fills the frame. Change height (in pixels) or width to fit your page.
What updates without copying again
Section titled “What updates without copying again”The widget address holds only the slide’s ID and mode (plus scope for a capture). Everything else comes from SlideMind: the instructions at every message, and the slide’s Look step (appearance, Q&A layout, labels, AI notice, Learner language), the opening message and the Chat turn limit each time the widget loads. Learners get your changes the next time the widget loads.
Copy the iframe again only when you change the activity type (or, for an embedded capture, its scope). See Changing a slide after installation.
URL parameters
Section titled “URL parameters”You can add parameters to the src address of the iframe to change one embed without touching the slide. Separate them with &, and URL-encode the values: write # as %23 and a space as %20.
| Parameter | What it does | Allowed values | Product default |
|---|---|---|---|
mode | The activity the widget shows. Set by the generated code. | qa, chat, capture | The slide’s activity type |
theme | Light or dark theme. | light, dark | light |
color | Primary color: header, learner bubbles and send button. | # and six hexadecimal digits, for example %230f766e | #4f46e5 |
ai_color | Assistant bubble color. | Same as color | Follows the theme |
ai_text_color | Assistant text color. | Same as color | Follows the theme |
radius | Bubble radius, in pixels. | Whole number from 0 to 24 | 12 |
header | Shows or hides the header. | 1 (show), 0 (hide) | Shown |
title | Title in the header. | 1 to 200 characters | The slide title |
question | Text already typed in the learner’s answer or message box when the widget opens. The learner can edit it before sending. | 1 to 2,000 characters | Empty |
sm_user | The learner’s identifier. See Identify the learner. | 1 to 255 characters | None |
scope | Memory scope of an embedded capture. | global, course, module, slide | slide |
A value that is not allowed is ignored: the widget falls back to the next level below, and never shows an error for it.
Example: a dark Chat without a header, for one identified learner.
<iframe src="https://api.slidemind.app/widget/abc123?mode=chat&theme=dark&header=0&sm_user=learner-4821" width="100%" height="480" frameborder="0" title="Coaching feedback" allow="clipboard-write"></iframe>Which value wins
Section titled “Which value wins”For each appearance setting, the widget uses the first value it finds, in this order:
- A parameter in the iframe address.
- The slide’s appearance, set in its Look step.
- The workspace defaults, in Settings › Integrations › HTML Widget defaults.
- The product defaults in the table above.
The Learner language is not a URL parameter: set it on the slide or in the workspace defaults. It changes the buttons, labels and messages of the widget. The AI answers in the language of your instructions. See Appearance and language.
Identify the learner
Section titled “Identify the learner”Learner memory works only for an identified learner. Without one, the activity works normally, but nothing is remembered and memory placeholders use their fallback text.
Inside the iframe, the widget runs on SlideMind’s address (api.slidemind.app), not on your site’s. The browser does not let it read the LMS session of the page around it, so it cannot use SCORM, and it cannot resolve a cmi5 launch either. It looks for the learner only in its own address, in this order:
sm_user.- An xAPI
actorlaunch parameter, if it is in the widget address. user_id, thenlearner_id, thenstudent_id.
In practice, add sm_user to the iframe address with the ID of the person viewing the page. Use what your LMS or site offers to insert the current user’s ID into the page, or build the address on your server.
The identifier is visible in the page’s source. Prefer an internal LMS ID to an e-mail address. See Identifying learners for the full rules.
Messages learners may see
Section titled “Messages learners may see”These pages replace the widget when it cannot start. They are always in English.
| Message | Likely cause | What to do |
|---|---|---|
| ”Configuration not found.” | The slide is a draft or archived, it was deleted, or the address is wrong. | Publish the slide, or copy the iframe again from the right slide. |
| ”This widget is not available.” | The workspace that owns the slide is not active. | Check the workspace. See Delete or restore a workspace. |
| ”The assistant is loading. One moment, please.” | Many learners are opening the widget at once. | Nothing: the page reloads by itself after a few seconds. |
| No SlideMind message: the browser refuses to show the frame | The site that shows the widget is not in Allowed origins. | Add the site. See Allowed websites. |
These messages appear inside the widget, in its Learner language (English shown here):
| Message | Likely cause | What to do |
|---|---|---|
| ”The AI assistant is temporarily unavailable. Please try again later or contact your course provider.” | The workspace cannot reach the AI: SlideMind Credits used up, monthly usage limit reached, no AI connected, model not available on the plan, or workspace not active. | Check the Overview dashboard and Choosing how AI is funded. |
| ”Too many requests right now. Please try again in a moment.” | SlideMind stayed busy after the widget’s automatic retries. | Wait a moment, then send again. |
| ”Network error. Please try again.” | The learner’s connection failed. | Send again. |
| ”Something went wrong. Please try again.” | Any other error. | Check Activity and analytics. |
| ”Assessment unavailable” (Q&A, in place of the verdict) | The AI returned no usable score or verdict. | See Results: plain text or structured. |
See also Troubleshooting.
Advanced: messages for developers
Section titled “Advanced: messages for developers”This section is for developers who build logic around the iframe, for example to unlock a Next button when the activity ends. The widget talks to the page that contains it with window.postMessage. Its messages never include the learner’s identifier.
Messages the widget sends
Section titled “Messages the widget sends”Message type | When | Other fields |
|---|---|---|
sm:ready | The widget has loaded. | mode; learnerDetected (true or false); layout (the Q&A layout name, or null) |
sm:complete | Once per load, when the activity is finished: in a Q&A, when the feedback is shown (including “Assessment unavailable”); in a Chat, when the turn limit is reached, or after the first reply when there is no limit. | mode |
sm:result | After each result the learner sees, only once your page has sent sm:listen. | mode; reply (the text shown); in a Q&A, verdict (pass, partial, fail or null); fields (the structured result, or null); missing (the missing field names, or null); in a Chat, turns (the learner turns that got a reply) and max_turns (the turn limit, 0 without a limit). A Chat also sends one sm:result right after sm:listen, so your page knows the limit before the first reply. |
sm:capture:result | In answer to sm:capture. | success; saved (the number of values saved); error (a short code); requestId (copied from your message) |
Messages your page can send
Section titled “Messages your page can send”Message type | What it does | Fields |
|---|---|---|
sm:listen | Subscribes your page to sm:result. Send it from the page that directly contains the iframe, after sm:ready. | None |
sm:capture | Saves values in the learner’s memory (capture mode only). See Embedded capture. | variables; optional scope, learnerUid, requestId |
The widget accepts sm:listen and sm:capture only from a site listed in Allowed origins (any site when the list is empty). In your own listener, check that a message comes from the iframe and from the widget’s origin, https://api.slidemind.app:
var frame = document.getElementById("sm-widget");var widgetOrigin = "https://api.slidemind.app";
window.addEventListener("message", function (event) { if (event.source !== frame.contentWindow || event.origin !== widgetOrigin) return; var data = event.data || {}; if (data.type === "sm:ready") { frame.contentWindow.postMessage({ type: "sm:listen" }, widgetOrigin); } else if (data.type === "sm:result") { console.log(data.reply, data.verdict, data.fields); } else if (data.type === "sm:complete") { document.getElementById("next-button").disabled = false; }});This example assumes you added id="sm-widget" to the iframe.
Embedded capture
Section titled “Embedded capture”A Memory capture slide can also use the widget: in Activity and destination, set Integration method to Embedded capture and Destination to HTML Widget (iframe). The generated iframe carries mode=capture and a default scope (the one chosen under Capture scope, when the Installation step shows that field).
In this mode the widget shows nothing to the learner and makes no AI call. It waits for your page to send the values, so it needs a developer, and the Installation step shows no setup steps for it.
frame.contentWindow.postMessage({ type: "sm:capture", variables: { first_name: "Alex" }, requestId: "intro-1"}, "https://api.slidemind.app");variables: the values to save, as text, under the memory keys this slide saves (its Values to remember). A number or a boolean is refused with theinvalid_requesterror. If the message contains any other key, nothing is saved and the answer carries thevariable_not_configurederror.scope(optional):global,course,moduleorslide. Without it, the widget uses thescopeof its address. Send the scope set for each value in the slide’s Values to remember step, with one message per scope when they differ. Acourseormodulescope needs the slide to be attached to a course or module, otherwise the answer carries theinvalid_scopeerror.learnerUid(optional): the learner’s identifier. Without it, the widget uses the learner it detected (sm_userin its address). With neither, nothing is saved and the answer carries theno_learner_uiderror.
The widget answers with sm:capture:result. Check success before you move on. See Saving values.