Skip to main content

Calls Widget API Reference

The Calls Widget API provides methods to customize the behavior and appearance of the Bambuser One-to-One Calls Widget on your website.

Getting Started​

After setting up your onBambuserOneToOneReady handler (as described in the Initial Setup), you can start customizing the behavior of the Calls Widget on your site.

window.onBambuserOneToOneReady = BambuserOneToOneEmbed => {
  // This method will be invoked when embed.js has loaded and Bambuser 
  // One-to-One API is available.
  let oneToOneEmbed = new BambuserOneToOneEmbed({
    orgId: 'YOUR_ORG_ID_HERE',
  });
};
caution

Note that the oneToOneEmbed object and its properties (constants and methods below) are only accessible within the onBambuserOneToOneReady method body.

You should define the onBambuserOneToOneReady method before loading the embed script (embed.js) on your page.

Instance Constructor​

The BambuserOneToOneEmbed constructor is used to create an instance of the embed with specific configuration options. You can customize the widget's behavior, appearance, and functionality by passing different options to the constructor.
At least the orgId option is required to initialize the embed.

Configuration Options​

orgId​

  • Value type: string

Your organization ID found in your Bambuser dashboard URL (https://lcx.bambuser.com/o/[orgId]/...)

queue​

  • Value type: string

Specify which queue customers should join when initiating calls. If not specified, the default queue configured in the BamHub will be used. It accepts queue name, or ID.

let oneToOneEmbed = new BambuserOneToOneEmbed({
  queue: 'QUEUE_NAME_OR_ID_HERE'
});

triggers​

  • Value type: Array<string>

Specify custom events that will trigger the start of a call. This can be useful for integrating with other parts of your application.

Available trigger types:

  • 'connect-link': Required for starting booked calls/appointments using connect links (?bambuserConnectId=XXXXXXXXX).
  • 'queue-link': Opens the callsWidget with the queue specified in the bambuserQueueId URL parameter.
  • 'smart': Enables the overlay widget functionality. See other Overlay Widget options.
  • 'always': Automatically opens the calls Widget after page load.
let oneToOneEmbed = new BambuserOneToOneEmbed({
  triggers: [
    'smart',        // Activate overlay widget
    'connect-link', // Required for connect links (Created for booked calls)
    'queue-link',   // Required for queue links
    'always',       // Auto-open on page load
    ]
});

connectId​

  • Value type: string

Specify a connect ID to directly start a call for a booked meeting. This is an alternative to using the bambuserConnectId URL query parameter.

let oneToOneEmbed = new BambuserOneToOneEmbed({
  orgId: 'YOUR_ORG_ID',
  connectId: 'XXXXXXXXXXXX'
});

dropInEnabled​

  • Default: true
  • Value type: boolean

Control the visibility of the drop-in option on the start screen.

bookingsEnabled​

  • Default is configured in the BamHub settings
  • Value type: boolean
  • Requirement: Bookings must be enabled in the BamHub configurations.

Control the visibility of the booking option on the start screen.

openBookingPage​

  • Value type: boolean
  • Default: false

If set to true, the widget will open directly on the booking page as soon as the embed is initialized.

let oneToOneEmbed = new BambuserOneToOneEmbed({
  orgId: 'YOUR_ORG_ID',
  openBookingPage: true
});

locale​

  • Default: 'en-US'
  • Value type: string

Sets the language and region for the widget. (e.g., en-GB, sv-SE)
The locale code MUST match one of the enabled translations available on your BamHub settings.

let oneToOneEmbed = new BambuserOneToOneEmbed({
  locale: 'sv-SE'
});

data​

  • Value type: object | function returning Promise<object>

Provide customer data to be presented to agents during calls. Can be a static object or a function that returns a Promise.

// Example: Static data
let oneToOneEmbed = new BambuserOneToOneEmbed({
  data: {
    firstName: "Joe",
    lastName: "Doe",
    externalId: 123,
    email: "joe@example.com"
  }
});
// Example: Dynamic data
let oneToOneEmbed = new BambuserOneToOneEmbed({
  data: function() {
    return new Promise((resolve) => {
      fetch('/api/current-user')
        .then(response => response.json())
        .then(user => resolve({
          externalId: user.id,
          firstName: user.first_name,
          lastName: user.last_name
        }));
    });
  }
});

The customer data can be updated at any point during the session using the updateData() method.

allowFirstPartyCookies​

  • Default: true
  • Value type: boolean

Configure if the embed script is allowed to write first-party cookies for tracking purposes.

Static example:

let oneToOneEmbed = new BambuserOneToOneEmbed({
  allowFirstPartyCookies: false
});

Dynamic example:

let oneToOneEmbed = new BambuserOneToOneEmbed({
  // Replace `hasDeclinedCookies` with your own function to check if user has declined cookies
  allowFirstPartyCookies: !hasDeclinedCookies()
});

trackingTags​

  • Value type: Array<{key: string, value: string | number | boolean}>

Set custom tracking tags during initialization. These tags can be used for analytics and reporting. Can also be set or updated later using the setTrackingTags() method.

Constraints:

  • Maximum of 20 tags allowed
  • Key must be a string
  • Value can be string, number, or boolean (strings limited to 1KB)
  • Duplicate keys not allowed (last one wins)
let oneToOneEmbed = new BambuserOneToOneEmbed({
  trackingTags: [
    { key: 'customer-segment', value: 'premium' },
    { key: 'has-purchased-before', value: true }
  ]
});

enableScanning​

  • Default: false
  • Value type: boolean

Enable barcode and QR code scanning in Agent mobile apps when the back-facing camera is active.

merchantBaseUrl​

  • Default: window.origin
  • Value type: string

In cobrowsing mode, specifies the base URL where agents will be sent when browsing starts.

dataLayerTracking​

  • Default: true
  • Value type: boolean

Control whether tracking events are pushed to the Google Tag Manager data layer.

ecommerceTracking​

  • Default: true
  • Value type: boolean

Control whether GA4 Ecommerce events are pushed to the data layer.

bookingServiceIds​

  • Default: All published services
  • Value type: Array<string>

Control which published booking services are visible to customers.

let oneToOneEmbed = new BambuserOneToOneEmbed({
  bookingServiceIds: ['service-id-1', 'service-id-2']
});

bookingResourceId​

  • Value type: string

Specify a specific booking resource ID for Bambuser Native Bookings. It allows you to control which specific resource is bookable. Setting bookingResourceId is possible through URL query parameters and embed configs.

Example: (URL param)

https://www.mydomain.com/live-meeting?bookingResourceId=XXXXXXXXXXXX

Example: (Embed config)

let oneToOneEmbed = new BambuserOneToOneEmbed({
  orgId: 'YOUR_ORG_ID',
  bookingResourceId: 'XXXXXXXXXXXX'
});

bookingIframeUrl​

  • Value type: string

Specify a custom URL for the booking iframe. This is typically used for external booking system integrations.

let oneToOneEmbed = new BambuserOneToOneEmbed({
  orgId: 'YOUR_ORG_ID',
  bookingIframeUrl: 'https://your-booking-system.com/embed'
});

disableCoBrowsing​

  • Default: false
  • Value type: boolean

Disable the Co-browsing functionality in the Calls Widget.

let oneToOneEmbed = new BambuserOneToOneEmbed({
  orgId: 'YOUR_ORG_ID',
  disableCoBrowsing: true
});

Note the Co-browsing feature needs to be enabled for you to work. Learn more about Co-browsing.

floatingPlayer​

  • Value type: object
  • Default: { navigationMode: 'iframe' }
  • Requirement: Co-browsing must be enabled

Configure floating player behavior when the widget is minimized during co-browsing. This controls how navigation is handled when the widget floats above your website content.

Properties:

  • navigationMode - string - Navigation mode: 'iframe' or 'manual'
    • 'iframe' (default) - Widget handles navigation automatically using an iframe. Recommended for most use cases.
    • 'manual' - Developer handles navigation manually. Ideal for Single Page Applications (SPAs) that skip the iframe navigation window.
  • confirmClosingBrowser - boolean - When navigationMode is 'manual', controls whether to show a browser confirmation dialog when user tries to close/refresh the page during a call. Default: true

Examples:

Using string values:

let oneToOneEmbed = new BambuserOneToOneEmbed({
  floatingPlayer: {
    navigationMode: 'manual',
    confirmClosingBrowser: false
  }
});

Using constants:

window.onBambuserOneToOneReady = BambuserOneToOneEmbed => {
  let oneToOneEmbed = new BambuserOneToOneEmbed({
    orgId: 'YOUR_ORG_ID',
    floatingPlayer: {
      navigationMode: BambuserOneToOneEmbed.FLOATING_PLAYER_NAVIGATION_MODE.MANUAL,
      confirmClosingBrowser: true
    }
  });
};

More details about floating player compatibility and behavior can be found in the Iframe Compatibility & Handling Navigation documentation.

themeId​

  • Default: default BamHub theme
  • Value type: string

Specify which theme to apply to the Calls Widget if multiple themes are enabled.

Example:

let oneToOneEmbed = new BambuserOneToOneEmbed({
  orgId: 'YOUR_ORG_ID',
  themeId: 'XXXXXXXXXXXX'
});

getMinimizedWidgetStyle​

  • Value type: function
  • Returns: object with positioning properties

Customize the positioning and appearance of the minimized/floating widget.

Return Object Properties:

  • position - Widget position (e.g., 'bottom-right', 'bottom-left')
  • verticalMargin - Vertical offset as a CSS value (e.g., '16px')
  • horizontalMargin - Horizontal offset as a CSS value (e.g., '16px')
  • zIndex - CSS z-index value
let oneToOneEmbed = new BambuserOneToOneEmbed({
  getMinimizedWidgetStyle: function() {
    return {
      position: 'bottom-right',
      verticalMargin: '20px',
      horizontalMargin: '20px',
      zIndex: '1000'
    };
  }
});

Overlay Widget Options​

The following options are specific to the Overlay Widget (OLW) functionality. For more detailed information about configuring and using the Overlay Widget, see the Overlay Widget documentation.

smart trigger​

To enable the Overlay Widget, include the 'smart' trigger type in the triggers array.

let oneToOneEmbed = new BambuserOneToOneEmbed({
  triggers: [
    'smart' // Activate overlay widget
  ]
});

smartVariantOverride​

Choose the overlay widget variant: 'Video', 'Side dock', or 'Avatar'.

  • Value type: string
let oneToOneEmbed = new BambuserOneToOneEmbed({
  triggers: [
    'smart' // Activate overlay widget
  ],
  smartVariantOverride: 'Side dock'
});

popupTimeoutSeconds​

  • Default: 60

  • Value type: number

Define how many seconds before the overlay widget appears.

let oneToOneEmbed = new BambuserOneToOneEmbed({
  triggers: [
    'smart' // Activate overlay widget
  ],
  smartVariantOverride: 'Side dock',
  popupTimeoutSeconds: 5 // Appears after 5 seconds
});

getOverlayOffsets​

  • Value type: function
  • Argument: position<string>
    • Possible positions: 'bottom-left', 'bottom-right', 'docked_left', 'docked_right'

Dynamic positioning function for the overlay widget.

// Example function to calculate offsets based on device type
function calculateOLWOffsets(position) {
  const isMobile = document.body.classList.contains('mobile');
  const yOffset = isMobile ? '64px' : '16px';
  
  return {
    x: '16px',
    y: yOffset,
    zIndex: '1000'
  };
}

let oneToOneEmbed = new BambuserOneToOneEmbed({
  getOverlayOffsets: calculateOLWOffsets // Pass the function here
});

Events​

The embed API provides events that you can listen to for customizing widget behavior.

Event Subscription​

To subscribe to an event, use the on method of the oneToOneEmbed instance:

let oneToOneEmbed = new BambuserOneToOneEmbed({
  orgId: 'YOUR_ORG_ID',
});

oneToOneEmbed.on(`${eventName}`, function(data) {
  // Handle the event here
});

Unsubscribing from Events​

To unsubscribe from an event, use the removeListener method:

function handleQueueOpen(data) {
  console.log('Queue opened:', data);
}

// Subscribe
oneToOneEmbed.on('queue-is-open', handleQueueOpen);

// Later, unsubscribe
oneToOneEmbed.removeListener('queue-is-open', handleQueueOpen);

Queue Events​

queue-is-open​

Fired when the queue opens or when the embed initializes and the queue is open.

Sample Event Data:

{
  isOpen: true,
  nextCloseTime: "2023-12-01T21:00:00.000Z"
}

Example:

oneToOneEmbed.on('queue-is-open', (data) => {
  // Use the event for your own purposes, for example enable a button to open the Call Widget when queue is open
  isOpen = data.isOpen;
  if (isOpen) {
    const myButton = document.getElementById("start-call-button");
    myButton.disabled = false;
  }
});

queue-is-closed​

Fired when the queue closes or when the embed initializes and the queue is closed.

Sample Event Data:

{
  isOpen: false,
  nextOpenTime: "2023-12-01T09:00:00.000Z"
}

Example:

oneToOneEmbed.on('queue-is-closed', (data) => {
  // Use the event for your own purposes, for example disable a button to open the Call Widget when queue is closed
  isOpen = data.isOpen;
  nextOpenTime = data.nextOpenTime;
  const myButton = document.getElementById("start-call-button");
  myButton.disabled = true;
  myButton.title = `The queue is currently closed and will open at ${new Date(nextOpenTime).toLocaleTimeString()}`;
});

agents-online​

Fired whenever the number of online agents changes.

Sample Event Data:

{
  numberOfAgentsOnline: 3,
  queueId: 'abc123'
}

Example:

oneToOneEmbed.on('agents-online', ({ numberOfAgentsOnline }) => {
  // Use the event for your own purposes, for example change some indicator text on your site
  document.getElementById("status").textContent = numberOfAgentsOnline < 1 ? "Unfortunately there are no agents online :(" : "Let's have a video call!";
});

queue-estimated-waiting-time​

Fired when there's a change to the queue's estimated waiting time.

Sample Event Data:

{
  estimatedWaitingTime: 120,
  agents: 2,
  place: 3,
  queueId: 'abc123'
}

Example:

oneToOneEmbed.on('queue-estimated-waiting-time', ({ estimatedWaitingTime }) => {
  // Use the event for your own purposes, for example change some indicator text on your site
  document.getElementById("waiting-time").textContent = `Estimated waiting time: ${estimatedWaitingTime}s`;
});

Tracking Events​

tracking-event​

Emitted for all tracking events including call events, product events, cart events, and GA4 ecommerce events. Listen to this for custom analytics integration.

Sample Event Data:

{
  eventName: 'event-name', // For Bambuser events
  eventData: { /* event data */ },
  event: 'ga4-event-name', // For GA4 events
  ecommerce: { /* ecommerce data */ }
}

Example:

oneToOneEmbed.on('tracking-event', (payload) => {
  if (payload.eventName) {
    // Handle Bambuser events
    console.log('Bambuser event:', payload.eventName, payload.eventData);
  } else if (payload.event) {
    // Handle GA4 events
    console.log('GA4 event:', payload.event, payload.ecommerce);
  }
});
Complete Event List

For a complete list of all available tracking events including call events (call_widget_opened, joined_queue, left_queue, call_started, call_transferred, call_ended, call_widget_closed), product events, cart events, and GA4 ecommerce events, see the Tracking Events documentation.

Product Events​

provide-product-data​

Emitted when an agent requests product data. You must handle this event to provide product information.

Event Data:

{
  products: [{
    ref: "product-reference-or-url",
    type: "url" | "product-reference" | "scanned-code",
    id: "bambuser-product-id"
  }]
}
Code Examples

For complete code examples and implementation details, see the Provide Product Data documentation.

provide-search-data​

Emitted when an agent performs a product search. You must handle this event to provide search results.

Event Data:

{
  query: "search-term",
  callback: function(results) { /* Call with array of product data */ }
}
Code Examples

For complete code examples and implementation details, see the Provide Search Data documentation.

Cart Events​

should-add-item-to-cart​

Emitted when an agent adds a product to the cart.

Event Data:

{
  sku: "product-sku",
  callback: function(success) { /* Call with true/false */ }
}

Example:

oneToOneEmbed.on('should-add-item-to-cart', (addedItem, callback) => {
  // Add the product to your native cart
  fetch('/api/cart/add', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ sku: addedItem.sku, quantity: 1 })
  })
  .then(() => callback(true))  // Success
  .catch(() => callback(false)); // Failure
});

