How do I embed an AI agent in my web app using the Web SDK?

Embedding with the Web SDK

The Web SDK handles video rendering, audio, and session lifecycle. It works with React, Vue, Angular, and vanilla JavaScript.

1. Install the SDK

npm install @touchcastllc/napster-companion-api @reduxjs/toolkit

2. Get a session token (server-side)

First create your Omniagent via POST /public/agents if you haven't already. Then call POST /public/agents/{agentId}/connections with your agent ID to create a session. The response includes a token — pass this securely to the client. Never generate session tokens in client-side code.

3. Initialise in React

Import NapsterCompanionApiSdk, create a container ref, and call NapsterCompanionApiSdk.init(token, { mountContainer: containerRef.current, position: "bottom-right" }) inside a useEffect. Call instance.destroy() on cleanup.

Important: Always generate a fresh token on every page load — tokens are single-use and short-lived. Reusing a saved token will cause WebSocket connection failures on reload.

Tip: Examples for Vue, Angular, and vanilla JS are in the WebRTC docs. Always generate the session token on your backend — never in client-side code.

Persistence mode — keeping conversations alive across page navigation

By default, when a user navigates to a new page on your website, the Web SDK unmounts and the agent session ends. Persistence mode keeps the agent session alive across full page navigations on multi-page websites, so the conversation continues seamlessly even as users move between pages.

This means a user who starts a conversation on your homepage can navigate to a product page and continue the same conversation without losing context or needing to restart the agent.

How to enable persistence mode

Pass persistence: true when initialising the SDK:

NapsterCompanionApiSdk.init(token, {
  mountContainer: containerRef.current,
  position: "bottom-right",
  persistence: true
});

When persistence mode is enabled, the SDK maintains the session state and reconnects the agent on each new page load without requiring a new token or a new session to be created on the server. The session context — including conversation history — is preserved.

When to use persistence mode

• Multi-page websites where users browse across several pages in a single visit
• E-commerce sites where a user may move from a homepage to a product page to a cart
• Any experience where conversation continuity across page transitions matters

First release note

Persistence mode is in its first release. Napster is actively gathering feedback from real integrations. If you encounter issues or have feedback, raise it via the Napster developer community on Discord.

Full guide: developers.napster.com/docs/sdks/web-sdk/persistence