Widget API Reference

The LeadJot Widget SDK provides a JavaScript API that allows you to programmatically control the chatbot widget on your website. Access it via the global window.lj object after the widget has loaded.

API Reference

Methods

window.lj.show()

Shows the widget trigger button if it was previously hidden.

window.lj.show();

window.lj.hide()

Hides the widget trigger button, making it invisible to users.

window.lj.hide();

window.lj.open()

Opens the chat window if it's currently closed.

window.lj.open();

window.lj.close()

Closes the chat window if it's currently open.

window.lj.close();

window.lj.toggle()

Toggles the chat window open/closed state.

window.lj.toggle();

window.lj.on(event, callback)

Subscribe to widget events. Returns an unsubscribe function.

Parameters:

• event (string) - The event name to listen for
• callback (function) - Function to call when the event occurs

Returns: () => void - Unsubscribe function

Available Events:

• "show" - Fired when the widget is shown
• "hide" - Fired when the widget is hidden
• "open" - Fired when the chat window opens
• "close" - Fired when the chat window closes
• "toggle" - Fired when the widget state is toggled

// Listen to open events
const unsubscribe = window.lj.on("open", () => {
  console.log("Chat window opened!");
  // Your custom logic here
});

// Later, unsubscribe when no longer needed
unsubscribe();

Usage Examples

Opening Chat on Button Click

document.getElementById("open-chat-btn").addEventListener("click", () => {
  window.lj.open();
});

Hiding Widget on Specific Pages

if (window.location.pathname === "/checkout") {
  window.lj.hide();
}

Tracking Widget Events

window.lj.on("open", () => {
  // Track chat opened event in analytics
  analytics.track("chat_opened");
});

window.lj.on("close", () => {
  // Track chat closed event
  analytics.track("chat_closed");
});

Conditional Widget Display

// Only show widget to logged-in users
if (userIsLoggedIn()) {
  window.lj.show();
} else {
  window.lj.hide();
}

Queued Calls (Before Widget Loads)

If you call SDK methods before the widget has loaded, calls are automatically queued and executed once the widget initializes:

// These will work even if called before the widget script loads
window.lj.hide();
window.lj.on("open", () => console.log("Chat opened"));

// Widget will process these calls when it initializes

Widget Configuration

The widget automatically fetches configuration from your chatbot settings, including:

• Display name
• Initial messages
• Suggested messages
• Input placeholder text
• Theme (light/dark)
• Colors (primary color, chat icon color)
• Icon alignment (left/right)
• Custom icons (profile icon, chat icon)
• Branding settings

These settings are configured in your LeadJot dashboard and don't require code changes.

Best Practices

if (typeof window.lj !== "undefined") {
  window.lj.open();
} else {
  console.warn("LeadJot widget not loaded yet");
}

Event Cleanup

Always unsubscribe from events when your component unmounts or when you no longer need them:

let unsubscribe;

// In your component
useEffect(() => {
  unsubscribe = window.lj?.on("open", handleOpen);
  return () => {
    unsubscribe?.();
  };
}, []);

Error Handling

The SDK methods are safe to call even if the widget hasn't initialized. Calls made before initialization are queued automatically.

Troubleshooting

Widget API Not Available

If window.lj is undefined:

• Ensure the widget script has loaded
• Check that you're using the correct chatbot ID
• Verify the script tag is placed before your code runs

Events Not Firing

• Ensure you're subscribing after the widget has initialized
• Check browser console for errors
• Verify event names match exactly (case-sensitive)

Widget Not Appearing

• Check that window.lj.show() has been called (widget may be hidden by default)
• Verify your chatbot ID is correct
• Check browser console for loading errors