# React Release Notes

> Release notes for @revrag-ai/embed-react — what changed in each release, with upgrade steps.

URL: /embed/integration/react/react-releases
Markdown: /embed/integration/react/react-releases.md



# React SDK — Release Notes [#react-sdk--release-notes]

`@revrag-ai/embed-react` · release history, newest first. Install the latest with `npm install @revrag-ai/embed-react@latest`; confirm the current version on [npm](https://www.npmjs.com/package/@revrag-ai/embed-react).

***

## 1.5.0 [#150]

*Released: 5 October 2026*

The Action Intelligence release — the voice agent can now **see and act on the host page** — plus a React 17 build and many widget stability fixes. Several of the fixes stop crashes and freezes the host app could hit in 1.4.4, so **upgrading is recommended**. Upgrading from **1.4.4** needs a few code changes; work through the [upgrade steps](#upgrade-steps-144--150) below.

```bash
npm install @revrag-ai/embed-react@1.5.0
```

### Breaking changes [#breaking-changes]

| Change                                          | What to do                                                                                                                        |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **`appVersion` is required in `useInitialize`** | Pass it in the options: `useInitialize(apiKey, { appVersion })`. Without it, initialization fails and the widget never appears.   |
| **`useEmbed()` removed**                        | Use `startCall`, `endCall`, `isCallActive` and the widget functions in [New exports](#new-exports).                               |
| **`EmbedContextType` type removed**             | Not needed once `useEmbed` is gone.                                                                                               |
| **`EventPayload` type removed**                 | Use `CustomEventPayload`.                                                                                                         |
| **`embedEvent` is narrower**                    | `reset()` and `getSessionId()` are gone. `event`, `customEvent`, `addCallback`, `removeCallback` and `getStoredAppUserId` remain. |

### Behaviour changes to check [#behaviour-changes-to-check]

| Change                                            | What to check                                                                                                                                                 |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **The agent can act on your pages during a call** | Add `data-revrag-mask` to fields it must never read, and put screens it must never see in `excludeScreens`.                                                   |
| **Higher default z-index**                        | The widget now sits above the host page's own modals and overlays. If you placed your own UI above the widget with a fixed z-index, check it is still on top. |
| **The button is draggable by default**            | Known issue: `EmbedButton` does not pass `draggable` or `autoCollapseMs` through in 1.5.0, so `draggable={false}` has no effect yet.                          |

### New [#new]

* **Action Intelligence.** During a call, the agent can read the current screen and act on it — tap, type, select, scroll and read fields — and highlights each element it acts on.
  * Starts automatically inside `EmbedProvider`; no setup needed.
  * Masked fields (`data-revrag-mask`, exported as `MASK_ATTR`) are never sent.
  * If the user clicks or types during an action, the agent stops instead of overwriting them.
  * New `EmbedProvider` props: `actionRootRef`, `excludeScreens`, `showOnAllScreens` and `getScreenName`.
* **Widget.**
  * A draggable button, on by default, that works with touch.
  * Live captions (CC) and an in-call status line ("Speaking", "Listening").
  * During a call, the expanded card collapses back to the button after `collapsedView.collapsedTime`; the call keeps running.

#### New exports [#new-exports]

| Export                                                                          | What it does                                                       |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `startCall`, `endCall`, `isCallActive`                                          | Start or end a call from your own code                             |
| `expandWidget`, `collapseWidget`, `isWidgetExpanded`, `subscribeWidgetExpanded` | Open, close or watch the widget                                    |
| `EmbedLogout`                                                                   | Clear the SDK session when your user signs out                     |
| `AgentEvent`, `embedOnAgent`, `embedOffAgent`                                   | Subscribe to agent lifecycle events                                |
| `MASK_ATTR`                                                                     | The attribute name that masks a field                              |
| `@revrag-ai/embed-react/react17`                                                | Build for React 17 apps on webpack                                 |
| `@revrag-ai/embed-react/diagnostics`                                            | `verifyIntegration()` and `integrationSnapshot()` to check a setup |

### Fixed [#fixed]

* **Host app safety**
  * A crash inside the widget now hides only the widget, instead of unmounting the whole app.
  * Bad values in the dashboard's widget config no longer crash rendering; each field falls back to its default.
  * The SDK loads when browser storage is blocked ("Block all cookies", sandboxed iframes).
  * No more tab freeze when another script also keeps its element pinned to the end of `<body>`.
  * Ending a call no longer removes the host page's own `<audio>` elements.
  * `"use client"` is back in the bundles, so the Next.js App Router works without a wrapper.
* **Calls**
  * Closing the widget or ending a call while it was still connecting could leave the microphone on — fixed.
  * Mute state no longer carries over into the next call.
* **Widget display**
  * The widget no longer sits behind the host page's own modals and overlays, and stays usable while a host dialog is open.

### Upgrade steps: 1.4.4 → 1.5.0 [#upgrade-steps-144--150]

1. Install `@revrag-ai/embed-react@1.5.0`, and check your stack against the [Dependency & Compatibility Guide](/embed/integration/react/react-dependencies).
2. Pass `appVersion` to `useInitialize`, matching a version your Revrag dashboard has a config for.
3. Search your code for `useEmbed`, `EmbedContextType` and `EventPayload`, and replace them as above.
4. React 17 on webpack: import from `@revrag-ai/embed-react/react17`.
5. Import the stylesheet as `@revrag-ai/embed-react/style.css`, not `…/dist/style.css`.
6. Call `EmbedLogout()` when your user signs out.
7. Mask sensitive fields and set `excludeScreens` where needed.
8. Optional: run `verifyIntegration()` from `@revrag-ai/embed-react/diagnostics` to check the setup.

The [React integration guide](/embed/integration/react) covers each step in detail.

***

## 1.4.4 and earlier [#144-and-earlier]

1.4.4 was published on 8 June 2026. It predates most of 1.5.0: no `/react17` or `/diagnostics` entry, no `appVersion` option, no Action Intelligence, no call controls, no agent events and no `EmbedLogout()`. If you are still on it, upgrade with the steps above.