> ## Documentation Index
> Fetch the complete documentation index at: https://docs.realtalkstudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LMS integration

> How to add Real Talk Studio roleplays to your LMS or SCORM course — a guide for instructional designers

## Who this guide is for

This guide is written for **instructional designers** and **L\&D teams** who build courses in tools like Articulate Rise, Cornerstone, Moodle, or Canvas.

You do **not** need to be a developer to embed a roleplay. Most of the work is copy-paste from Real Talk Studio into your course. If you need scores to flow automatically into your LMS gradebook, your **IT or LMS administrator** (or a tool like Zapier) will handle that part — we explain what to ask them for below.

***

## The big picture

Real Talk Studio does not replace your SCORM course. You keep your existing slides, videos, and quizzes. You **add** AI roleplay practice at the points where learners need to apply what they have learned.

| Real Talk Studio handles                          | Your LMS handles                             |
| ------------------------------------------------- | -------------------------------------------- |
| The conversation with the AI avatar               | Who is enrolled on the course                |
| Scoring and skill feedback                        | Module order and completion tracking         |
| Showing feedback to the learner after the session | Certificates, pathways, and official records |

**How it appears in the course:** Real Talk Studio opens **inside** a page in your LMS — like embedding a YouTube video, but interactive. Learners stay in your course; they do not need a separate Real Talk Studio login for embedded sessions.

<Info>
  There is no standalone SCORM file for the roleplay itself. You paste an **embed code** (provided by Real Talk Studio) into an Embed or HTML block in your authoring tool. Enterprise customers can discuss custom SCORM packaging with their account team.
</Info>

***

## Quick start: add a roleplay to your course

<Steps>
  <Step title="Create the roleplay in Real Talk Studio">
    Build your scenario, personas, and skills in your studio as usual. Name skills clearly — they appear in feedback and exports (e.g. “Active listening”, “Handling objections”).
  </Step>

  <Step title="Copy the embed code">
    Open the roleplay in your studio → **Embed Code** tab → choose **LMS / Rise** → copy the iframe code.
  </Step>

  <Step title="Paste into your course">
    In Rise: add an **Embed** block. In other tools: use **Custom HTML** or **iFrame** where available. Paste the code. Set the block height to at least **800px** (900–1000px works well on some themes).
  </Step>

  <Step title="Add a short intro for learners">
    On the slide before the roleplay, tell learners they will need **microphone access** (and camera if your scenario uses video). Link to [Troubleshooting](/it-admin/troubleshooting) if your organisation uses strict corporate networks.
  </Step>

  <Step title="Publish and test">
    Publish the course and complete a test run yourself. Confirm the avatar loads, audio works, and feedback appears at the end.
  </Step>
</Steps>

<Tip>
  In Articulate Rise, use the **Embed** block type — do not paste the URL alone. The full iframe code is required.
</Tip>

***

## Where to place roleplays in a programme

You can embed roleplays anywhere it helps learning:

* **Before training** — diagnostic conversation to see where someone starts
* **After a module** — short practice applying one skill
* **At the end** — summative assessment using the same scenario as the start (to measure improvement)

Align the **skills** you configure in Real Talk Studio with the **learning objectives** on each module. When skill names match your curriculum, reporting and any future automation are much easier.

**Rough timing:** diagnostic or summative roleplays often need **8–15 minutes**. Short practice sessions can be **5–8 minutes** with fewer skills.

***

## Getting results out: two ways

Every session is saved in Real Talk Studio. You choose how to use that data.

### Option 1 — Download a spreadsheet (easiest)

**Best for:** pilots, manager reviews, compliance records, programmes where the LMS does not need live scores.

No technical setup. Anyone with admin access can:

1. Open your studio in the **Real Talk Studio admin portal**
2. Go to **Session history**
3. Filter by date or roleplay
4. Click **Download CSV**

The file includes date, roleplay name, score, skill ratings, session length, and learner email (when available). If your IT team added a learner reference ID (see below), it appears as **External Customer ID**.

You can open the CSV in Excel, share it with stakeholders, or import it into your LMS reporting on a schedule that suits you.

### Option 2 — Automatic delivery (webhook)

