Controlling the Widget

Search…

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.
1
ServiceBell("init", "<API_KEY>", {
2
 /**
3
 * Whether or not to hide the widget initially.
4
 *
5
 * Defaults to false.
6
 */
7
 hidden: false,
8
​
9
 /**
10
 * Which side to render the widget on, 'left' or 'right'.
11
 *
12
 * Defaults to 'right'.
13
 */
14
 position: "right",
15
 
16
 /**
17
 * Whether or not to connect the widget on init, or manually later.
18
 * If the client has recently connected, they will connect anyway
19
 * despite this setting to allow for navigation and refreshes.
20
 *
21
 * Defaults to true.
22
 */
23
 connect: true,
24
 
25
 /**
26
 * Which design to use for the launcher, 'pill' or 'video'. Pill
27
 * is the small circle design that is used on smaller devices.
28
 * Video is the larger widget. Even if 'video' is specified,
29
 * 'pill' will be used on smaller devices.
30
 *
31
 * Defaults to 'video'.
32
 */
33
 launcher: 'pill',
34
 
35
 /**
36
 * Class name to use as selector for sensitive elements, causes
37
 * them not to be sent when viewing a visitor's screen. Should not
38
 * include selector characters like . or #, cannot be an arbitrarily
39
 * complex selector.
40
 *
41
 * Defaults to 'sb-block'.
42
 */
43
 blockClass: "sb-block",
44
 
45
 /**
46
 * How the widget initializes itself. It has three possible values.
47
 *
48
 * "retrigger" The widget will re-establish its session on each page load. 
49
 * This is the default mode.
50
 *
51
 * "iframe-jit" The widget loads the page into an iframe
52
 * when an agent connects. After that the widget will be continuously 
53
 * connected as they navigate the site.
54
 *
55
 * Defaults to 'retrigger'
56
 */
57
 mode: "retrigger"
58
})
Copied!
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")
1
ServiceBell("show");
Copied!
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")
1
ServiceBell("hide");
Copied!
Hides the widget if it's visible.
ServiceBell("expand")
1
ServiceBell("expand");
Copied!
Expands the widget if it's visible.
ServiceBell("alert", options?)
1
ServiceBell("alert", {
2
 // Title text to display in the push notification
3
 title: "My important page",
4
 // Body message to display in the push notification
5
 body: "Some helper text",
6
})
Copied!
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")
1
ServiceBell("dial");
Copied!
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")
1
ServiceBell("bookMeeting");
Copied!
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")
1
ServiceBell("connect");
Copied!
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")
1
ServiceBell("disconnect");
Copied!
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.