Introduction
This is what makes an embedded Astrato dashboard behave like a native part of the surrounding application rather than an isolated iframe. The communication runs both ways:
Host app → Astrato: the external app can control navigation inside Astrato (switch sheets), pass filter values to Astrato, or trigger actions inside the embedded dashboard.
Astrato → host app: the embedded dashboard can tell the host which sheet is active, which filters are applied, or what the user just clicked — so the host can react.
Both directions use the standard browser postMessage API, so any web app that can run JavaScript can integrate.
When embedding Astrato, there is a need to allow communication between the host and the Astrato app.
These new actions allow external apps hosting Astrato apps to pass or receive information from the Astrato app.
Some use cases:
Control navigation inside Astrato from a custom navigation menu
Pass filter values to Astrato
Get information on current filters or active sheets from the Astrato app
Example: a customer portal embeds an Astrato dashboard alongside its own navigation menu. When the user clicks a menu item in the host app, the host sends a message to the Astrato iframe with the sheet name to display, and the dashboard switches to that sheet — without the user reloading the page or interacting with Astrato's own navigation. The dashboard becomes another panel of the host app, not a separate tool.
Passing information to an Astrato app
The example below shows how to pass information to an Astrato app and control navigation between the different sheets in the app.
Astrato Action
Uses the On browser event action block.
Add the go-to action block and set the parameter to use the custom event data payload.
External App Function
Add this JavaScript (JS) code to the external source app to control Astrato iframe embeds.
This defines the function to call:
const iframe = document.querySelector('iframe');
function sentMessage(type, payload) {
iframe.contentWindow.postMessage(
{
type: type, // or just `type`
payload: payload // or just `payload`
},
'*'
);
}
Calling the function
The function must be called to emit an event:
sentMessage('ASTRATO_SHEET_NAVIGATION', 'Home');
The payload would be, in this case, the name of the Sheet to navigate to.
It is important to ensure that the type in the code is identical to the custom event name in Astrato.
Listening to events in an Astrato app
Listening to events in Astrato allows Astrato to pass information to an external app.
The example below shows how to pass the active sheet to the external app.
Astrato Action
This action block emits the active sheet name to a browser event whenever the active sheet is changed.
External APP
Add this code to the external app to listen to events passed from Astrato.
window.addEventListener('message', (event) => {
if (event.data?.type === 'ASTRATO_SHEET_ENTER') {
const activeSheetName = event.data.payload;
['Circle', 'Square', 'Triangle'].forEach((sheetName) => {
const button = document.getElementById(sheetName);
if (activeSheetName === sheetName) {
button.classList.add('active');
} else {
button.classList.remove('active');
}
})
} FAQ
What does "listening to events" actually do?
The host application (the web app embedding Astrato) sends a message using iframe.contentWindow.postMessage(...). Inside the Astrato app, an Action with an On browser event trigger catches that message and runs whatever blocks you've configured — typically a Go-to action to navigate, or a Set Variable action to apply a filter. The "type" you send in the message must match the custom event name configured in the Astrato Action.
How does Astrato send information back to the host?
An Astrato Action emits a browser event (for example, when the active sheet changes). In the host application, a standard window.addEventListener('message', ...) listener catches it, reads event.data.type and event.data.payload, and reacts — highlighting a button, updating sidebar state, or anything else the host app needs to do.
What can I control through external communication?
Three common patterns: control navigation inside Astrato from a custom menu in the host app; pass filter values from the host into the dashboard; and read the current state of the dashboard (active sheet, applied filters) from the host. Anything that can be done through an Astrato Action can be triggered this way.
Do I need a special SDK to use this?
No. It uses the standard browser postMessage API and window.addEventListener('message', ...). Any web application that can run JavaScript can integrate with an Astrato embed.