When you embed an AI Agent/ Space in an iframe, the parent page will receive messages via the postMessage API. To handle these messages securely, ensure that you verify the message origin.

Please note that event naming supports two product names: Napster Spaces and MentorSite, therefore event MENTORSITE_RESULTS is treated equally as NAPSTER_SPACES_RESULTS

Receiving Messages from the Embed

You can listen for messages sent from the Napster Spaces iframe using the window.postMessage API. This allows your application to receive results and transcripts from the embedded assistant.

Example: Handling the `MENTORSITE_RESULTS` / `NAPSTER_SPACES_RESULTS` Event

Below is a sample code snippet that demonstrates how to listen for and handle messages sent from the Napster Spaces iframe:

<script>
  window.addEventListener('message', function(event) {
    // Verify the message is coming from a trusted origin
    if (event.origin !== 'https://mentorsite-embed.ciscape.com') {
      console.warn('Untrusted origin:', event.origin);
      return;
    }

    const messageData = event.data;

    // Results postMessage event
    if (messageData && messageData.type === 'MENTORSITE_RESULTS') {
      console.log('Received data from iframe:', messageData.data);
      // Add your custom handling logic here
    }
    // Transcripts postMessage event
    if (messageData && messageData.type === 'MENTORSITE_TRANSCRIPTS') {
      console.log('Received data from iframe:', messageData.data);
      // Add your custom handling logic here
    }
    // Session Started postMessage event
    if (messageData && messageData.type === 'MENTORSITE_SESSION_STARTED') {
      console.log('Received data from iframe:', messageData.data);
      // Add your custom handling logic here
    }
  });
</script>

Example: Message Data Payload for`MENTORSITE_RESULTS` / `NAPSTER_SPACES_RESULTS` Event

Napster Spaces may return data in the following structure, depending on the source of the embedded content.

📦 Shopify Store Example

[
  {
    "position": 1,
    "title": "Classic Cap Toe Oxford",
    "link": "https://fakestore.myshopify.com/products/classic-cap-toe-oxford",
    "product_link": "https://fakestore.myshopify.com/products/classic-cap-toe-oxford",
    "product_id": "1234567890123",
    "source": "fakestore.myshopify.com",
    "price": "$450.00",
    "extracted_price": 450,
    "thumbnail": "https://cdn.shopify.com/s/files/sample_image.png",
    "rating": 5,
    "reviews": null,
    "delivery": null,
    "extensions": [],
    "relevance_score": "100",
    "handle": "classic-cap-toe-oxford"
  }
]

🌐 Non-Shopify Site/Store Example

[
  {
    "position": 1,
    "title": "Mahatma Gandhi",
    "link": "https://example.org/wiki/mahatma-gandhi",
    "product_link": "https://example.org/wiki/mahatma-gandhi",
    "product_id": 1,
    "source": "example.org",
    "extracted_price": 0,
    "favicon": "",
    "rating": 5,
    "reviews": null,
    "delivery": null,
    "extensions": [],
    "snippet": "Mohandas Karamchand Gandhi was an Indian lawyer and political ethicist known for leading the nonviolent resistance movement..."
  },
  {
    "position": 2,
    "title": "Mahatma Gandhi Quotes",
    "link": "https://example.org/quotes/mahatma-gandhi",
    "product_link": "https://example.org/quotes/mahatma-gandhi",
    "product_id": 2,
    "source": "example.org",
    "extracted_price": 0,
    "favicon": "",
    "rating": 5,
    "reviews": null,
    "delivery": null,
    "extensions": [],
    "snippet": "Quotes and philosophies by Mahatma Gandhi, a prominent figure in India's independence movement..."
  }
]

Message Data for `MENTORSITE_TRANSCRIPTS`/ `NAPSTER_SPACES_TRANSCRIPTS` Event

{
    "action": "completed",
    "type": "message",
    "role": "assistant",
    "response_id": "resp_Bo91dUv4GbCiZsnOohvH8",
    "item_id": "item_Bo91dmwhBww3WpCSkk5NG",
    "content": "Welcome to Napster Spaces! I'm here to guide you through the amazing world of napster spaces.",
    "timestamp": "2025-06-30T13:39:54.626071+00:00"
}

The value of the role can be either user or assistant. If the value is assistant, it represents the transcript from the avatar; if it is user, it represents the transcript from the user.

Message Data for `MENTORSITE_SESSION_STARTED`/ `NAPSTER_SPACES_SESSION_STARTED` Event

{
    "sessionId": "ddabb177-742a-459b-9f75-c4c7d6c00aee"
}

The value of the sessionId is unique per session.

Message Data for `MENTORSITE_TALK_STATES`/ `NAPSTER_SPACES_TALK_STATES` Event

{
    "state": "preparing"
}

preparing – The avatar talk is initialising.
started – The avatar has started speaking.
ended – The avatar stopped speaking.
completed – The talk processing is completed but audio is not ended in this case.
cancelled – The talk was interrupted or manually stopped before completion.

