Skip to content
Nexvio Logo Nexvio.ai Docs

Control Widget

Control Widget

Overview

The Nexvio.ai JavaScript SDK provides methods to programmatically control your chatbot widget. This allows you to open, close, show, hide, and customize the widget based on user actions or other events on your website.

Basic Widget Controls

Opening and Closing the Widget

You can programmatically open and close the chatbot widget:

// Open the chatbot widget
window.nexvio('open');


// Close the chatbot widget
window.nexvio('close');


// Toggle the widget (open if closed, close if open)
window.nexvio('toggle');

Showing and Hiding the Widget

You can control the visibility of the widget:

// Hide the chatbot widget completely
window.nexvio('hide');


// Show the chatbot widget (makes it visible again after hiding)
window.nexvio('show');

The difference between close and hide:

  • close closes the chatbot window but keeps the launcher button visible
  • hide completely removes the chatbot from view (both window and launcher)

Advanced Widget Controls

Setting the Position

You can change the position of the widget:

// Position the widget in the bottom-right corner (default)
window.nexvio('setPosition', 'bottom-right');


// Position the widget in the bottom-left corner
window.nexvio('setPosition', 'bottom-left');


// Position the widget in the top-right corner
window.nexvio('setPosition', 'top-right');


// Position the widget in the top-left corner
window.nexvio('setPosition', 'top-left');

Customizing the Widget Size

You can adjust the size of the chatbot window:

// Set custom dimensions (width and height in pixels)
window.nexvio('setSize', {
  width: 400,  // in pixels
  height: 600  // in pixels
});


// Reset to default size
window.nexvio('resetSize');

Setting Custom Colors

You can update the widget color scheme programmatically:

// Change the primary color of the widget
window.nexvio('updateColors', {
  primary: '#FF5733',  // Main color for buttons and accents
  secondary: '#427bf5', // Secondary color for certain elements
  background: '#ffffff' // Background color of the chat window
});

Practical Examples

Example 1: Opening the Chatbot After Page Load Delay

// Wait 5 seconds after page load, then open the chatbot
document.addEventListener('DOMContentLoaded', function() {
  setTimeout(function() {
    window.nexvio('open');
  }, 5000); // 5000 milliseconds = 5 seconds
});

Example 2: Opening the Chatbot Based on Scroll Depth

// Open the chatbot when the user scrolls 70% down the page
window.addEventListener('scroll', function() {
  const scrollPosition = window.scrollY;
  const totalHeight = document.body.scrollHeight - window.innerHeight;
  const scrollPercentage = (scrollPosition / totalHeight) * 100;


  if (scrollPercentage > 70) {
    // Only open once
    if (!window.chatbotOpened) {
      window.nexvio('open');
      window.chatbotOpened = true;
    }
  }
});

Example 3: Showing/Hiding Based on URL Path

// Hide the chatbot on certain pages
function manageChatbotVisibility() {
  const currentPath = window.location.pathname;


  // Hide on checkout and login pages
  if (currentPath.includes('/checkout') || currentPath.includes('/login')) {
    window.nexvio('hide');
  } else {
    window.nexvio('show');
  }
}


// Run on page load
manageChatbotVisibility();


// For single-page applications, monitor URL changes
// This is a simplified example - use proper router events in production
window.addEventListener('popstate', manageChatbotVisibility);

Responding to User Inactivity

// Open the chatbot after 60 seconds of user inactivity
let inactivityTimer;


function resetInactivityTimer() {
  clearTimeout(inactivityTimer);
  inactivityTimer = setTimeout(function() {
    window.nexvio('open');
  }, 60000); // 60000 milliseconds = 60 seconds
}


// Reset the timer on user interaction
['mousemove', 'mousedown', 'keypress', 'scroll', 'touchstart'].forEach(function(event) {
  document.addEventListener(event, resetInactivityTimer, true);
});


// Start the timer when the page loads
resetInactivityTimer();

Controlling the Widget on Mobile Devices

Responsive behavior considerations:

// Adjust widget size based on screen width
function adjustChatbotSize() {
  if (window.innerWidth < 768) { // Mobile breakpoint
    window.nexvio('setSize', {
      width: 320,
      height: 500
    });
  } else { // Desktop
    window.nexvio('setSize', {
      width: 400,
      height: 600
    });
  }
}


// Run on page load
adjustChatbotSize();


// Run when window is resized
window.addEventListener('resize', adjustChatbotSize);

Combining with Event Listeners

For more advanced use cases, you can combine widget controls with event listeners:

// Open the chatbot when a specific button is clicked
document.getElementById('support-button').addEventListener('click', function() {
  window.nexvio('open');
});


// Listen for chatbot open events
window.nexvio('on', 'open', function() {
  console.log('Chatbot was opened');
  // Track analytics event
  if (typeof gtag === 'function') {
    gtag('event', 'chatbot_opened');
  }
});


// Listen for chatbot close events
window.nexvio('on', 'close', function() {
  console.log('Chatbot was closed');
});

Widget Visibility on Page Navigation

For single-page applications:

// Function to update chatbot visibility based on route
function updateChatbotOnRouteChange() {
  const currentPath = window.location.pathname;


  // Show or hide based on path
  if (currentPath === '/help' || currentPath === '/support') {
    // Auto-open on help/support pages
    window.nexvio('show');
    window.nexvio('open');
  } else if (currentPath === '/checkout') {
    // Hide completely on checkout
    window.nexvio('hide');
  } else {
    // Default: show but closed
    window.nexvio('show');
    window.nexvio('close');
  }
}


// For most single-page application frameworks,
// you would hook this into your router's navigation events

Tips and Best Practices

  1. Avoid Disrupting User Flow: Don’t open the chatbot at crucial moments like when users are filling out forms.

  2. Mobile Considerations: Be extra careful with size and positioning on mobile devices to avoid obscuring content.

  3. User Preferences: Consider storing the user’s preference (like if they manually closed the widget) in localStorage and respecting it on subsequent visits.

  4. Performance: Avoid making frequent or rapid changes to the widget as it may impact page performance.

  5. Combine with Analytics: Track when and why your widget is being shown, opened, or used to optimize its implementation.

// Example of respecting user preference
window.nexvio('on', 'close', function() {
  // Store that user manually closed the widget
  localStorage.setItem('chatbotClosed', 'true');
});


// On page load
document.addEventListener('DOMContentLoaded', function() {
  if (localStorage.getItem('chatbotClosed') !== 'true') {
    // Only auto-open if user didn't manually close it before
    setTimeout(function() {
      window.nexvio('open');
    }, 3000);
  }
});