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', (exerciseResult) => {
  console.log('Conversation finished', exerciseResult.detail);
  // Handle end-of-conversation logic here
});

The exerciseResult object has the following properties:

percentage: number;
needsManualEvaluation: boolean;
pointsAwarded: number;
durationInMs?: number;
taskResultInfos?: TaskResultInfo[];
purpose: string;
conversationId?: number;
exerciseSessionId?: string;

๐Ÿงช 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.