should-update-item-in-cart​

Emitted when an agent modifies product quantity in the cart.

Event Data:

{
  sku: "product-sku",
  quantity: 2,
  callback: function(success) { /* Call with true/false */ }
}

Example:

oneToOneEmbed.on('should-update-item-in-cart', (updatedItem, callback) => {
  if (updatedItem.quantity > 0) {
    // Update quantity in your native cart
    fetch('/api/cart/update', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ sku: updatedItem.sku, quantity: updatedItem.quantity })
    })
    .then(() => callback(true))
    .catch(() => callback(false));
  } else {
    // Remove item from your native cart
    fetch('/api/cart/remove', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ sku: updatedItem.sku })
    })
    .then(() => callback(true))
    .catch(() => callback(false));
  }
});

goto-checkout​

Emitted when the customer clicks the checkout button.

Example:

oneToOneEmbed.on('goto-checkout', () => {
  // Redirect to your checkout page
  oneToOneEmbed.floatAbove('https://your-checkout-url-here');
});
oneToOneEmbed.on('goto-checkout', () => {
  // Redirect to your checkout page
  window.location.href = '/checkout';
});

Other Events​

goto-chat​

Emitted when the user chooses to switch to a chat experience from within the Calls Widget. This event can be used to integrate with a separate chat solution. The Calls Widget will close when this event is emitted.

