Skip to main content

Control Widget Visibility

This guide covers how to dynamically control the visibility and availability of the Calls Widget's drop-in option and the Overlay Widget (OLW) based on real-time conditions such as agent availability and queue status.

Disable the drop-in button​

Disable the drop-in button when no agents are online​

Use the agents-online event together with the updateElement() method to disable the drop-in button when no agents are available, and re-enable it when they come back online.

window.onBambuserOneToOneReady = function (BambuserOneToOneEmbed) {
  var oneToOneEmbed = new BambuserOneToOneEmbed({
    orgId: 'YOUR_ORG_ID',
  });

  oneToOneEmbed.on('agents-online', function ({ numberOfAgentsOnline }) {
    if (numberOfAgentsOnline < 1) {
      // No agents online — disable the drop-in button
      oneToOneEmbed.updateElement(
        BambuserOneToOneEmbed.ELEMENTS.DROP_IN_CARD,
        {
          disableCTA: true,
          content: {
            subtitle: 'No agents are available right now',
            buttonText: 'Unavailable',
          },
        }
      );
    } else {
      // Agents are back online — reset to default
      oneToOneEmbed.updateElement(
        BambuserOneToOneEmbed.ELEMENTS.DROP_IN_CARD,
        null
      );
    }
  });
};

This keeps the drop-in card visible but greys out the button and updates the text to inform the customer. Passing null resets the card to its default state.

tip

You can customize the subtitle and buttonText values to match your brand's tone and language. See the updateElement() state fields for all available content properties.

Disable the drop-in button when the queue is closed​

You may also want to disable the drop-in button when the queue is closed, regardless of agent availability. This example uses the queue-is-open and queue-is-closed events alongside agents-online:

window.onBambuserOneToOneReady = function (BambuserOneToOneEmbed) {
  var oneToOneEmbed = new BambuserOneToOneEmbed({
    orgId: 'YOUR_ORG_ID',
  });

  var agentsOnline = 0;
  var queueOpen = true;

  function updateDropInState() {
    if (agentsOnline < 1 || !queueOpen) {
      oneToOneEmbed.updateElement(
        BambuserOneToOneEmbed.ELEMENTS.DROP_IN_CARD,
        {
          disableCTA: true,
          content: {
            subtitle: !queueOpen
              ? 'The queue is currently closed'
              : 'No agents are available right now',
            buttonText: 'Unavailable',
          },
        }
      );
    } else {
      oneToOneEmbed.updateElement(
        BambuserOneToOneEmbed.ELEMENTS.DROP_IN_CARD,
        null
      );
    }
  }

  oneToOneEmbed.on('agents-online', function (data) {
    agentsOnline = data.numberOfAgentsOnline;
    updateDropInState();
  });

  oneToOneEmbed.on('queue-is-open', function () {
    queueOpen = true;
    updateDropInState();
  });

  oneToOneEmbed.on('queue-is-closed', function () {
    queueOpen = false;
    updateDropInState();
  });
};

Hide the drop-in option entirely​

If you prefer to completely remove the drop-in option from the widget's start screen rather than showing a disabled button, use the dropInEnabled configuration option.

Since dropInEnabled is set at initialization time, you need to check conditions before creating the embed instance. Use getNumberOfOnlineAgents() or areQueuesOpen() for this:

window.onBambuserOneToOneReady = function (BambuserOneToOneEmbed) {
  // Create a temporary instance to check agent availability
  var tempInstance = new BambuserOneToOneEmbed({
    orgId: 'YOUR_ORG_ID',
    dropInEnabled: false
  });
};

Show or hide the Overlay Widget based on conditions​

The Overlay Widget (OLW) can be programmatically shown or hidden using the showOverlayWidget() and hideOverlayWidget() methods. This lets you control when the OLW appears based on any custom condition.

info

To use the OLW, you must first enable it by including the 'smart' trigger in your configuration. See the Overlay Widget documentation for full setup instructions.

Hide the OLW when no agents are online​

window.onBambuserOneToOneReady = function (BambuserOneToOneEmbed) {
  var oneToOneEmbed = new BambuserOneToOneEmbed({
    orgId: 'YOUR_ORG_ID',
    triggers: ['smart', 'connect-link'],
    smartVariantOverride: 'Video',
  });

  // Expose to window for programmatic control
  window.oneToOneEmbed = oneToOneEmbed;

  oneToOneEmbed.on('agents-online', function ({ numberOfAgentsOnline }) {
    if (numberOfAgentsOnline < 1) {
      oneToOneEmbed.destroy(); // Completely remove the widget if no agents are online
    }
  });
};

Hide the OLW when the queue is closed​

oneToOneEmbed.on('queue-is-closed', function () {
  oneToOneEmbed.destroy(); // Completely remove the widget if the queue is closed
});

oneToOneEmbed.on('queue-is-open', function () {
  oneToOneEmbed.showOverlayWidget();
});
tip

You can also request the OLW to be automatically hidden when no agents are online as an organization-level setting. Contact your Bambuser representative to enable this. The programmatic approach above gives you more fine-grained control on the client side.