How to integrate the Linguineo conversation player into your learning environment

🎓 How to integrate the Linguineo conversation player into your learning environment

Linguineo’s conversational AI player allows learners to practice speaking in real-world scenarios directly from your platform. In this tutorial, we’ll walk you through embedding the player into your LMS or custom learning environment.

🔐 1. Identity provider setup & getting the access token

Important note: In real-world deployments, you must use your own identity provider. You will need to share your JWKS set URL with us at Linguineo. Our team will configure this on our APIs—you cannot do this step yourself. For this tutorial, we’ll demonstrate integration using Linguineo’s Keycloak identity provider for simplicity.

First, authenticate your users and obtain an access token for the player.

Use Linguineo’s Identity Provider (for testing/demo only):

Basic JavaScript login flow:

Add the following button to your html page:

<button id="login">Login with OAuth</button>

Then add the following Javascript script. This code sets the retrieved access token to the element with id linguineo-conversation to your page (which we will add in the following sections):

const clientId = 'moodle';
const authorizationUrl = 'https://keycloak.linguineo.com/auth/realms/moodle/protocol/openid-connect/auth';
const tokenUrl = 'https://keycloak.linguineo.com/auth/realms/moodle/protocol/openid-connect/token';

document.getElementById('login').onclick = () => {
  const authUrl = `${authorizationUrl}?response_type=code&client_id=${clientId}&redirect_uri=${encodeURIComponent(window.location.href)}&scope=openid`;
  window.location.href = authUrl;
};

const params = new URLSearchParams(window.location.search);
if (params.has('code')) {
  const code = params.get('code');
  fetch(tokenUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: window.location.href,
      client_id: clientId,
    }),
  })
  .then(res => res.json())
  .then(data => {
    const accessToken = data.access_token;
    document.getElementById('linguineo-conversation').setAttribute('access-token', accessToken);
  });
}

To test the login with the Linguineo identity provider, you can try with user tester01 and password testing2025

🧩 2. Import the required JavaScript files

To use the linguineo-conversation component, add the following script tags to (typically the bottom of) your page:

<script nomodule src="https://cdn.linguineo.com/linguineo-conversation/1.0.0/conversation-webcomponents-es5.js"></script>
<script type="module" src="https://cdn.linguineo.com/linguineo-conversation/1.0.0/conversation-webcomponents-es2015.js"></script>

In case you prefer to not reference any Linguineo urls, feel free to copy these js and css files to your own environment. You can download them here.

🧱 3. Add the <linguineo-conversation> component to the page

Set up a container for the player and embed the component with your configuration. How to configure the linguineo-conversation component is described in detail here.

<style>
  .linguineo-conversation-container {
    height: 100vh;
    width: 100vw;
  }
</style>

<div class="linguineo-conversation-container">
  <linguineo-conversation
    id="linguineo-conversation"
    access-token=""
    auth-method="bearer"
    bot-name="Bot"
    application="TEST_APP"
    language="fr"
    tutor-language="nl"
    scenario-id="503"
    answer-type="SPEAKING_WITH_INTERMEDIATE_WRITING"
    show-pronunciation-feedback="false"
    show-simple-corrective-feedback="false"
    sound-effects-enabled="false"
    additional-corrective-feedback="false"
    always-wait-for-bot-to-finish-speaking="false"
    enable-contextualized-grammar-corrections="false"
    do-additional-pronunciation-analysis="false"
  ></linguineo-conversation>
</div>

Be sure to dynamically update the access-token via JavaScript after login (see example in first step).

🛎️ 4. Listening for the linguineo:end event

You can listen for when a user finishes a conversation:

window.addEventListener('linguineo:end', (e) => {
  console.log('Conversation finished', e.detail);
  // Handle end-of-conversation logic here
});

🧪 Optional: React & Angular Integration

The Linguineo player integrates smoothly with modern frameworks like React and Angular. You can pass the access-token as a prop (React) or an input (Angular), and attach event listeners such as linguineo:end in your component logic.

For full working examples—including token handling and refresh logic—visit our GitHub repository:
👉 Linguineo Conversation Client Usage Example
It includes complete setups for plain JavaScript, React, and Angular.

✅ Conclusion

You now have a fully working conversational AI component embedded in your LMS! In production, remember to:

Have questions or need help with setup? Contact our technical team—we’re here to support you.