**Best for:** updating an LMS gradebook automatically, routing learners to different modules based on scores, or pushing results into another system without manual exports.

A **webhook** is an automatic notification Real Talk Studio sends to a web address when someone finishes a roleplay. That address is usually set up by your IT team or using a no-code tool like **Zapier** or **Make**.

**What you need to do in Real Talk Studio admin:**

1. Open your studio → **Settings**
2. Paste the webhook address your IT team gives you into **Webhook URL**
3. Save

Full technical details (what data is sent, example setups) are in **[Webhook config](/webhook-config)** — share that page with your IT contact.

<Info>
  **You do not need a webhook for most programmes.** CSV export is enough unless you specifically need scores in the LMS the moment a session ends.
</Info>

***

## Linking results to the right learner

If many people use the same embed link, you may want each completion tied to a specific learner in your LMS.

Your **IT or LMS team** can add a learner reference to the embed link when the course launches. In Real Talk Studio this is called **`extCustId`** (external customer ID). It is usually the LMS user ID or enrolment ID — **not** the learner’s email in plain text.

You will see the same reference in:

* The **External Customer ID** column when you download CSV
* Automatic webhook deliveries (if configured)

Ask your IT team: *“Can we pass our LMS learner ID into the Real Talk Studio embed URL as extCustId?”* Details for them are in [Webhook config](/webhook-config).

***

## Who does what

| Task                                         | Instructional designer | IT / LMS admin     |
| -------------------------------------------- | ---------------------- | ------------------ |
| Build roleplay scenarios and skills          | ✓                      |                    |
| Copy embed code into Rise / SCORM            | ✓                      |                    |
| Write learner-facing intro slides            | ✓                      |                    |
| Download CSV for reporting                   | ✓                      |                    |
| Test on corporate network                    | ✓ (with learner)       | ✓ (firewall rules) |
| Add learner ID to embed link                 |                        | ✓                  |
| Set up webhook / Zapier                      |                        | ✓                  |
| Mark SCORM activity “complete” automatically |                        | ✓ (if required)    |
| Map scores to LMS gradebook                  |                        | ✓                  |

Share **[Firewall configuration](/it-admin/firewall-configuration)** with IT if learners on office networks have connection issues.

***

## Platform tips

| Platform                   | Where to paste embed code              |
| -------------------------- | -------------------------------------- |
| **Articulate Rise**        | Embed block (full iframe code)         |
| **Cornerstone / SumTotal** | HTML content object                    |
| **Moodle**                 | Page resource or HTML block            |
| **Canvas**                 | External tool page or iframe in a page |
| **Docebo / TalentLMS**     | Custom content / HTML embed            |

If your LMS must mark the activity **complete** in the gradebook when the roleplay finishes (not just when the learner clicks Continue), that usually requires extra setup by your IT team — see **For your IT team** below.

***

## Checklist before launch

* [ ] Roleplay skills match module learning objectives
* [ ] Embed block is tall enough (800px+)
* [ ] Intro slide mentions microphone (and camera if needed)
* [ ] You completed a full test session in the published course
* [ ] You know whether you are using **CSV export** or asked IT to set up a **webhook**
* [ ] Corporate learners: IT has reviewed [firewall requirements](/it-admin/firewall-configuration) if needed

***

## For your IT team

The sections below are for LMS administrators, developers, or integration partners. Instructional designers can share this page and point them here.

