JavaScript API

window.Nimbia has the functions and events below. The coming loadNimbia() returns the same object.

#How the API is named

• Anything getState() reads back is a setting, and update() changes it. Anything that happens once, such as starting a guide or hanging up, is a verb that returns a promise. pauseGuide() is a verb, because whether a guide is paused belongs to the running guide and ends with it.
• update() changes the keys you name and leaves the rest alone. The type is NimbiaUpdateOptions; the type for boot() is NimbiaBootOptions.
• Names are positive: visible, not hidden; microphoneEnabled, not muted.
• There are no toggles. update({ microphoneEnabled: false }) leaves the microphone off whatever it was before, so two calls can't undo each other.
• identify() says who the visitor is and starts a new session for them. update() says how the widget behaves and leaves the session alone.
• A call made before the script has loaded is queued and runs once it has. An action called before the session has started waits for it.
• The prompt a first-time visitor sees, "Ready for a 2-minute walkthrough?", is the CTA modal. dismissCtaModal() closes it and getState().ctaModalVisible says whether it shows.
• on() returns a function that removes the handler.

Nimbia.update({ visible: !onLoginPage, inputMode: "chat" }); // settings
await Nimbia.startGuide("guide-id"); // an action; fine before the widget is ready
const stop = Nimbia.on("guideEnded", onGuideEnded);
stop();

#Wait for the widget

The widget is ready once Nimbia has started the visitor's session, a moment after boot() with a user or after identify(). Actions wait for it themselves. To wait in your own code:

await Nimbia.ready; // a promise

Nimbia.on("ready", () => {}); // an event; runs at once if the widget is already ready

Nimbia.getState().ready; // a boolean

getState() exists only once the script has loaded. Before that, use Nimbia.ready or the events.

#Settings

update(options) changes the settings you name and leaves the rest alone. getState() returns their current values.

The widget keeps a setting it can't apply yet and applies it as soon as it can. speakerEnabled: false with no call running turns Nimbia's voice off once the next call starts, and getState() shows the kept value until then. inputMode: "chat" before a call makes the next call, or the next guide, start in chat. Settings made before the script has loaded or before the session has started apply once it has.

chatOpen, inputMode, microphoneEnabled and speakerEnabled belong to a call and reset when it ends. visible and minimized stay, also across identify().

Guides find their page by its path, such as /dashboard. When your app runs under a prefix, set basePath to it: with basePath: "/demo", the page /demo/dashboard matches a guide's /dashboard. Paths outside the prefix stay as they are, so you can set it once in boot(). The widget reads it each time it sends the page to Nimbia, so set it before the first page under the prefix. basePath stays across identify().

update() logs a warning and skips a key it doesn't know or a value of the wrong type.

// Keep the widget off the login form
Nimbia.update({ visible: location.pathname !== "/login" });

#Actions

Each action returns a promise. It resolves once the action has started and rejects with a NimbiaError if it can't. An action called before the widget is ready waits for it.

#Start a guide

startGuide(guideId) starts a guide the way the Start button in the widget's checklist does. A visitor who hasn't been asked about the microphone yet is asked first whether they want to talk or type. With inputMode: "chat" the guide starts in chat without the question.

When your page asks that question itself, pass the answer as startGuide(guideId, { inputMode }) and the widget doesn't ask. With "voice" the browser asks for the microphone at once, and if the visitor refuses, the guide goes on in chat. With "chat" the widget doesn't use the microphone. Nimbia speaks in both modes.

Call it from the click that confirms the choice, before any await in your handler. Safari plays Nimbia's voice only when the page started it while handling a click, and after the first await the page no longer counts as handling the click.

startButton.addEventListener("click", () => {
  Nimbia.startGuide("your-guide-id", { inputMode: voiceChosen ? "voice" : "chat" });
});

try {
  await Nimbia.startGuide("your-guide-id");
} catch (error) {
  if (error.code === "timeout") showHelpLink();
}

If you call startGuide() several times before the widget is ready, only the latest call runs, and the earlier ones reject with superseded. You find a guide's ID in the Nimbia dashboard.

startMilestone(guideId) is a deprecated alias. It skips the microphone question, as it always has.

#Errors

Check error.code or error.name === "NimbiaError". instanceof NimbiaError fails when the page and the widget script each have their own copy of the class.

#Events

on(event, handler) adds a handler and returns a function that removes it. once() does the same for a single run, and off(event, handler) removes a handler too.

const stop = Nimbia.on("guideEnded", ({ guideId, reason }) => {
  if (reason === "completed") analytics.track("guide_completed", { guideId });
});

// Later:
stop();

#State

getState() returns the settings above plus:

Nimbia.on("change", ({ state, changed }) => {
  if (changed.includes("call")) {
    document.body.classList.toggle("in-call", state.call === "connected");
  }
});

#TypeScript

Coming soon: the types ship with the @nimbia/js package, which isn't published yet. Until then, use the script snippet; the tables on this page list every function, setting and event.

Once it's published, @nimbia/js exports the types: NimbiaUpdateOptions, NimbiaState, NimbiaEvents and its payloads, NimbiaIdentity, NimbiaError and NimbiaErrorCode, and the Nimbia interface. With the snippet, install the package for its types and add this once, which types window.Nimbia:

import type {} from "@nimbia/js/global";