Skip to content

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.

  • 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.

  1. Open the slide in the slide editor.
  2. In the Activity box, select Change.
  3. In the Activity and destination dialog, set Interface to SlideMind widget and Destination to HTML Widget (iframe).
  4. Select Done.

The last step of the slide editor is now called Add it to your web 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:

  1. Copy the iframe with Copy the code. If the slide has unsaved changes, the button reads Save & copy the code.
  2. Paste it into an HTML or embed block of your page, LMS or course.
  3. 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.

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.

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.

ParameterWhat it doesAllowed valuesProduct default
modeThe activity the widget shows. Set by the generated code.qa, chat, captureThe slide’s activity type
themeLight or dark theme.light, darklight
colorPrimary color: header, learner bubbles and send button.# and six hexadecimal digits, for example %230f766e#4f46e5
ai_colorAssistant bubble color.Same as colorFollows the theme
ai_text_colorAssistant text color.Same as colorFollows the theme
radiusBubble radius, in pixels.Whole number from 0 to 2412
headerShows or hides the header.1 (show), 0 (hide)Shown
titleTitle in the header.1 to 200 charactersThe slide title
questionText 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 charactersEmpty
sm_userThe learner’s identifier. See Identify the learner.1 to 255 charactersNone
scopeMemory scope of an embedded capture.global, course, module, slideslide

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>

For each appearance setting, the widget uses the first value it finds, in this order:

  1. A parameter in the iframe address.
  2. The slide’s appearance, set in its Look step.
  3. The workspace defaults, in Settings › Integrations › HTML Widget defaults.
  4. 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.

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:

  1. sm_user.
  2. An xAPI actor launch parameter, if it is in the widget address.
  3. user_id, then learner_id, then student_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.

These pages replace the widget when it cannot start. They are always in English.

MessageLikely causeWhat 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 frameThe 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):

MessageLikely causeWhat 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.

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.

Message typeWhenOther fields
sm:readyThe widget has loaded.mode; learnerDetected (true or false); layout (the Q&A layout name, or null)
sm:completeOnce 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:resultAfter 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:resultIn answer to sm:capture.success; saved (the number of values saved); error (a short code); requestId (copied from your message)
Message typeWhat it doesFields
sm:listenSubscribes your page to sm:result. Send it from the page that directly contains the iframe, after sm:ready.None
sm:captureSaves 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.

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 the invalid_request error. If the message contains any other key, nothing is saved and the answer carries the variable_not_configured error.
  • scope (optional): global, course, module or slide. Without it, the widget uses the scope of 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. A course or module scope needs the slide to be attached to a course or module, otherwise the answer carries the invalid_scope error.
  • learnerUid (optional): the learner’s identifier. Without it, the widget uses the learner it detected (sm_user in its address). With neither, nothing is saved and the answer carries the no_learner_uid error.

The widget answers with sm:capture:result. Check success before you move on. See Saving values.