Example:

oneToOneEmbed.on('goto-chat', () => {
  // Logic to open your chat widget
  myChatWidget.open();
});

Methods​

Calls Widget Control​

show()​

Programmatically start the Calls Widget.

oneToOneEmbed.show();

destroy()​

Programmatically closes the Calls Widget and remove it from the DOM.

oneToOneEmbed.destroy();

floatAbove(url)​

  • Requirement: Co-browsing must be enabled.
  • Parameters:
    • url (optional) - string - Absolute or relative URL to navigate to in co-browsing mode.

Programmatically minimizes the Calls Widget to float above the current page.

oneToOneEmbed.floatAbove();

If a URL is provided, the agent and customer will be navigated to that URL in co-browsing mode.

  • The URL must be on the same origin/domain as your embed landing page.
oneToOneEmbed.floatAbove('/some-page');

Queue Management​

areQueuesOpen()​

Returns a promise that resolves to queue status information.

tip

You can also listen to the queue-is-open and queue-is-closed events to get real-time updates whenever the queue status changes.

Return Value:

{
  isOpen: true,
  nextOpenTime: "2023-12-01T09:00:00.000Z",
  nextCloseTime: "2023-12-01T21:00:00.000Z"
}

Example:

oneToOneEmbed.areQueuesOpen().then(({ isOpen, nextOpenTime }) => {
  if (isOpen) {
    console.log('Queue is currently open!');
  } else {
    console.log(`Queue closed. Opens at: ${new Date(nextOpenTime).toLocaleString()}`);
  }
});

