Widget JavaScript API

Control the embedded Kodda chat widget programmatically from your website

Installation

No package required — the API is included with the embed script

When you embed the Kodda widget on your site, a global window.Kodda object is automatically available. No extra npm install needed.

<script
  src="https://kodda.dev/widget/embed.js"
  data-bot-id="YOUR_BOT_ID"
  async
></script>

Control Methods

All methods return window.Kodda for chaining, except isOpen()

open()Open the chat widget panel.

Kodda.open();

close()Close the chat widget panel.

Kodda.close();

toggle()Toggle the chat widget open or closed.

Kodda.toggle();

send(text)Open the widget and immediately send a message.

Kodda.send("How do I reset my password?");

setText(text)Pre-fill the input field without opening the widget or sending.

Kodda.setText("How do I reset my password?");

submit()Send whatever text is currently in the input field.

Kodda.setText("Hello!").submit();

clear()Clear the current conversation history.

Kodda.clear();

isOpen()Returns true if the widget is currently open.

const open = Kodda.isOpen();

Events

Listen to widget lifecycle events

readyWidget has finished loading and is ready to receive commands

openWidget panel was opened

closeWidget panel was closed

// Subscribe
const off = Kodda.on('ready', () => {
  console.log('Widget is ready');
});

// Unsubscribe
off();

// Or use off()
const handler = () => console.log('opened');
Kodda.on('open', handler);
Kodda.off('open', handler);

Usage Examples

Trigger from a custom button

<button onclick="Kodda.open().setText('I need help with billing').submit()">
  Get Billing Help
</button>

Pre-fill context from your app (React)

useEffect(() => {
  if (typeof window.Kodda !== 'undefined') {
    window.Kodda.setText(`Order #${orderId} — I have a question`);
  }
}, [orderId]);

Auto-open after user scrolls

window.addEventListener('scroll', () => {
  if (window.scrollY > 500 && !Kodda.isOpen()) {
    Kodda.open();
  }
});