Controlling the Widget

Use the Javascript API to control widget behaviors

The ServiceBell API exposes a few methods that allow you to control the widget without user interaction. This can be useful for controlling the user experience around users requesting calls, or hooking up the widget to custom UI elements.

The API has changed as of January 31, 2022

If you've installed and used ServiceBell before then, you might notice our API has changed a little bit. Methods used to be called like ServiceBell.init(), but now use ServiceBell("init"). This allows us to add new methods without you needing to update your embedded snippet script.

If you installed an older version of the snippet, please copy and update with the latest snippet at the bottom of the Settings Page to start using the new API.

ServiceBell("init", api_key, options?)

You can add options to the init call to specify how the widget should render initially.

ServiceBell("init", "<API_KEY>", {
  /**
   * Whether or not to hide the widget initially.
   *
   * Defaults to false.
   */
  hidden: false,

  /**
   * Which side to render the widget on, 'left' or 'right'.
   *
   * Defaults to 'right'.
   */
  position: "right",
  
  /**
   * Whether or not to connect the widget on init, or manually later.
   * If the client has recently connected, they will connect anyway
   * despite this setting to allow for navigation and refreshes.
   *
   * Defaults to true.
   */
  connect: true,
  
  /**
   * Which design to use for the launcher, 'pill' or 'video'. Pill
   * is the small circle design that is used on smaller devices.
   * Video is the larger widget. Even if 'video' is specified,
   * 'pill' will be used on smaller devices.
   *
   * Defaults to 'video'.
   */
  launcher: 'pill',
  
  /**
   * Class name to use as selector for sensitive elements, causes
   * them not to be sent when viewing a visitor's screen. Should not
   * include selector characters like . or #, cannot be an arbitrarily
   * complex selector.
   *
   * Defaults to 'sb-block'.
   */
  blockClass: "sb-block",
  
  /**
   * How the widget initializes itself. It has three possible values.
   *
   * "retrigger" The widget will re-establish its session on each page load. 
   *     This is the default mode.
   *
   * "iframe-jit" The widget loads the page into an iframe
   *     when an agent connects. After that the widget will be continuously 
   *     connected as they navigate the site.
   *
   * Defaults to 'retrigger'
   */
  mode: "retrigger"
})

Note that some of these options overlap with the configurations set via your organization's widget appearance settings page. If any of these arguments are provided programmatically, the JS options will take precedence over the appearance settings.

ServiceBell("show")

ServiceBell("show");

Shows the widget if it's hidden. If you want to start the widget hidden and programmatically show later, initialize with hidden: false.

ServiceBell("hide")

ServiceBell("hide");

Hides the widget if it's visible.

ServiceBell("expand")

ServiceBell("expand");

Expands the widget if it's visible.

ServiceBell("alert", options?)

ServiceBell("alert", {
  // Title text to display in the push notification
  title: "My important page",
  // Body message to display in the push notification
  body: "Some helper text",
})

Puts the visitor into an alert state, which displays them prominently on the dashboard, and sends all available admins a push notification. You can configure the notification with the optional options object argument. Alerting will cause no visual change for the visitor, it's only for dashboard alerting purposes.

ServiceBell("dial")

ServiceBell("dial");

Puts the visitor into the dialing state, which displays them prominently on the dashboard, sends all available admins a push notification, and displays to the user the dialing state. This is equivalent to the user clicking on the widget to dial. The widget will always be visible when dialing, even if it was hidden.

ServiceBell("bookMeeting")

ServiceBell("bookMeeting");

Immediately opens the widget to the book meeting view that they normally see if the dial timer times out, or if no admins are available. Either shows them an email submission form, or the Calendly widget if Calendly is configured.

ServiceBell("connect")

ServiceBell("connect");

Triggers the widget to connect to the ServiceBell server if it wasn't already connected. This is only used in conjunction with { connect: false } or ServiceBell("disconnect") as the widget will normally connect by default after calling ServiceBell.init()

ServiceBell("disconnect")

ServiceBell("disconnect");

Triggers the widget to disconnect from the ServiceBell server if it wasn't already disconnected. This should typically be used in conjunction with ServiceBell.connect().

Note that if your ServiceBell installation initializes with { connect: true } or doesn't specify a connect parameter, the widget will immediately connect on the next page load or refresh unless ServiceBell("disconnect") is called again.

ServiceBell("showPopup", options?)

ServiceBell("showPopup", {
  /**
  * Whether to display a 'small' popup or a 'large' full screem modal
  *
  * Defaults to 'small'
  */
  size: "small"
});

Triggers a small popup to appear above the widget, or a larger modal to take over the screen, to invite visitors to use the ServiceBell widget to start a call. Either of them will only show up if the widget is currently collapsed, and agents are available to take calls. Otherwise there will be no effect.

ServiceBell("startJourney", options)

ServiceBell("startJourney", {
  /**
  * Journey ID to start the visitor on.
  *
  * The journey must be enabled.
  */
  journeyId: 123
});

This asynchronous call will attempt to start the visitor on the journey for the provided ID. If the journey is not found or not active, the api call will not succeed. If the visitor is currently on a different journey, it will be cancelled in favor of the one specified in the journeyId option parameter. If the visitor is already on the specified journey, the call will return true without restarting the journey. This function returns a Promise<boolean> representing whether the visitor has been (or already is) started on the journey. It will log failures to the browser console.