Embed SCL

SCL is normally displayed in an iframe inside a learning or business platform. The parent chooses the role-play, supplies the learner identity, and grants microphone access; SCL owns the briefing, voice practice, transcript, and feedback journey.

Launch URL

Parameter	Required	Purpose
`rolePlayId`	Yes	Identifies the active exercise to load
`demoMode`	No	Uses mock feedback; it is a demo switch, not an authorization control


https://<scl-host>/?rolePlayId=<role-play-id>

The identifier is trimmed and must not be empty. An unknown or inactive role-play is not available to the learner.

Iframe requirements

The parent page and SCL must use HTTPS. Grant microphone permission explicitly:


<iframe
  src="https://<scl-host>/?rolePlayId=<role-play-id>"
  allow="microphone"
  title="Syntphony Conversational Learning"
></iframe>

The browser and network must also permit the configured HTTPS APIs, SCAI WebSocket signalling, and WebRTC media path.

Token handshake

SCL and the parent exchange postMessage events:

Direction	Event type	Payload	Purpose
SCL to parent	`syntphony_V2V_client_ready`	none	Announces that SCL can receive the initial token
Parent to SCL	`syntphony_V2V_token_submitted`	`{ token }`	Supplies the learner bearer token
SCL to parent	`syntphony_V2V_token_refresh_request`	`{ token }`	Requests a replacement for an expired token
Parent to SCL	`syntphony_V2V_token_refreshed`	`{ token }`	Returns the refreshed token

The parent should wait for the ready event before sending the token and answer refresh requests within ten seconds.


const sclOrigin = 'https://<scl-host>';
const frame = document.querySelector('#scl-frame');
 
window.addEventListener('message', async (event) => {
  if (event.origin !== sclOrigin || event.source !== frame.contentWindow) return;
 
  if (event.data?.type === 'syntphony_V2V_client_ready') {
    frame.contentWindow.postMessage(
      { type: 'syntphony_V2V_token_submitted', token: await getLearnerToken() },
      sclOrigin
    );
  }
 
  if (event.data?.type === 'syntphony_V2V_token_refresh_request') {
    frame.contentWindow.postMessage(
      { type: 'syntphony_V2V_token_refreshed', token: await refreshLearnerToken() },
      sclOrigin
    );
  }
});

Host responsibilities

Launch only role-plays the learner is allowed to access.
Validate event.origin and event.source for every message.
Supply and refresh a bearer token with the claims required by downstream integrations.
Grant microphone permission and provide a supported network path.
Define learner consent and support messaging before the iframe opens.
Decide how the host confirms completion. SCL does not currently send a parent-facing “finished” message; configured completion is reported through the backend Learning Platform Integration.

Standalone access

Outside an iframe, SCL shows a manual bearer-token form. This supports development and integration testing only and should not be presented as a learner login.