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

# Embed

> Embed the full dashboard into your application with a single iframe.

The embed system renders the full Recover dashboard inside your application via an iframe. Authentication is handled via short-lived tokens — your end users never need to create a Recover account or log in.

## Generate Embed Token

`POST /accounts/:id/embed-token`

<ParamField body="expires_in" type="integer" default="28800">
  Token lifetime in seconds. Default: 28800 (8 hours). Max: 86400 (24 hours).
</ParamField>

<ParamField body="view" type="string" default="full">
  Which view to show: `full`, `conversations`, `leads`, `sequences`, `settings`
</ParamField>

<ParamField body="user_name" type="string">
  Display name for the embedded user (shown in manual messages)
</ParamField>

<ParamField body="user_role" type="string" default="admin">
  Permission level: `owner`, `admin`, `member`
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/embed-token \
    -H "X-Partner-Key: pk_live_abc123def456..." \
    -H "Content-Type: application/json" \
    -d '{
      "expires_in": 28800,
      "view": "full",
      "user_name": "Jane Smith",
      "user_role": "admin"
    }'
  ```

  ```typescript JavaScript theme={null}
  const res = await fetch(`https://api.recoverbiz.com/v1/accounts/${accountId}/embed-token`, {
    method: 'POST',
    headers: {
      'X-Partner-Key': 'pk_live_abc123def456...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      expires_in: 28800,
      view: 'full',
      user_name: 'Jane Smith',
      user_role: 'admin',
    }),
  });
  const { embed_url } = await res.json();
  ```

  ```python Python theme={null}
  token = requests.post(
      f'{BASE_URL}/accounts/{account_id}/embed-token',
      headers=headers,
      json={
          'expires_in': 28800,
          'view': 'full',
          'user_name': 'Jane Smith',
          'user_role': 'admin'
      }
  ).json()
  ```
</CodeGroup>

**Response: `200 OK`**

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-02-15T18:30:00Z",
  "embed_url": "https://app.recoverbiz.com/embed?token=eyJhbGciOiJIUzI1NiIs..."
}
```

## Iframe Setup

Drop a single iframe tag into your page:

```html theme={null}
<iframe
  id="recover-embed"
  src="https://app.recoverbiz.com/embed?token=YOUR_TOKEN_HERE"
  style="width: 100%; height: 700px; border: none; border-radius: 8px;"
  allow="clipboard-write"
></iframe>
```

## View Modes

Control which part of the dashboard is visible:

| View            | What It Shows                                                                      |
| --------------- | ---------------------------------------------------------------------------------- |
| `full`          | Complete dashboard with tab navigation (Conversations, Leads, Sequences, Settings) |
| `conversations` | Conversation list + message view only                                              |
| `leads`         | Lead management table with filters and import                                      |
| `sequences`     | Sequence builder and enrollment                                                    |
| `settings`      | AI configuration, context files, checklist setup                                   |

Append `&view=conversations` to the embed URL, or set it when generating the token.

## White-Labeling

Branding is configured at the account level (see [Create Account](/partner/accounts#create-account)). The embed automatically applies:

* **Logo**: Your logo replaces the default logo in the sidebar and header
* **Accent color**: Buttons, links, and active states use your color
* **Company name**: All AI references use the account's `company_name`

<Info>
  The embed never shows Recover branding to your end users. It's fully white-labeled.
</Info>

## Responsive Sizing

The embed is fully responsive. Set the iframe width to `100%` and provide a minimum height of `500px`. For best results, use `height: calc(100vh - 64px)` to fill the available viewport.

```html theme={null}
<iframe
  src="https://app.recoverbiz.com/embed?token=..."
  style="width: 100%; height: calc(100vh - 64px); border: none;"
></iframe>
```

## Cross-Frame Events (postMessage API)

The embed communicates events to your parent window via `postMessage`. Listen for events to react to user actions inside the embed.

| Event                           | Fires When                       | Data Fields       |
| ------------------------------- | -------------------------------- | ----------------- |
| `recover:conversation_selected` | User opens a conversation        | `phone`           |
| `recover:lead_status_changed`   | Lead status is updated           | `phone`, `status` |
| `recover:checklist_completed`   | All required documents collected | `phone`           |
| `recover:message_sent`          | Manual message sent from embed   | `phone`           |
| `recover:token_expiring`        | Token expires in 5 minutes       | —                 |

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

  const { type, data } = event.data;

  switch (type) {
    case 'recover:conversation_selected':
      console.log('User opened conversation:', data.phone);
      break;
    case 'recover:lead_status_changed':
      console.log('Lead status updated:', data.phone, data.status);
      break;
    case 'recover:checklist_completed':
      console.log('All documents collected for:', data.phone);
      break;
    case 'recover:message_sent':
      console.log('Manual message sent to:', data.phone);
      break;
    case 'recover:token_expiring':
      // Token expires in 5 minutes — refresh it
      refreshEmbedToken();
      break;
  }
});
```

## Token Refresh

Tokens expire after the configured `expires_in` period. The embed emits a `recover:token_expiring` event 5 minutes before expiry. To refresh without a page reload:

```javascript theme={null}
async function refreshEmbedToken() {
  const res = await fetch('/your-backend/recover-token', { method: 'POST' });
  const { token } = await res.json();

  const iframe = document.getElementById('recover-embed');
  iframe.contentWindow.postMessage({
    type: 'recover:refresh_token',
    token: token
  }, 'https://app.recoverbiz.com');
}
```