JavaScript API

The JavaScript API starts a Web Agent on a page, identifies the user and controls the panel. It is the same in both installs: window.Faustine after the loader.js script tag, and the default export of @faustine-ai/web-agent. This page describes version 0.2.5 of the package.

Usage

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

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

agent.identify({ jwt: token });
agent.open();

init loads the version the environment serves and the widget, and returns a handle. Until init has run, identify, logout and shutdown do nothing. On a page that loads the agent with the auto-mount script tag, which does not call init, only open, close and toggle work. Every method of the handle is also a function of Faustine, and a named export of the package: init, identify, logout, open, close, toggle and shutdown.

A page holds one agent. The API has no events and no callbacks.

init

function init(options: InitOptions): AgentHandle

Starts the agent and shows the launcher. The call returns immediately. The widget loads in the background, and calls made on the handle before it is ready are applied when it is.

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

identify

function identify(info: IdentifyInfo): void

Attaches the signed-in user to the conversation.

Every field is optional. Pass jwt alone for a verified user. The other three are labels that appear in the agent's Monitoring tab as Unverified, and Faustine ignores them when Enforce verification is on.

A call made before the widget is ready is kept and applied when it is. If there are several, the last one is applied. Faustine.identify can also be called before init. It has no effect on a page installed with the auto-mount script tag, where init never runs.

agent.identify({ jwt: me.faustineJwt });

logout

function logout(): void

Removes the identity, the open conversation and the cached transcript from the browser, and shows an empty widget. Call it when the user signs out of your app. The launcher stays on the page, and the browser keeps its anonymous visitor ID.

open, close and toggle

function open(): void
function close(): void
function toggle(): void

open opens the panel, close closes it and leaves the launcher, and toggle does one or the other. Use them from your own button. See Use your own launcher button.

A call to open or toggle made before the widget is ready is applied when it is. On a page installed with the auto-mount script tag, Faustine.open, Faustine.close and Faustine.toggle work without init. They wait up to 2 seconds for the widget to load.

document.querySelector('#help')?.addEventListener('click', () => agent.toggle());

shutdown

function shutdown(): void

Does what logout does and removes the widget and the launcher from the page. A later call to init starts the agent again.

Types

The package exports InitOptions, IdentifyInfo and AgentHandle.

interface AgentHandle {
  open(): void;
  close(): void;
  toggle(): void;
  identify(info: IdentifyInfo): void;
  logout(): void;
  shutdown(): void;
}

Errors

The loader does not throw after init returns. It writes to the console, with the prefix [Faustine].

Next steps

• Install from npm: add the package to an app with a bundler.
• Install with a script tag: use the same API without a build step.
• Identity verification: what each identity level gives the user.
• @faustine-ai/web-agent: the package and its versions.