Widget Control

The HelpKite JavaScript embed script provides simple methods to control your chat widget's visibility and state programmatically. This gives you complete control over when and how users interact with your AI agent.

Understanding Widget Controls

The HelpKite widget has two separate control systems:

Widget Visibility

Show/hide the chat button

Controls whether the floating chat button appears on your page at all.

showWidget() / hideWidget()

Chat State

Open/close the chat window

Controls whether the chat conversation window is expanded or collapsed.

open() / close() / toggle()

Control Methods Comparison

MethodWhat it doesWhen to use
showWidget()Makes the floating button visible on the pageShow widget after user scrolls, on specific pages, or after delay
hideWidget()Completely hides the button (and closes chat if open)Hide on checkout, payment pages, or where chat shouldn't appear
open()Expands the chat window (button remains visible)Open chat from custom "Contact Us" button, auto-open for new users
close()Collapses the chat window (button still visible)Close chat programmatically, after form submission
toggle()Switches between open/closedCustom toggle buttons

Basic Usage

Widget Visibility Controls

Show or hide the chat button on your page

// Show the widget button (makes it appear on page)
HelpKite('showWidget');

// Hide the widget button completely (also closes chat)
HelpKite('hideWidget');

Chat Window Controls

Open or close the chat conversation window

// Open the chat window
HelpKite('open');

// Close the chat window
HelpKite('close');

// Toggle between open/closed
HelpKite('toggle');

// Legacy aliases (still work)
HelpKite('openChat');  // Same as 'open'
HelpKite('closeChat'); // Same as 'close'

Real-World Use Cases

Hide widget on checkout/payment pages

const pathname = window.location.pathname;
if (pathname === '/checkout' || pathname === '/payment') {
  HelpKite('hideWidget'); // Button disappears completely
}

Open chat from a custom button

<button onclick="HelpKite('open')">
  Contact Support
</button>

Show widget after user scrolls

window.addEventListener('scroll', () => {
  if (window.scrollY > 500) {
    HelpKite('showWidget'); // Button appears after scroll
  }
});

Auto-open chat for new users

HelpKite('onReady', function() {
  if (isFirstTimeUser()) {
    HelpKite('open'); // Opens chat automatically
  }
});

Open chat when user encounters an error

function handleError(errorType) {
  console.log(`User encountered error: ${errorType}`);
  HelpKite('open'); // Provide immediate help
}

Contextual help based on page

HelpKite('onReady', function() {
  const currentPage = window.location.pathname;

  if (currentPage === '/pricing') {
    // Auto-show widget on pricing page
    HelpKite('showWidget');
  } else if (currentPage === '/support') {
    // Auto-open chat on support page
    HelpKite('open');
  }
});

Event Listeners

Listen for widget events to customize behavior and track user interactions:

// Widget is ready and initialized
HelpKite('onReady', function() {
  console.log('HelpKite widget is ready!');
});

// Chat was opened
HelpKite('onOpen', function() {
  console.log('Chat opened');
  // Track with analytics
  if (typeof gtag !== 'undefined') {
    gtag('event', 'chat_opened', {
      event_category: 'support'
    });
  }
});

// Chat was closed
HelpKite('onClose', function() {
  console.log('Chat closed');
});

// User sent a message
HelpKite('onMessageSent', function(data) {
  console.log('User sent:', data);
});

// AI replied
HelpKite('onMessageReceived', function(data) {
  console.log('AI replied:', data);
});

Best Practices

Always use onReady

Wait for the widget to be ready before calling control methods. This ensures all functionality is loaded.

Debounce rapid calls

Avoid rapid open/close calls that can cause UI glitches. Add delays between actions if triggered by scroll or other frequent events.

Contextual timing

Open chat at relevant moments, not randomly. Consider user intent and current page context.

Respect user preference

Remember if user has dismissed chat recently. Don't repeatedly auto-open if they've closed it.

Don't interrupt workflows

Be careful about auto-opening during critical user tasks like checkout or form completion.

Track usage

Use event listeners to understand how users interact with the widget and optimize placement/timing.

Complete Integration Example

Full implementation with multiple triggers

<!-- Your HTML -->
<button id="contact-btn">Contact Us</button>
<button id="help-btn">Help</button>

<!-- HelpKite Widget Script -->
<script type="text/javascript">
  window.helpkiteSettings = {
    agentId: 'YOUR_AGENT_ID',
    showWidget: false  // Hide initially
  };
</script>
<script type="text/javascript" src="https://embed.helpkite.com/sdk"></script>

<script type="text/javascript">
  // Wait for widget to be ready
  HelpKite('onReady', function() {
    console.log('Widget ready!');

    // Contact button - show and open chat
    document.getElementById('contact-btn').onclick = function() {
      HelpKite('showWidget');
      HelpKite('open');
    };

    // Help button - just show widget
    document.getElementById('help-btn').onclick = function() {
      HelpKite('showWidget');
    };

    // Show after 30 seconds for engaged users
    setTimeout(function() {
      HelpKite('showWidget');
    }, 30000);

    // Hide on specific pages
    const pathname = window.location.pathname;
    if (pathname === '/checkout' || pathname === '/payment') {
      HelpKite('hideWidget');
    }
  });

  // Track events
  HelpKite('onOpen', function() {
    console.log('User opened chat');
  });

  HelpKite('onMessageSent', function(data) {
    console.log('User sent message:', data);
  });
</script>

Troubleshooting

Methods not working

• Ensure you're calling methods inside the onReady callback

• Check that the widget has loaded successfully (no console errors)

• Verify script order (settings before SDK script)

Widget not appearing

• Check that agentId is correct

• If using showWidget: false, you must call showWidget() to make it visible

• Check browser console for errors

Events not firing

• Make sure event listeners are added before the events occur

• Check that callback functions are defined properly

• Verify widget is actually opening/closing (check the DOM)