## Send and receive messages

URL: https://docs.atlan.com/product/capabilities/build-apps/references/postmessage-reference

> postMessage types and payloads: send IFRAME_READY or request a token; handle ATLAN_AUTH_CONTEXT.

This reference provides message types, payload shapes, and usage patterns for communication between your embedded app and the product via `postMessage`. Use this document to look up which messages the product sends (handshake, auth context, logout) and which messages your app sends (ready signal, token request, error).

## Messages from Atlan to your app

```ts
{
 type: 'ATLAN_HANDSHAKE',
 payload: {
 appId: string
 }
}
```

```ts
{
 type: 'ATLAN_AUTH_CONTEXT',
 payload: {
 token: string,
 expiresAt: number,
 user: {
 id: string,
 username: string,
 email: string,
 name: string
 },
 page: {
 route: string,
 params: Record<string, string | string[]>,
 query: Record<string, string | string[]>
 },
 timestamp: number
 }
}
```

For a complete payload, see [Auth payload](https://docs.atlan.com/llms/platform/build-apps/auth-context/llms.txt).

```ts
{
 type: 'ATLAN_LOGOUT'
}
```

## Messages from your app to Atlan

```ts
{
 type: 'IFRAME_READY'
}
```

```ts
{
 type: 'IFRAME_TOKEN_REQUEST'
}
```

```ts
{
 type: 'IFRAME_ERROR',
 payload: {
 message: string
 }
}
```

## Minimal message handling example

```ts
const ATLAN_ORIGIN = 'https://your-tenant.atlan.com'

window.addEventListener('message', (event) => {
 if (event.origin !== ATLAN_ORIGIN) return

 const { type, payload } = event.data || {}

 switch (type) {
 case 'ATLAN_HANDSHAKE':
 // Never use '*' as targetOrigin.
 window.parent.postMessage({ type: 'IFRAME_READY' }, ATLAN_ORIGIN)
 break
 case 'ATLAN_AUTH_CONTEXT':
 console.log('Authenticated user:', payload.user.username)
 break
 case 'ATLAN_LOGOUT':
 // Clear any cached session state
 break
 }
})
```

## See also

- [Auth payload](https://docs.atlan.com/llms/platform/build-apps/auth-context/llms.txt): Token, user, and page fields
- [Embed your app](https://docs.atlan.com/llms/platform/build-apps/embed-in-atlan/llms.txt): Working integration example (SDK and manual)
- [Connection and authentication issues](https://docs.atlan.com/llms/platform/build-apps/connection-and-authentication-issues/llms.txt): Common handshake and timeout errors

---