Widget JavaScript API

Widget JavaScript API

SimpleChat provides a powerful JavaScript API to control the chat widget programmatically. This API follows industry-standard patterns for maximum flexibility and ease of integration.

Quick StartHide Launcher & Use Custom Button

<script
  src="https://YOUR_BOT_ID.p.simplechat.bot/js/simple-chat-premium.min.js"
  data-chat-id="YOUR_BOT_ID"
  data-start-hidden="true"
  async>
</script>

<button onclick="simpleChatWidget.open()">Chat with us</button>

Auto-bind to Existing Button

<script
  src="https://YOUR_BOT_ID.p.simplechat.bot/js/simple-chat-premium.min.js"
  data-chat-id="YOUR_BOT_ID"
  data-custom-button=".my-chat-btn"
  async>
</script>

<button class="my-chat-btn">Start Chat</button>

Data Attributes

Attribute	Type	Default	Description
data-chat-id	string	required	Your bot ID (e.g., bot_xxx)
data-start-hidden	boolean	false	Hide the launcher bubble on load
data-custom-button	string	-	CSS selector to auto-bind a custom button

JavaScript API Reference

The window.simpleChatWidget object is available immediately when the script loads. Commands called before the widget is fully ready are automatically queued and executed when ready.

Chat Window Control

Method	Returns	Description
open()	void	Open the chat window
close()	void	Close the chat window
toggle()	void	Toggle open/closed state
isOpen()	boolean	Check if chat is open

Example:

// Open chat when user scrolls to bottom
window.addEventListener('scroll', () => {
  if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 100) {
    simpleChatWidget.open();
  }
});

Launcher Control

Method	Returns	Description
show()	void	Show the launcher bubble
hide()	void	Hide the launcher bubble
isVisible()	boolean	Check if launcher is visible

Example:

// Show launcher after 5 seconds
setTimeout(() => {
  simpleChatWidget.show();
}, 5000);

Ready Detection

The API is available immediately, but if you need to know when the widget is fully loaded:

Method 1: DOM Event

document.addEventListener('simplechat:ready', function(e) {
  console.log('Widget ready!', e.detail.chatId);
  // Safe to call any method here
});

Method 2: onReady Callback

window.simpleChatConfig = {
  chatId: 'YOUR_BOT_ID',
  onReady: function() {
    console.log('Widget is ready!');
  }
};

Method 3: Widget Event

simpleChatWidget.on('ready', function() {
  console.log('Widget ready via event system!');
});

Note: You don't need to wait for ready to call methods like open() or hide(). Commands are automatically queued and executed when the widget is ready.

Event System

Listen to widget events with on() and off() methods.

Event	Data	Description
ready	{chatId}	Widget fully loaded and ready
chat:open	-	Chat window opened
chat:close	-	Chat window closed
launcher:show	-	Launcher became visible
launcher:hide	-	Launcher became hidden
message:sent	{text}	User sent a message
message:received	{text}	Received a message

Example:

// Track chat opens in analytics
simpleChatWidget.on('chat:open', () => {
  analytics.track('Chat Opened');
});

// Show notification badge when chat is hidden
simpleChatWidget.on('message:received', (data) => {
  if (!simpleChatWidget.isOpen()) {
    showNotificationBadge();
  }
});

// Remove listener
const handler = () => console.log('opened');
simpleChatWidget.on('chat:open', handler);
simpleChatWidget.off('chat:open', handler);

Advanced Configuration

For full control, use window.simpleChatConfig before the script loads:

<script>
  window.simpleChatConfig = {
    chatId: 'YOUR_BOT_ID',
    startHidden: true,
    customButton: '.chat-trigger',
    onReady: function() {
      console.log('Widget ready!');
    }
  };
</script>
<script src="https://YOUR_BOT_ID.p.simplechat.bot/js/simple-chat-premium.min.js" async></script>

Shadow DOM Isolation

The widget uses Shadow DOM for complete CSS isolation. This means:

• Your website's styles won't affect the widget
• The widget's styles won't leak to your website
• startHidden: true renders nothing visible until open() is called
• Safe to use on any website without conflicts

Browser Support

The widget works in all modern browsers:

• Chrome 53+
• Firefox 63+
• Safari 10+
• Edge 79+

Need Help?

• Contact Support
• View Pricing