How to Add an AI Tutor to Moodle

The most common mistake when adding a custom script to Moodle is pasting it into the course content editor. Moodle's editor — TinyMCE or Atto — strips script tags when the page is saved. It is a security feature, not a bug. The script disappears on save and nothing loads. The correct approach bypasses the content editor entirely and uses a site-level setting that is not filtered.

Prerequisites before you start

• Moodle site administrator access: you need to be able to access Site administration. Course editor access is not enough.
• A Kolsense account with an Edu Widget configured: you need an embed script from the Kolsense dashboard. The script includes your widget ID and is specific to your configuration.
• Your allowed domain set in Kolsense admin: the Edu Widget will only activate on the domain you have approved in the Kolsense admin console.

Step-by-step: adding the AI tutor to Moodle

Step 1: Get your embed script from Kolsense

Log into your Kolsense dashboard and navigate to the Edu Widget section. Find the widget you have configured for the course, and copy the embed code. It is a small JavaScript snippet, typically one or two lines. It will look something like:

<script src="https://www.kolsense.ai/edu-widget-loader.js" data-key="your-widget-key"></script>

Step 2: Navigate to Additional HTML in Moodle

In Moodle, go to:

1. Site administration (top-level admin menu)
2. Appearance
3. Additional HTML

You will see three text fields: one for code in the head, one at the start of the body, and one at the end of the body.

Step 3: Paste the script into the End of BODY field

Paste your Kolsense embed script into the field labelled "Within HEAD" or "End of BODY". End of BODY is preferred for JavaScript that controls a widget — it ensures the page content loads before the script runs. Click Save changes.

Step 4: Verify it is loading

Navigate to any course page on your Moodle site in a regular browser tab. The AI tutor widget button should appear on the page. If it does not:

• Check that the script was saved correctly in Additional HTML — edit the field again and confirm the code is still there
• Check that your Kolsense allowed domain matches your Moodle site's domain exactly
• Check the browser console (F12 > Console) for JavaScript errors that might indicate why the script is not running
• Confirm the Edu Widget is set to Live (not Draft) in your Kolsense dashboard

Step 5: Test before going live to students

Before students see the widget, test it thoroughly. Ask the kinds of questions your students will actually ask — including questions that are at the edge of the subject scope, questions the tutor should not answer, and conversational or off-topic questions. Confirm that the tutor handles each case the way you expect. If it gives a wrong answer, update the configuration in your Kolsense dashboard and re-test.

Why the content editor does not work

Moodle's content editors have a built-in HTML sanitiser that removes potentially dangerous HTML, including script tags. This is intentional — it prevents malicious code from being embedded in course pages by instructors or students. It also means that any custom JavaScript you paste into a page via the editor will be removed on save. The Additional HTML section in site administration is the designated location for custom scripts — it is accessible only to site administrators and is not filtered.

What students see

Once the widget is live, students see a small button on the course page. When they click it, the browser asks for microphone permission. After granting permission, they can speak directly to the AI tutor. The conversation happens in the browser — no login, no external app. The widget appears on every page of the Moodle site because Additional HTML is site-wide, so students can access the tutor from any course page.

Limitations specific to Moodle

• Not available in the Moodle app: the mobile app does not load Additional HTML scripts. Students using the Moodle app on a phone will not see the widget. It works only in a browser.
• Site-wide deployment: Additional HTML applies to all pages. If you only want the widget on one course, you need either a custom Moodle plugin or a theme that supports per-course script injection — which requires developer involvement.
• Admin access required: instructors without site admin access cannot add the script themselves. They need to request it from the Moodle administrator.

For instructors using other platforms

The same Additional HTML or custom code injection approach applies to other LMS platforms, though the location of the setting varies. For WordPress-based platforms like LearnDash or Tutor LMS, the script can typically be added via a custom HTML widget in the theme footer or via a "header and footer scripts" plugin. For Teachable, the Pro plan or above is required — the Starter plan does not allow custom code. For platforms that do not allow any custom code injection, the AI tutor cannot be embedded.

For general guidance on what an AI tutor does and how to configure it, see the AI Tutor for Online Courses guide.