Widget Public API

If you add custom code to your website, Rose exposes a small browser API on window.InboundXWidget.

You can use it to:

• check whether the widget is ready
• read the current Rose session ID
• read visitor identifiers if you need them
• add Rose data to your own links, redirects, or booking flows

When to use it

The widget loads in the background after your page starts rendering.

If you want to read data from the widget as soon as the page loads, wait until Rose is ready:

<script>
function waitForRoseReady(callback) {
  const tryAgain = () => {
    if (!window.InboundXWidget) {
      window.setTimeout(tryAgain, 100);
      return;
    }

    if (window.InboundXWidget.isReady?.()) {
      callback();
      return;
    }

    if (window.InboundXWidget.onReady) {
      window.InboundXWidget.onReady(callback);
      return;
    }

    window.setTimeout(tryAgain, 100);
  };

  tryAgain();
}

waitForRoseReady(() => {
  console.log('Rose is ready');
});
</script>

You can also check readiness manually:

window.InboundXWidget?.isReady?.();

This returns:

• true when the widget is fully loaded
• false when it is still loading

Available methods

Method	What it does	Typical use
isReady()	Returns true when the widget is ready	Check whether you can safely call the API
onReady(callback)	Runs your callback once the widget is ready	Best option when adding custom scripts
getIdentityContext()	Returns all available Rose identifiers in one object	Use when you want everything at once
getSessionId()	Returns the current Rose session ID	Most common method
getLastActiveSessionId()	Returns the most recent active Rose session ID	Use only if you specifically need the last active conversation
getPersonId()	Returns the visitor's Rose person ID when available	Useful for advanced tracking
getClientId()	Returns Rose's stable client ID for this browser	Useful for advanced tracking

What getIdentityContext() returns

{
  sessionId: "sess_123",
  lastActiveSessionId: "sess_123",
  personId: "person_456",
  clientId: "client_789"
}

Some values can be null.

For example:

• sessionId is usually available once the widget is ready
• personId may still be null if Rose has not identified the visitor yet
• clientId is available for Rose's internal tracking even when personId is not

If you only need one value, use the dedicated getter instead of reading the full object.

Most common use case

Most websites only need this:

window.InboundXWidget?.getSessionId?.();

That gives you the current Rose session ID for the page.

Use it after the widget is ready, or inside a click handler.

Example: add rose_session_id to your redirect URL

Here is the basic idea:

const url = new URL('https://example.com/book-demo');
const sessionId = window.InboundXWidget?.getSessionId?.();

if (sessionId) {
  url.searchParams.set('rose_session_id', sessionId);
}

window.location.href = url.toString();

If the session ID is available, the final URL becomes:

https://example.com/book-demo?rose_session_id=sess_123

If the session ID is not available yet, the redirect still works. It simply opens without that extra parameter.

Examples by platform

Basic JSReactFramerWebflow

<button id="book-demo-button">Book a demo</button>

<script>
document.addEventListener('DOMContentLoaded', () => {
  const button = document.getElementById('book-demo-button');
  if (!button) return;

  button.addEventListener('click', () => {
    const url = new URL('https://example.com/book-demo');
    const sessionId = window.InboundXWidget?.getSessionId?.();

    if (sessionId) {
      url.searchParams.set('rose_session_id', sessionId);
    }

    window.location.href = url.toString();
  });
});
</script>

import React from 'react';

export default function BookDemoButton() {
  const handleClick = () => {
    const url = new URL('https://example.com/book-demo');
    const sessionId = window.InboundXWidget?.getSessionId?.();

    if (sessionId) {
      url.searchParams.set('rose_session_id', sessionId);
    }

    window.location.href = url.toString();
  };

  return <button onClick={handleClick}>Book a demo</button>;
}

import * as React from 'react';

export default function BookDemoButton() {
  const handleClick = () => {
    const url = new URL('https://example.com/book-demo');
    const sessionId = window.InboundXWidget?.getSessionId?.();

    if (sessionId) {
      url.searchParams.set('rose_session_id', sessionId);
    }

    window.location.href = url.toString();
  };

  return (
    <button
      onClick={handleClick}
      style={{ padding: '12px 20px', cursor: 'pointer' }}
    >
      Book a demo
    </button>
  );
}

In Framer, you can use this inside a Code Component or a custom code block.

Give your button an ID such as book-demo-button, then add this in Project Settings → Custom Code or on the page:

<script>
document.addEventListener('DOMContentLoaded', () => {
  const button = document.getElementById('book-demo-button');
  if (!button) return;

  button.addEventListener('click', function (event) {
    event.preventDefault();

    const url = new URL('https://example.com/book-demo');
    const sessionId = window.InboundXWidget?.getSessionId?.();

    if (sessionId) {
      url.searchParams.set('rose_session_id', sessionId);
    }

    window.location.href = url.toString();
  });
});
</script>

If you want to read the session ID immediately on page load

For example, if you want to store it in your own script before any button click, use waitForRoseReady:

<script>
function waitForRoseReady(callback) {
  const tryAgain = () => {
    if (!window.InboundXWidget) {
      window.setTimeout(tryAgain, 100);
      return;
    }

    if (window.InboundXWidget.isReady?.()) {
      callback();
      return;
    }

    if (window.InboundXWidget.onReady) {
      window.InboundXWidget.onReady(callback);
      return;
    }

    window.setTimeout(tryAgain, 100);
  };

  tryAgain();
}

waitForRoseReady(() => {
  const sessionId = window.InboundXWidget.getSessionId();
  console.log('Current Rose session:', sessionId);
});
</script>

Which method should I use?

Goal	Recommended method
Wait until Rose is ready	onReady(callback)
Check readiness manually	isReady()
Get the current session ID	getSessionId()
Get everything at once	getIdentityContext()

Good to know

• The public API is available on the top-level page where the Rose widget is installed.
• If you test inside a preview iframe, some values may be missing.
• In most cases, getSessionId() is the only method you need.