---
title: "Using postMessage with the Lab Client (iframe Integration)"
slug: "using-postmessage-with-the-lab-client-iframe-integration"
updated: 2025-08-28T21:44:00Z
published: 2025-08-28T21:44:00Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skillable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using postMessage with the Lab Client (iframe Integration)

## Overview

This article documents the Lab Client API endpoints used for `postMessage` (iframe integration). For each endpoint, you'll find:

- **Event ID**: Identifies the event associated with the message.
- **Description**: Explains the endpoint’s behavior and context.
- **Request parameters**: Lists the required fields to include in the message payload.
- **Response**: Describes the structure and content of the message returned.
- **Example:**Provides a sample request to demonstrate usage.

### General Notes

- All requests must include the correct `event_id`.
- Responses (when present) will have a corresponding `event_name` or `event_Id`.
- For events like connection status, variable changes, or activity completion, listen for messages with the appropriate `event_name`.
- Always validate message origins and data for security.

---

## Endpoints

### getEnvironmentConnectionStatus

**Request Event ID**: `getEnvironmentConnectionStatus`

**Description**: Returns the current connection status of the lab environment (e.g., VM connection state). The response includes environment type, machine ID, status, and error information (if present).

#### Request Parameters

| Name | Type | Required? | Default Value | Description |
| --- | --- | --- | --- | --- |
| `event_id` | string | Yes | — | Must be `getEnvironmentConnectionStatus` |
| `version` | number | No | `1` | API version |

#### Response

| Name | Type | Value |
| --- | --- | --- |
| `event_name` | string | Always `environment_connection_status` |
| `environment_type` | string | `none` or `machine` |
| `environment_type_code` | number | `0` or `1` |
| `machine_id` | string or null | Machine identifier, if present |
| `status` | string | `connected` or `disconnected` |
| `status_code` | number | `0` or `1` |
| `error` | string or null | Error message, if applicable |

#### Example

```javascript
labClientWindow.postMessage({ event_id: 'getEnvironmentConnectionStatus' }, '*');
// Listen for response with event_name: 'environment_connection_status'
```

---

### getEnvironmentLatency

**Request Event ID:**`getEnvironmentLatency`

**Description:**Returns the current latency, in milliseconds (ms), between the lab client and the selected VM.

#### Request Parameters

| Name | Type | Required? | Default Value | Description |
| --- | --- | --- | --- | --- |
| `event_id` | string | Yes | — | Must be `getEnvironmentLatency` |
| `version` | number | No | `1` | API version |

#### Response

| Name | Type | Value |
| --- | --- | --- |
| `event_Id` | string | Always `environment_latency` |
| `latency` | number | Latency in ms |

#### Example

```javascript
labClientWindow.postMessage({ event_id: 'getEnvironmentLatency' }, '*');
// Listen for response with event_Id: 'environment_latency'
```

---

### sendTextToEnvironment

**Event ID:**`sendTextToEnvironment`

**Description:**Sends the provided text (typed or pasted) to the active VM console. Use this event ID with a `text` parameter to automate commands or credential entry.

> [!NOTE]
> Response
> 
> This event does not return a response.

#### Request Parameters

| Name | Type | Required? | Default Value | Description |
| --- | --- | --- | --- | --- |
| `event_id` | string | Yes | — | Must be `sendTextToEnvironment` |
| `text` | string | Yes | — | Text to send to the active VM console (typically used for commands, credentials, or other input) |
| `version` | number | No | `1` | API version |

#### Response

None (action only)

#### Example

```javascript
labClientWindow.postMessage({ event_id: 'sendTextToEnvironment', text: 'ls -la' }, '*');
```

---

### getLabToken

**Event ID:**`getLabToken`

**Description:**Retrieves the value of a named lab token. Use this event ID with a `name` parameter to request the token, and the response will include its value.

#### Request Parameters

| Name | Type | Required? | Default Value | Description |
| --- | --- | --- | --- | --- |
| `event_id` | string | Yes | — | Must be `getLabToken` |
| `name` | string | Yes | — | The name of the lab token to retrieve |
| `version` | number | No | `1` | API version |

#### Response

| Name | Type | Value |
| --- | --- | --- |
| `event_Id` | string | Always `lab_token ` |
| `value` | string or null | The value of the requested lab token, returned as a string |

#### Example

```javascript
labClientWindow.postMessage({ event_id: 'getLabToken', name: 'LabProfile.Name' }, '*');
// Listen for response with event_Id: 'lab_token'
```

---

### getLabVariable

**Event ID:**`getLabVariable`

