Chatspark
⌘K

API Reference

v1
⌘K

Programmatic Widget Controls

Control the ChatSpark widget from your JavaScript: open, close, toggle, and reset the chat programmatically.

New ChatSpark API

The recommended API is window.ChatSpark, which provides a clean interface for controlling the widget after it loads:

javascript

// Wait for the widget to load, then use the API
if (window.ChatSpark) {
  window.ChatSpark.open();    // Open the chat
  window.ChatSpark.close();   // Close the chat
  window.ChatSpark.toggle();  // Toggle open/closed
  window.ChatSpark.reset();   // Reset conversation and optionally reopen
}

Open Widget on Button Click

Attach a click handler to any element to open the chat when the user interacts with your page:

html

<button id="open-chat-btn">Chat with us</button>

<script>
  document.getElementById('open-chat-btn').addEventListener('click', function() {
    if (window.ChatSpark) {
      window.ChatSpark.open();
    }
  });
</script>

Close Widget Programmatically

Close the chat from your code. For example, after a form submission or when navigating away:

javascript

// Close the chat after a successful lead capture
window.ChatSpark.on('lead-captured', function(data) {
  console.log('Lead captured:', data);
  window.ChatSpark.close();
});

Legacy API

For backward compatibility or multi-instance setups, the legacy API remains available:

javascript

// All widget instances, keyed by instance ID (default: 'default')
window.chatSparkInstances

// Open an instance (e.g. the default one)
const instance = window.chatSparkInstances['default'];
if (instance) {
  instance.updateProps({ toggle: true });  // Toggle open/closed
  instance.updateProps({ isOpen: true });  // Force open
  instance.updateProps({ isOpen: false }); // Force close
}

// Legacy helper: open and render a new widget
window.openChatSparkBot(
  chatbotId,
  isOpen = false,
  gaID = '',
  fullScreen = false,
  renderTag = 'body',
  triggerMessage = '',
  styles = { marginBottom: '20px', marginRight: '20px' },
  instanceId = null
);
Prefer the new API
Use window.ChatSpark when possible. The legacy API will continue to work but may change in future versions.

Trigger Elements

Add the class cs-trigger-agent or cs-trigger-chatbot to any element. Clicking it will open the widget and optionally send a trigger message:

html

<button class="cs-trigger-agent" data-trigger="I need help with pricing">
  Ask about pricing
</button>

<!-- With multiple instances, target a specific one -->
<button class="cs-trigger-agent" data-instance="helpcenter" data-trigger="Show me the docs">
  Open help center
</button>

Previous

Embed Guide

Next

Events