setQueue(queueTerm)​

Updates the queue for the widget.

Parameters:

  • queueTerm - string - Queue name, slug, or ID.
// Change to a different queue
oneToOneEmbed.setQueue('new-queue-id');

getNumberOfOnlineAgents(queueTerm)​

Returns a promise with the number of online agents for a specific queue.

tip

You can alternatively listen to the agents-online event to get real-time updates whenever the number of online agents changes.

Parameters:

  • queueTerm (optional) - string - Queue name, slug, or ID. If omitted, uses the configured default queue.

Return Value:

{
  numberOfAgentsOnline: 3,
  queueId: 'QUEUE_ID'
}

Example:

// Get agents online for configured queue
oneToOneEmbed.getNumberOfOnlineAgents().then(({ numberOfAgentsOnline }) => {
  console.log(`${numberOfAgentsOnline} agents are online`);
});

// Get agents online for a specific queue
oneToOneEmbed.getNumberOfOnlineAgents('support-queue').then(({ numberOfAgentsOnline }) => {
  console.log(`${numberOfAgentsOnline} agents are online in support queue`);
});

getEstimatedWaitingTime(queueTerm)​

Returns a promise with estimated waiting time information.

Parameters:

  • queueTerm (optional) - string - Queue name, slug, or ID. If omitted, uses the configured default queue.

