Embed

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

integer

default:"28800"

Token lifetime in seconds. Default: 28800 (8 hours). Max: 86400 (24 hours).

string

default:"full"

Which view to show: full, conversations, leads, sequences, settings

string

Display name for the embedded user (shown in manual messages)

string

default:"admin"

Permission level: owner, admin, member

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"
  }'

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();

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()

Response: 200 OK

{
  "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:

<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). 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

The embed never shows Recover branding to your end users. It’s fully white-labeled.

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.

<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	—

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:

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');
}

Core API

Features

Platform

Generate Embed Token

Iframe Setup

View Modes

White-Labeling

Responsive Sizing

Cross-Frame Events (postMessage API)

Token Refresh

​Generate Embed Token

​Iframe Setup

​View Modes

​White-Labeling

​Responsive Sizing

​Cross-Frame Events (postMessage API)

​Token Refresh

Generate Embed Token

Iframe Setup

View Modes

White-Labeling

Responsive Sizing

Cross-Frame Events (postMessage API)

Token Refresh