Skip to main content

Communication with Classwise

Whether you embed Classwise as an iframe or open it in a new tab, you can communicate with it using the window.postMessage API.

Sending a message to Classwise​

To send a message (e.g., to trigger a specific behavior or send data), use:

  • If you're using an iframe
const iframeEl = document.getElementById("classwise-app-iframe");
iframeEl.contentWindow.postMessage(
  {
    message_type: "YOUR_EVENT_TYPE",
    data: {
      /* your data */
    },
  },
  "https://app.classwise.com"
);
  • If you're using a new tab/window
classwiseWindow.postMessage(
  {
    message_type: "YOUR_EVENT_TYPE",
    data: {
      /* your data */
    },
  },
  "https://app.classwise.com"
);

Read more at:

Receiving messages from Classwise​

When Classwise App loads and initializes properly, a message is sent to the host indicating successful connection and readiness to receive further messages.

To receive message and any other messages, host must listen for messages via listener.

function handleMessage(event) {
  // Only accept messages from the trusted Classwise app origin
  if (event.origin !== "https://app.classwise.com") return;

  const dataObj = event.data;

  switch (dataObj.message_type) {
    case "hello":
      // Classwise app has launched and established a communication channel
      break;

    case "waiting_for_mode_selection":
      // Classwise app is ready to receive mode selection
      break;

    case "waiting_for_content":
      // Classwise app is ready to receive quiz content, optionally with a list of students
      break;

    case "quiz_result":
      // Quiz finished; if class was selected, Classwise sends quiz result
      break;

    default:
      // An unexpected message was received; log it for debugging
      console.warn(
        "Unexpected message indicating issue from Classwise:",
        event.data
      );
      break;
  }

  // You can respond to the Classwise app using postMessage from source object directly:
  // https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/source
  // Example:
  // event.source?.postMessage({ message_type: 'your_message_type', data: {...} }, event.origin);
}

window.addEventListener("message", handleMessage);

Communication process between two applications​

Standard Mode (Manual Login)​

Anonymous Mode​

Hello message from Classwise​

{
  "message_type": "hello",
  "data": "Classwise App is ready to receive messages"
}

Choosing the Integration Mode​

Shortly after hello message, Classwise will send another message indicating readiness for mode selection: waiting_for_mode_selection.

Waiting for mode selection message from Classwise​

{
  "message_type": "waiting_for_mode_selection",
  "data": "Classwise is ready to receive integration mode configuration"
}

Mode Selection API Overview​

All mode selection requests use a unified mode_selection message format:

{
  "message_type": "mode_selection",
  "data": {
    "type": "standard", // or "anonymous"
    "token": "jwt_token", // for standard mode with account linking
    // OR
    "partnerUserId": "unique_id" // for anonymous mode
  }
}

This intuitive approach uses clear, descriptive message types that make the integration purpose obvious at first glance.

From now on, Classwise will wait for response from you. You have two integration modes available:

For users who want full access to Classwise features with persistent profiles. You can choose between:

{
  "message_type": "mode_selection",
  "data": {
    "type": "standard",
    "token": "your_jwt_token_here"
  }
}

Manual Login (no account linking)​

{
  "message_type": "mode_selection",
  "data": {
    "type": "standard",
    "token": null
  }

2. Anonymous Mode​

For temporary access without requiring user accounts:

{
  "message_type": "mode_selection",
  "data": {
    "type": "anonymous",
    "partnerUserId": "unique_user_identifier"
  }
}

Implementation Details:

  • Standard Mode Read more
    • Account Linking: Automatic login via JWT token (Recommended)
    • Manual Login: Users log in manually to Classwise
  • Anonymous Mode Read more
    • Temporary sessions without persistent accounts

You can find detailed implementation instructions for each mode in the following sections of the documentation.