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

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

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.

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

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

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

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.

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

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

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

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.

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

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.

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

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