Return Value:

{
  estimatedWaitingTime: 120,
  agents: 2,
  place: 3,
  queueId: 'QUEUE_ID'
}

Example:

oneToOneEmbed.getEstimatedWaitingTime().then(({ estimatedWaitingTime, place }) => {
  console.log(`You are #${place} in queue. Estimated wait: ${estimatedWaitingTime} seconds`);
});

Customer Data Management​

updateData(data)​

Updates customer data for the current session. If no data is provided, the data function (if configured) will be called again.

Parameters:

  • data (optional) - object - New customer data to set.
// Update with new data
oneToOneEmbed.updateData({
  externalId: 456,
  firstName: 'Jane',
  lastName: 'Smith'
});

// Refresh data from function
oneToOneEmbed.updateData();

setTrackingTags(tags)​

Sets custom tracking tags for the current session. These tags can be used for analytics and reporting.

Parameters:

  • tags - Array<{key: string, value: string | number | boolean}> - An array of key-value pairs.
    • A maximum of 20 tags is allowed.
    • The key must be a string.
    • Duplicate tracking tag keys are not allowed. If set the last one in the list will be used
    • The value can be a string, number, or boolean. String values are limited to 1KB.

Example:

oneToOneEmbed.setTrackingTags([
  { key: 'customer-segment', value: 'premium' },
  { key: 'has-purchased-before', value: true }
]);

