Iframe Persistence

When you embed a BoostGPT agent directly in an iframe, the chat is saved by BoostGPT after the first message is sent. To resume that same chat after your page reloads, store the active chat_id sent by the iframe.

Embed URL

Start with your agent URL and add embed=1.

<iframe
  id="boostgpt-agent"
  src="https://agent.your-domain.com?embed=1"
  style="width: 100%; height: 720px; border: 0;"
  allow="clipboard-read; clipboard-write; microphone; camera; fullscreen"
></iframe>

After the first message, the embedded agent navigates to:

https://agent.your-domain.com/<chat_id>?embed=1

Listen For Chat IDs

BoostGPT sends a postMessage event whenever an embedded chat id becomes active.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://agent.your-domain.com') return;
  if (event.data?.type !== 'boostgpt:chat_id') return;

  localStorage.setItem('boostgpt_chat_id', event.data.chat_id);
});

Event payload:

{
  type: 'boostgpt:chat_id',
  chat_id: 'CHAT_UUID',
  bot_id: 'BOT_UUID',
  embed: true,
  widget: false
}

Restore The Chat

When your page loads again, read the saved chat id and include it in the iframe URL.

const iframe = document.getElementById('boostgpt-agent');
const chatId = localStorage.getItem('boostgpt_chat_id');
const baseUrl = 'https://agent.your-domain.com';

iframe.src = chatId
  ? `${baseUrl}/${encodeURIComponent(chatId)}?embed=1`
  : `${baseUrl}?embed=1`;

Full Example

<iframe
  id="boostgpt-agent"
  style="width: 100%; height: 720px; border: 0;"
  allow="clipboard-read; clipboard-write; microphone; camera; fullscreen"
></iframe>

<script>
  const baseUrl = 'https://agent.your-domain.com';
  const storageKey = 'boostgpt_chat_id';
  const iframe = document.getElementById('boostgpt-agent');

  const chatId = localStorage.getItem(storageKey);
  iframe.src = chatId
    ? `${baseUrl}/${encodeURIComponent(chatId)}?embed=1`
    : `${baseUrl}?embed=1`;

  window.addEventListener('message', (event) => {
    if (event.origin !== baseUrl) return;
    if (event.data?.type !== 'boostgpt:chat_id') return;

    localStorage.setItem(storageKey, event.data.chat_id);
  });
</script>

Use a scoped storage key if you embed multiple agents:

const storageKey = `boostgpt_chat_id:${botId}`;

SSO With Iframe Embeds

Pass a short-lived SSO token in the iframe URL so the embedded agent can authenticate the user on its own domain.

https://agent.your-domain.com?embed=1&sso_token=SIGNED_JWT

When restoring a saved chat, include the same parameter on the chat URL:

https://agent.your-domain.com/<chat_id>?embed=1&sso_token=SIGNED_JWT

Generate SIGNED_JWT on your server using the agent’s SSO secret. Do not sign SSO tokens in browser code.

import jwt from 'jsonwebtoken';

const token = jwt.sign({
  email: user.email,
  name: user.name,
  external_id: user.id,
}, process.env.BOOSTGPT_SSO_SECRET, {
  algorithm: 'HS256',
  expiresIn: '10m',
});

See SSO setup for the full JWT payload and backend examples.

Getting Started

Choose Your Path

Providers & Models

Embed URL

Listen For Chat IDs

Restore The Chat

Full Example

SSO With Iframe Embeds

​Embed URL

​Listen For Chat IDs

​Restore The Chat

​Full Example

​SSO With Iframe Embeds

Embed URL

Listen For Chat IDs

Restore The Chat

Full Example

SSO With Iframe Embeds