JavaScript API

Overview

Once the widget script has loaded, it exposes a small API on window.CallKaro. Use it to open the widget from your own buttons, close it programmatically, and run your own code when a conversation starts or ends. Nothing here is required. If you only want the launcher in the corner, the snippet on its own is enough.

CallKaro.open()                       // open the conversation panel
CallKaro.close()                      // close it
CallKaro.on('start', data => { ... }) // listen for events
CallKaro.widgetId                     // the id from your script tag

The snippet uses defer, so window.CallKaro does not exist while your page is still parsing. Any code that touches it must wait. The simplest reliable approach is to check inside the handler that needs it, because by the time a visitor clicks something the widget has long since loaded:

document.getElementById('talk-to-us').addEventListener('click', () => {
  if (window.CallKaro) CallKaro.open()
})

If you need to run code as soon as the widget is available — to attach event listeners, for example — poll briefly:

function whenCallKaroReady(fn) {
  if (window.CallKaro) return fn(window.CallKaro)
  const timer = setInterval(() => {
    if (window.CallKaro) {
      clearInterval(timer)
      fn(window.CallKaro)
    }
  }, 100)
  setTimeout(() => clearInterval(timer), 10000)  // give up after 10s
}

whenCallKaroReady(ck => {
  ck.on('start', () => console.log('conversation started'))
})

Do not call CallKaro.open() on page load to auto-open the widget. It works, but opening a voice panel before a visitor has asked for it is intrusive, and some browsers will block the microphone prompt because it did not follow a user gesture. Trigger it from a click instead.

Methods

CallKaro.open()

Opens the conversation panel and hides the launcher. Does nothing if the panel is already open. Use it to trigger the widget from your own call-to-action:

<button id="talk-to-us">Talk to us</button>

<script>
  document.getElementById('talk-to-us').addEventListener('click', () => {
    if (window.CallKaro) CallKaro.open()
  })
</script>

Opening the panel does not start a conversation. The visitor still presses Talk and grants microphone permission themselves.

CallKaro.close()

Closes the panel and restores the launcher. Does nothing if it is already closed.

CallKaro.close()

Closing the panel during an active conversation ends that conversation.

CallKaro.on(event, callback)

Registers a listener. Returns CallKaro, so calls can be chained:

CallKaro
  .on('open',  () => console.log('panel opened'))
  .on('start', () => console.log('conversation started'))
  .on('end',   () => console.log('conversation ended'))

You can register several listeners for the same event; all of them run. There is no way to remove a listener once added.

An error thrown inside your callback is caught and logged to the console — it will not break the widget.

CallKaro.widgetId

The widget id read from your script tag. Useful when the same analytics code runs on pages carrying different widgets.

console.log(CallKaro.widgetId)   // "wgt_a1b2c3d4"

Events

Event	Fires when	Payload
`open`	The panel opens, whether by click or `CallKaro.open()`	`{}`
`close`	The panel closes	`{}`
`ready`	The panel has loaded and fetched its configuration	`{ widgetId }`
`start`	A conversation begins	`{ state: 'start', sessionId }`
`end`	A conversation ends	`{ state: 'end' }`

ready fires after the panel is opened for the first time, not on page load — the panel is only loaded when somebody opens it.

Examples

Track engagement in your analytics

whenCallKaroReady(ck => {
  ck.on('open',  () => gtag('event', 'widget_opened'))
  ck.on('start', d => gtag('event', 'voice_conversation_started', {
    session_id: d.sessionId
  }))
  ck.on('end',   () => gtag('event', 'voice_conversation_ended'))
})

Measure how long conversations last

whenCallKaroReady(ck => {
  let startedAt = null
  ck.on('start', () => { startedAt = Date.now() })
  ck.on('end', () => {
    if (!startedAt) return
    const seconds = Math.round((Date.now() - startedAt) / 1000)
    console.log('conversation lasted', seconds, 'seconds')
    startedAt = null
  })
})

whenCallKaroReady(ck => {
  const bubble = document.querySelector('.my-chat-bubble')
  ck.on('open',  () => { bubble.style.display = 'none' })
  ck.on('close', () => { bubble.style.display = '' })
})

React

import { useEffect } from 'react'

function TalkToUsButton() {
  useEffect(() => {
    if (!window.CallKaro) return
    window.CallKaro.on('start', () => {
      // your tracking here
    })
  }, [])

  return (
    <button onClick={() => window.CallKaro?.open()}>
      Talk to us
    </button>
  )
}

In React, register listeners once — for example in a top-level component. A listener added inside a component that mounts repeatedly will be registered again each time, and there is no way to remove it.

Limitations

Worth knowing before you build on this:

Listeners cannot be removed. There is no off() method.
No way to start a conversation from code. open() shows the panel; the visitor presses Talk. This is deliberate — browsers require a user gesture before granting microphone access.
No transcript access. The conversation text is not exposed to the host page. Read transcripts in Call History instead.
One widget per page. A second snippet on the same page is ignored, and CallKaro always refers to the first.

Need something else?

Tell us what you are trying to build and we will see what we can expose

Getting started

Pricing

Voice AI Agents

Chat Agents

AI FDE

AI Auditor

KPI Manager

Phone Numbers

Calls

Webhooks

Website Widget

Whatsapp (Facebook)

Integrations

Overview

Waiting For The Widget

Methods

CallKaro.open()

CallKaro.close()

CallKaro.on(event, callback)

CallKaro.widgetId

Events

Examples

Track engagement in your analytics

Measure how long conversations last

Hide your own chat bubble while the widget is open

React

Limitations

Need something else?

​Overview

​Waiting For The Widget

​Methods

​CallKaro.open()

​CallKaro.close()

​CallKaro.on(event, callback)

​CallKaro.widgetId

​Events

​Examples

​Track engagement in your analytics

​Measure how long conversations last

​Hide your own chat bubble while the widget is open

​React

​Limitations

Need something else?

Overview

Waiting For The Widget

Methods

CallKaro.open()

CallKaro.close()

CallKaro.on(event, callback)

CallKaro.widgetId

Events

Examples

Track engagement in your analytics

Measure how long conversations last

Hide your own chat bubble while the widget is open

React

Limitations