Overlay Widget Control​

showOverlayWidget()​

Programmatically show the Overlay Widget.

hideOverlayWidget()​

Programmatically hide the Overlay Widget.

Product Data Management​

updateProduct(bambuserId, productFactory)​

Update product data for a specific product ID.

Parameters:

  • bambuserId - string - Bambuser generated product ID
  • productFactory - function - Function that is used to construct and return the product data object.
Code Examples

For complete code examples and implementation details, see the Provide Product Data documentation.

Custom Elements API​

Constants​

FLOATING_PLAYER_NAVIGATION_MODE​

Constants for configuring floating player navigation behavior. See floatingPlayer configuration option for details.

Values:

{
  IFRAME: 'iframe',  // Default - widget handles navigation automatically
  MANUAL: 'manual'   // Developer handles navigation manually (ideal for SPAs)
}

ELEMENTS​

  • Value:
{
  DROP_IN_CARD: 'drop-in-card',
  BOOKING_CARD: 'book-meeting-card',
}

Methods​

updateElement(id, state)​

Update the content or behavior of a customizable element.

Parameters:

  • id - Element ID from the ELEMENTS constant
  • state - Object with desired state or null to reset to default

State Fields:

  • disableCTA - Boolean to disable/enable the button
  • content - Object with text content:
    • title - Card title
    • subtitle - Card subtitle
    • buttonText - Button text

Example:

// Update drop-in card
window.oneToOneEmbed.updateElement(
  window.oneToOneEmbed.ELEMENTS.DROP_IN_CARD,
  {
    disableCTA: true,
    content: {
      subtitle: 'No agents available right now',
      buttonText: 'Try again later'
    }
  }
);
// Reset to default
window.oneToOneEmbed.updateElement(
  window.oneToOneEmbed.ELEMENTS.DROP_IN_CARD,
  null
);