**Description:**Retrieves the value of a specified lab variable by sending a message with this event ID and a `name` parameter. The response includes the variable’s value.

#### Request Parameters

| Name | Type | Required? | Default Value | Description |
| --- | --- | --- | --- | --- |
| `event_id` | string | Yes | — | Must be `getLabVariable` |
| `name` | string | Yes | — | The name of the lab variable to retrieve |
| `version` | number | No | `1` | API version |

#### Response

| Name | Type | Value |
| --- | --- | --- |
| `event_Id` | string | Always `lab_variable` |
| `value` | string or null | The value of the requested lab variable, returned as a string |

#### Example

```javascript
labClientWindow.postMessage({ event_id: 'getLabVariable', name: 'myVariable' }, '*');
// Listen for response with event_Id: 'lab_variable'
```

### sendLabNotification

**Event ID:**`sendLabNotification`

**Description:**Displays a notification (toast) in the lab client UI by sending a message with this event ID and a notification parameter.

> [!NOTE]
> Response
> 
> This event does not return a response.

#### Request Parameters

| Name | Type | Required? | Default Value | Description |
| --- | --- | --- | --- | --- |
| `event_id` | string | Yes | — | Must be `sendLabNotification` |
| `notification` | string | Yes | — | A string containing the message to display in the lab client UI |
| `version` | number | No | `1` | API version |

#### Response

None (action only)

#### Example

```javascript
labClientWindow.postMessage({ event_id: 'sendLabNotification', notification: 'Lab step completed!' }, '*');
```

---

### getInstructionsPageIndex

**Event ID:**`getInstructionsPageIndex`

**Description:**Retrieves the index of the currently displayed instructions page by sending a message with this event ID to request the current instructions page index. The response includes the page index.

#### Request Parameters

| Name | Type | Required? | Default Value | Description |
| --- | --- | --- | --- | --- |
| `event_id` | string | Yes | — | Must be `getInstructionsPageIndex` |
| `version` | number | No | `1` | API version |

#### Response

| Name | Type | Value |
| --- | --- | --- |
| `event_Id` | string | Always `instructions_page_index` |
| `page_index` | number or null | The index of the currently displayed |

#### Example

```javascript
labClientWindow.postMessage({ event_id: 'getInstructionsPageIndex' }, '*');
// Listen for response with event_Id: 'instructions_page_index'
```

---

### getMinutesRemaining

**Event ID:**`getMinutesRemaining`

**Description:**Returns the number of minutes remaining in the lab session by sending a message with this event ID to get the remaining time.

#### Request Parameters

| Name | Type | Required? | Default Value | Description |
| --- | --- | --- | --- | --- |
| `event_id` | string | Yes | — | Must be `getMinutesRemaining` |
| `version` | number | No | `1` | API version |

#### Response

| Name | Type | Value |
| --- | --- | --- |
| `event_Id` | string | Always `minutes_remaining` |
| `minutes_remaining` | number | The number of minutes remaining in the lab session |

#### Example

```javascript
labClientWindow.postMessage({ event_id: 'getMinutesRemaining' }, '*');
// Listen for response with event_Id: 'minutes_remaining'
```

---

### gotoInstructionsPage

**Event ID:**`gotoInstructionsPage`

**Description:**Programmatically navigates to a specific instructions page by sending a message with this event ID and a `page_index` parameter.

> [!NOTE]
> Response
> 
> This event does not return a response.

#### Request Parameters

| Name | Type | Required? | Default Value | Description |
| --- | --- | --- | --- | --- |
| `event_id` | string | Yes | — | Must be `gotoInstructionsPage` |
| `page_index` | number | Yes | — | The index of the instructions page to open |
| `version` | number | No | `1` | API version |

#### Response

None (action only)

#### Example

```javascript
labClientWindow.postMessage({ event_id: 'gotoInstructionsPage', page_index: 2 }, '*');
```

---

### evaluateActivity

**Event ID:**`evaluateActivity`

**Description:**Triggers evaluation of a specific lab activity (e.g., check whether a lab step is complete) by sending a message with this event ID and an `alias` parameter.

> [!NOTE]
> Response
> 
> This event does not return a response.

#### Request Parameters

| Name | Type | Required? | Default Value | Description |
| --- | --- | --- | --- | --- |
| `event_id` | string | Yes | — | Must be `evaluateActivity` |
| `alias` | string | Yes | — | The unique identifier of the activity to evaluate, used to check whether the specified activity has been completed |
| `version` | number | No | `1` | API version |

#### Response

None (action only)

#### Example

```javascript
labClientWindow.postMessage({ event_id: 'evaluateActivity', alias: 'step1' }, '*');
```