Use your own launcher button

With the launcher set to Custom (SDK), the widget renders no launcher. A control in your app, such as a button in the top bar or an item in a menu, opens and closes the agent by calling toggle.

Before you begin

The agent is installed in your app. See Installation.

Turn off the built-in launcher

In the portal, go to Web Agents and select your agent.
Select the Look & feel tab.
Under Launcher, select Custom (SDK).
Select Save changes.
Publish a version and deploy it.

Warning

Once this version is deployed, your users have no way to open the agent until your app has its own button. Ship the button first. Calling toggle while the built-in launcher is still there does no harm.

Add the button to your app

toggle opens the agent if it is closed and closes it if it is open.

Call toggle on the handle that init returned. ./faustine is the module where your app calls Faustine.init.

src/AskButton.tsx

import { agent } from './faustine';

export function AskButton() {
  return (
    <button type="button" onClick={() => agent.toggle()}>
      Ask AI
    </button>
  );
}

The embed script defines the global Faustine.

index.html

<button type="button" onclick="Faustine.toggle()">Ask AI</button>

On the handle, toggle can run before the widget has finished loading. The widget opens when it is ready.

To open or close without toggling, call open or close. See the JavaScript API.

What else opens the agent

A custom launcher does not turn off the other ways the agent opens. The keyboard shortcut and Opens automatically work as set under Behavior. See Set the greeting, placeholder and shortcut.

Troubleshooting

Symptom	Cause	Fix
The built-in launcher is still on the page	The change is in the draft, or the version is not deployed to the environment your app loads.	Publish a version and deploy it to that environment.
The button does nothing	No version is deployed to the environment, so the widget never loads.	Deploy a version, then reload the page.
`Faustine is not defined` in an inline handler	The page does not load the embed script, or the handler ran before the script.	Load the embed script on the page, or install from npm and call `agent.toggle()`.

Next steps

Choose a launcher and its position: the built-in launchers.
JavaScript API: open, close, toggle and the rest of the handle.
Set the greeting, placeholder and shortcut: add a keyboard shortcut next to your button.

Last updated November 11, 2026