Yoodli Web Embed API

Overview

The Web Embed API lets you embed Yoodli practice activities in your application and receive events when users complete sessions. Communication uses the standard HTML5 postMessage API for secure cross-origin messaging.

Use this when: You want to embed Yoodli activities directly in your UI and track scoring and activity completion.

See also: Web Embed Support Article

Using the postMessage API

1. Set up the iframe embed

Follow the Web Embed Support Article for complete iframe setup instructions, including required attributes and permissions.

2. Listen for events

window.addEventListener('message', (event) => {
  // Security: verify origin in production
  if (event.origin !== 'https://app.yoodli.ai') {
    return;
  }

  const message = event.data;

  switch (message.messageType) {
    case 'score_complete':
      handleScoreComplete(message.data);
      break;
    case 'activity_done':
      handleActivityDone(message.data);
      break;
  }
});

Message Format

All messages follow this structure:

interface YoodliMessage {
  messageType: string;  // Event type identifier
  data: any;           // Event-specific payload
  messageId?: string;  // Optional unique message ID
  version: string;     // API version (e.g., "1.0.0")
}

Events

`score_complete`

Fired when a user completes a practice session and receives a score.

interface ScoreCompleteData {
  score: number;             // Raw score (0-100)
  roleplayId: string;        // Unique roleplay identifier
  recordingId: string;       // Unique recording identifier
  recordingDuration: number; // Duration in seconds
  completedAt: string;       // ISO 8601 timestamp
}

Example payload:

{
  "messageType": "score_complete",
  "version": "1.0.0",
  "data": {
    "score": 87,
    "roleplayId": "rp_abc123",
    "recordingId": "rec_xyz789",
    "recordingDuration": 245,
    "completedAt": "2025-01-23T10:30:00Z"
  }
}

Use this to: Update progress tracking, unlock next activities, or show completion UI.

`activity_done`

Fired when a user exits or completes their activity session.