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

# Modal Communication

> Handle communication between your website and the Anon modal

# Migration Modal Event Communication

The Anon modal uses a structured event system to communicate user interactions and modal state to the parent window when embedded as an iframe. Events are sent via `window.postMessage` and always include user and migration context.

## Event Types & Payloads

All events have the following payload components:

<ResponseExample>
  ```json Event Structure Example theme={"system"}
  {
    "id": "evt_1234567890_abc123",          // Unique identifier for the event
    "object": "event",
    "created": "2023-11-09T12:00:00.000Z",  // ISO 8601 timestamp
    "type": "migration_modal.opened",       // Event type (see table)
    "data": {
      "user_id": "123",                     // End-user ID provided at modal creation
      "migration_id": "456"       
      // Additional event-specific fields may be included
    }
  }
  ```
</ResponseExample>

<ResponseField name="id" type="string" required>
  Unique identifier for the event
</ResponseField>

<ResponseField name="object" type="string" required>
  Always set to `"event"`
</ResponseField>

<ResponseField name="created" type="string" required>
  ISO 8601 timestamp of when the event was created
</ResponseField>

<ResponseField name="type" type="string" required>
  Event type. One of:
  `migration_modal.opened`, `migration_modal.completed`, `migration_modal.closed`, `migration_modal.failed`, `migration_modal_step.started`, `migration_modal_step.submitted`, `migration_modal_step.completed`, `migration_modal_step.failed`
</ResponseField>

<ResponseField name="data" type="object" required>
  Event-specific data containing user and migration context

  <Expandable title="data">
    <ResponseField name="user_id" type="string" required>
      End-user ID provided at modal creation
    </ResponseField>

    <ResponseField name="migration_id" type="string" required>
      Migration identifier
    </ResponseField>

    <ResponseField name="modal_step" type="string">
      Current modal step (for `migration_modal_step` events).
      Options: `welcome`, `provider_selection`, `login`, `mfa`, `company_selection`, and `unrecoverable_error`.
    </ResponseField>

    <ResponseField name="error_message" type="string">
      Error description (for `migration_modal.failed` and `migration_modal_step.failed` events)
    </ResponseField>
  </Expandable>
</ResponseField>

Below is a summary of all event types, when they are emitted, and their payload structure.

| Event Type                       | When Emitted                       | Data Provided                                               |
| -------------------------------- | ---------------------------------- | ----------------------------------------------------------- |
| `migration_modal.opened`         | Modal first displayed              | `{}`                                                        |
| `migration_modal.completed`      | Migration successfully started     | `{}`                                                        |
| `migration_modal.closed`         | User exits before migration start  | `{ "modal_step": "<string>" }`                              |
| `migration_modal.failed`         | Unrecoverable error                | `{ "modal_step": "<string>", "error_message": "<string>" }` |
| `migration_modal_step.started`   | Step displayed to user             | `{ "modal_step": "<string>" }`                              |
| `migration_modal_step.submitted` | User submitted step (intent)       | `{ "modal_step": "<string>" }`                              |
| `migration_modal_step.completed` | Step processed successfully        | `{ "modal_step": "<string>" }`                              |
| `migration_modal_step.failed`    | Step failed (validation or system) | `{ "modal_step": "<string>", "error_message": "<string>" }` |

## Receiving Events in the Parent Window

To listen for modal events, add a `message` event listener in your parent application. Always check the event source and type:

```javascript theme={"system"}
window.addEventListener("message", (event) => {
  // You can also check: event.origin === "https://dashboard.anon.com" for extra security
  if (event.data?.source !== "anon_modal") return;

  const modalEvent = event.data.event;
  if (!modalEvent) return;

  switch (modalEvent.type) {
    case "migration_modal.opened":
      // Handle modal opened
      break;
    case "migration_modal.completed":
      // Handle migration success
      break;
    case "migration_modal.closed":
      // Handle user exit
      break;
    case "migration_modal.failed":
      // Handle unrecoverable error
      break;
    // ... handle other event types as needed
    default:
      // Unknown event
      break;
  }
});
```

## Event Flows

Below are typical event flows for different user and system scenarios.

<Tabs>
  <Tab title="Successful Migration">
    <Steps>
      <Step title="migration_modal.opened">
        Modal first displayed
      </Step>

      <Step title="migration_modal_step.started">
        Step displayed to user (e.g., "welcome")
      </Step>

      <Step title="migration_modal_step.submitted">
        User clicks submit
      </Step>

      <Step title="migration_modal_step.completed">
        Step processed successfully
      </Step>

      <Step title="migration_modal_step.started">
        Next step displayed (e.g., "login")
      </Step>

      <Step title="migration_modal.completed">
        All steps completed - authentication workflow successful
      </Step>
    </Steps>
  </Tab>

  <Tab title="Validation or Login Error">
    <Steps>
      <Step title="migration_modal_step.started">
        Step displayed to user (e.g., "login")
      </Step>

      <Step title="migration_modal_step.submitted">
        User clicks submit
      </Step>

      <Step title="migration_modal_step.failed">
        Validation error by Anon modal (e.g., "Invalid email format")
      </Step>

      <Step title="migration_modal_step.submitted">
        User tries again
      </Step>

      <Step title="migration_modal_step.failed">
        Login error by service (e.g., "Wrong email / password provided")
      </Step>

      <Step title="migration_modal_step.submitted">
        User tries again
      </Step>

      <Step title="migration_modal_step.completed">
        Validation & login passes
      </Step>
    </Steps>
  </Tab>

  <Tab title="Unrecoverable Error">
    <Steps>
      <Step title="migration_modal_step.started">
        Step displayed to user (e.g., "login")
      </Step>

      <Step title="migration_modal_step.submitted">
        User clicks submit
      </Step>

      <Step title="migration_modal.failed">
        Internal server error - unrecoverable
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

**Best Practices:**

* Always verify the event source and origin.
* Use the event type and data to drive analytics, UI, or business logic.
* All events include `user_id` and `migration_id` for context.
* The event system deduplicates identical events within a 3-second window.