<AccordionGroup>
  <Accordion title="Embed code format and permissions">
    Each roleplay exposes an iframe embed from **Embed Code → LMS / Rise**. The iframe must include microphone and camera permissions:

    ```html theme={null}
    <iframe
      src="https://www.realtalkstudio.com/embed/your-roleplay-slug?studioId=YOUR_STUDIO_ID"
      width="100%"
      height="800"
      frameborder="0"
      allow="camera; microphone; display-capture"
      allowfullscreen
      style="border: none;"
    ></iframe>
    ```

    Optional URL parameters: `primaryColor`, `fontFamily`, `buttonRadius`, `language` / `lang`, `extCustId`, `parentDomain`. Restrict embed domains under **Studio → Security → Allowed domains**. See [Organization & studio permissions](/organization-and-studio-permissions).
  </Accordion>

  <Accordion title="Webhook setup and payload">
    Configure **Webhook URL** in studio Settings. Real Talk Studio POSTs JSON on completion; all fields are nested under `data`. See **[Webhook config](/webhook-config)** for the full payload, field reference, `extCustId` behaviour, and example receivers (Zapier, Node.js, Postgres).

    Webhooks are optional — session data is always available via **Session history → Download CSV**.
  </Accordion>

  <Accordion title="Marking SCORM complete from the embed">
    After feedback loads, the embed notifies the parent frame:

    ```javascript theme={null}
    { status: 'complete' }
    'completed'
    ```

    A SCORM wrapper can listen and set `cmi.core.lesson_status` to `completed`. Validate `event.origin` in production. postMessage signals **completion only** — scores travel via webhook or CSV, not postMessage.

    Some platforms (e.g. Evolve LMS) use MessageChannel; the embed also exposes `window.notifyAssessmentCompleted()`.
  </Accordion>

  <Accordion title="Automated pathways and score comparison">
    Real Talk Studio does not assign LMS pathways directly. To route learners by weak skills, a webhook receiver should store `skillsFeedback` and `extCustId`, apply mapping rules, and write back via the LMS API.

    To compare pre- and post-training scores for the same learner, store the first completion keyed by `extCustId` + `roleplaySlug` and diff when the second arrives. Embedded sessions do not use the in-app “previous score” API — comparison happens in your systems.
  </Accordion>

  <Accordion title="Integration options summary">
    * **Option A (recommended):** iframe inside existing SCORM / Rise — instructional designer pastes embed code.
    * **Option B:** standalone LMS activity with the same iframe — roleplays updatable without republishing SCORM.
    * **Option C:** custom SCORM wrapper around the iframe for strict completion tracking — requires authoring/dev work.

    xAPI and LTI are not standard today; webhooks + `extCustId` are the supported integration path. Enterprise custom integrations available on request.
  </Accordion>
</AccordionGroup>

***

## Related documentation

<CardGroup cols={2}>
  <Card title="Webhook config" icon="webhook" href="/webhook-config">
    For IT: automatic score delivery, learner ID (`extCustId`), and Zapier-style setups.
  </Card>

  <Card title="Firewall configuration" icon="shield-halved" href="/it-admin/firewall-configuration">
    For IT: network requirements on corporate Wi‑Fi.
  </Card>

  <Card title="Troubleshooting" icon="circle-question" href="/it-admin/troubleshooting">
    Microphone, browser, and connection issues inside the course.
  </Card>

  <Card title="Organization & studio permissions" icon="users-gear" href="/organization-and-studio-permissions">
    Studio access, credits, and allowed embed domains.
  </Card>
</CardGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="Do I need to involve IT?">
    Not for a basic embed. If you paste the embed code and download CSV for reporting, you can launch without IT. Involve IT if you need learner IDs on every session, automatic gradebook updates, corporate firewall access, or SCORM completion to fire automatically.
  </Accordion>

  <Accordion title="Do I need a webhook?">
    No. Webhooks are optional. CSV export from **Session history** includes scores, skills, and session details. Use a webhook only when results must flow into another system immediately.
  </Accordion>

  <Accordion title="Is there a SCORM file for the roleplay?">
    Not as a standard download. You embed Real Talk Studio inside your existing SCORM course. Enterprise customers can discuss custom SCORM packaging.
  </Accordion>

  <Accordion title="Can the LMS automatically send learners down different paths based on their score?">
    Not directly from Real Talk Studio. The roleplay shows feedback to the learner inside the embed. To change LMS pathways automatically, IT needs to receive scores (webhook or CSV import) and apply rules in the LMS.
  </Accordion>

  <Accordion title="Will learners see how they improved compared to an earlier attempt?">
    They see full feedback for the session they just completed. Comparing an earlier diagnostic to a final assessment is something you build in reporting — export CSV or ask IT to store webhook history — unless you surface it in a custom LMS page.
  </Accordion>

  <Accordion title="What if someone finishes too quickly to get a score?">
    Very short sessions may be flagged as too short to score. Treat these as incomplete and ask the learner to try again with a fuller conversation.
  </Accordion>
</AccordionGroup>