Sending Messages to the Embed iframe

You can communicate with an embedded iframe using the postMessage API. Below are the supported message types for interacting with the Napster Spaces or MentorSite embed.

🔹 Start the experience

To start the experience, use either the NAPSTER_SPACES_START_SESSION or MENTORSITE_START_SESSION event:

const embedIframe = document.querySelector('#napster-spaces-embed');

embedIframe.contentWindow.postMessage({
  type: 'NAPSTER_SPACES_START_SESSION'
}, '*');

✅ Ensure the iframe has the ID napster-spaces-embed as referenced in the querySelector.

🔹 Send a Question to the Embed

To send a question to the embedded assistant, use either the NAPSTER_SPACES_SEND_QUESTION or MENTORSITE_SEND_QUESTION event:

const embedIframe = document.querySelector('#napster-spaces-embed');

embedIframe.contentWindow.postMessage({
  type: 'NAPSTER_SPACES_SEND_QUESTION',
  text: 'What is Napster Spaces?'
}, '*');

🔹 Send a Message to the Embed

To send a message to the embedded assistant, use either the MENTORSITE_SEND_MESSAGE or NAPSTER_SPACES_SEND_MESSAGE event:

const embedIframe = document.querySelector('#napster-spaces-embed');

embedIframe.contentWindow.postMessage({
  type: 'NAPSTER_SPACES_SEND_MESSAGE',
  text: 'What is Napster Spaces?'
  trigger_response: true,
  delay: true
}, '*');

Behavior Notes:

trigger_response: true and delay: false → Assistant interrupts and speaks immediately.
trigger_response: true and delay: true → Assistant waits for current message to finish, then speaks.
trigger_response: false → Message is used to update the assistant's internal context only; no visible or spoken response is triggered.

🔹 Stop the Current Talk

To stop the avatar from speaking mid-conversation, use either the MENTORSITE_STOP_TALK or NAPSTER_SPACES_STOP_TALK event:

embedIframe.contentWindow.postMessage({
  type: 'NAPSTER_SPACES_STOP_TALK'
}, '*');

🔹 Stop the Current Session

To end the current session entirely (the user will need to click “Start” again), use either the MENTORSITE_STOP_SESSION or NAPSTER_SPACES_STOP_SESSION event:

embedIframe.contentWindow.postMessage({
  type: 'NAPSTER_SPACES_STOP_SESSION'
}, '*');

🔹 Hide/Show Avatar

To end the current session entirely (the user will need to click “Start” again), use either the MENTORSITE_HIDE_AVATAR or NAPSTER_SPACES_HIDE_AVATAR event:

embedIframe.contentWindow.postMessage({
  type: 'NAPSTER_SPACES_HIDE_AVATAR',
  hide: true
}, '*');

🔹 Hide/Show Preview

To end the current session entirely (the user will need to click “Start” again), use either the MENTORSITE_HIDE_PREVIEW or NAPSTER_SPACES_HIDE_PREVIEW event::

embedIframe.contentWindow.postMessage({
  type: 'NAPSTER_SPACES_HIDE_PREVIEW',
  hide: true
}, '*');

Supported Message Types

Message Type	Description

Message Type	Description
`NAPSTER_SPACES_START_SESSION` or `MENTORSITE_START_SESSION`	Launches the AI agent session without needing to use the Start button in the UI.
`NAPSTER_SPACES_SEND_QUESTION` or `MENTORSITE_SEND_QUESTION`	Sends a user question to the assistant in the embed.
`NAPSTER_SPACES_STOP_TALK` or `MENTORSITE_STOP_TALK`	Immediately stops the avatar from speaking.
`NAPSTER_SPACES_STOP_SESSION` or `MENTORSITE_STOP_SESSION`	Ends the current AI agent session and requires a restart.
`NAPSTER_SPACES_HIDE_AVATAR` or `MENTORSITE_HIDE_AVATAR`	Hide/Show Avatar
`NAPSTER_SPACES_HIDE_PREVIEW` or `MENTORSITE_HIDE_PREVIEW`	Hide/Show Preview

For more details about how postMessage works, refer to the MDN documentation.

URL Parameters

Following url parameters are supported.

Parameter Name	Description

Parameter Name	Description
`email`	Email of the user accessing the experience, this is useful to collect the user email in analytics
`hidePreview`	If `hidePreview` is `true`, the preview will be hidden.
`hideAvatar`	If `hideAvatar` is `true`, the avatar will be hidden.
`startText`	Customize the start button label, for example `startText=Connect`. The default is `Start`
`loadingText`	Ability to customize avatar loading text label, for example `loadingText=Preparing...`. Default is `Loading…`
`startingText`	Ability to customize avatar starting text label, for example `startingText=Connecting...`. Default is `Starting…`

Napster Spaces postMessage API v0.0.5