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

# Inbox component

> Embed the Inbox component to show a real-time conversation list scoped to the current User.

The Inbox component shows a list of conversations for the current User. It handles loading, pagination, and real-time updates automatically.

<img src="https://mintcdn.com/surge-67d47b03/TCCrlfgdQylYa0Zn/images/inbox-hero.jpg?fit=max&auto=format&n=TCCrlfgdQylYa0Zn&q=85&s=75845ba06f627b5f28e1328600218012" alt="Inbox component rendering a list of conversations with unread indicators and the most recent message snippet" width="1200" height="484" data-path="images/inbox-hero.jpg" />

## Installation

The simplest version of the inbox component can be embedded with an iframe:

```html theme={null}
<iframe
  src="https://embed.surge.app/conversations?user_id={SURGE_USER_ID}&token={ACCOUNT_TOKEN}&phone_number_id={PHONE_NUMBER_ID}"
></iframe>
```

Both `{SURGE_USER_ID}` and `{ACCOUNT_TOKEN}` are required for this account-token form. `{PHONE_NUMBER_ID}` is optional; include it when you want the inbox to show only conversations associated with a specific phone number.

If you use a signed User JWT from your server, pass that JWT as `token` and omit `user_id`; the JWT identifies the User. See [Embeddable UI components](./index#authentication) for the two authentication options.

## Events

The Inbox component emits `postMessage` events that you can listen to from the parent window.

| Event                     | When it fires                      |
| ------------------------- | ---------------------------------- |
| `conversation-selected`   | The user selects a conversation    |
| `conversation-deselected` | The active conversation is cleared |
| `filter-changed`          | The inbox filter changes           |

Listen for events from `https://embed.surge.app`:

```javascript theme={null}
window.addEventListener("message", (event) => {
  if (event.origin !== "https://embed.surge.app") return;

  switch (event.data?.type) {
    case "conversation-selected":
      console.log("Conversation selected", event.data);
      break;
    case "conversation-deselected":
      console.log("Conversation deselected", event.data);
      break;
    case "filter-changed":
      console.log("Filter changed", event.data);
      break;
  }
});
```

See the [Inbox component reference](https://docs.surge.app/ui/components/inbox#events) for the full event payload shapes.