# 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

```ts
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

```ts
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.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `agentId` | `string` | Required | The agent's ID, from the **Install the assistant** card. `init` throws if it is missing. |
| `env` | `string` | `Production` | The name of the environment to load. Without it, the agent loads Production, or its first environment while it has no Production. |
| `debug` | `boolean` | `false` | Opens a debug session for this page. See [Open a debug session](https://docs.faustine.ai/web-agents/debug-sessions/). |

| Situation | What `init` does |
| --- | --- |
| Called again with the same `agentId` | Returns the existing handle. |
| Called again with another `agentId` | Returns the existing handle and logs a warning. |
| Called outside a browser | Returns a handle whose methods do nothing, and logs one warning. |
| The agent cannot load | Logs the error to the console. Nothing appears on the page, and a later call to `init` tries again. |

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

## identify

```ts
function identify(info: IdentifyInfo): void
```

Attaches the signed-in user to the conversation.

| Field | Type | Description |
| --- | --- | --- |
| `jwt` | `string` | A token signed by your backend. The user is verified. See [Verify your users with a signed token](https://docs.faustine.ai/web-agents/verify-users/). |
| `userId` | `string \| number` | Your ID for the user. Unverified. |
| `name` | `string` | A display name. Unverified. |
| `email` | `string` | An email address. Unverified. |

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.

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

## logout

```ts
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

```ts
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](https://docs.faustine.ai/web-agents/custom-launcher/).

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.

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

## shutdown

```ts
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`.

```ts
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]`.

| Message | Cause |
| --- | --- |
| `init requires { agentId }` | Thrown by `init` when `agentId` is missing. |
| `init called outside a browser` | `init` ran during server-side rendering. |
| `init called for "…" but "…" is already initialized` | `init` ran with a second agent ID. |
| `failed to load …/embed?wid=…` | The request for the agent failed. A `404` response means no environment serves a version. A `403` response means the page's domain is not in the allowed domains. |
| `failed to load …/widget.js` | The widget script did not load. |

## Next steps

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