Install from npm

@faustine-ai/web-agent is the loader for apps that have a bundler. It gives you typed calls to start the agent, identify the user and open the panel. The widget and the agent's actions are not in the package. They load from Faustine when init runs.

Before you begin

• The agent has a version served on the environment the app loads. Publishing the first version serves it on the release target, which is the first environment you selected in the wizard.
• For a Next.js app, use @faustine-ai/next instead. See Install in Next.js.

Install the package

npm install @faustine-ai/web-agent

pnpm add @faustine-ai/web-agent

yarn add @faustine-ai/web-agent

bun add @faustine-ai/web-agent

Start the agent

To start the agent when your app loads:

1. In the portal, go to Web Agents and select your agent.
2. In the Overview tab, find the Install the assistant card and select the npm tab.
3. Copy the agentId value from the snippet.
4. Create a module that calls init, and import it from your app's entry file.

import Faustine from '@faustine-ai/web-agent';

export const agent = Faustine.init({
  agentId: '<AGENT_ID>',
});

The agent's launcher appears on the page. init returns a handle. Import agent wherever your app identifies the user or opens the panel.

A page holds one agent. A second call to init returns the handle of the first.

Load a different environment in development

init loads the Production environment, or the agent's first environment while it has no Production, unless you pass env. This example loads Staging outside production builds. import.meta.env.PROD is the Vite flag. Use your bundler's equivalent.

import Faustine from '@faustine-ai/web-agent';

export const agent = Faustine.init({
  agentId: '<AGENT_ID>',
  env: import.meta.env.PROD ? 'Production' : 'Staging',
});

The environment has to exist and serve a version. See Deploy a version to an environment.

Identify the user and sign out

Call identify when your app knows who the user is, and logout when they sign out.

import { agent } from './faustine';

export async function onSignedIn() {
  const me = await fetch('/api/me').then((res) => res.json());
  agent.identify({ jwt: me.faustineJwt });
}

export function onSignedOut() {
  agent.logout();
}

identify can run before the widget has finished loading. The loader keeps the last call and applies it when the widget is ready. To sign the token, see Verify your users with a signed token.

Server-side rendering

Importing the package on a server does nothing. init called outside a browser returns a handle whose methods do nothing, and logs one warning. In a framework that renders on the server, call init from code that runs in the browser only, such as an effect or a mount callback.

Troubleshooting

Next steps

• JavaScript API: every option of init and every method of the handle.
• React quickstart: the same install, step by step, in a React app.
• Verify your users with a signed token: sign the token that identify sends.
• @faustine-ai/web-agent: the package and its versions.