Web widget

Let visitors talk to your agent right on your website. The widget adds a button to your page; a click starts a voice call with the agent in the browser, with nothing to install. Only the websites you name can start calls.

Add the widget

1. 1
   Create the widget

   Open your agent in the dashboard, go to Phone & web, and choose Add to your website. Enter your website, for example https://example.com, and choose Create widget.

   Add more sites separated by commas. Entering example.com also allows www.example.com, and the other way round.

2. 2
   Style it

   Pick the position, colours, label and icon in the same dialog. The preview shows the result, and the code below it updates as you go.

3. 3
   Paste the code

   Copy the code for your kind of site and paste it into every page that should show the button. Calls connect once your agent is live.

<script src="https://cdn.kugelaudio.com/widget/v1/widget.js" data-agent="YOUR_WIDGET_ID" async></script>

'use client'

import { useEffect } from 'react'

export function KugelAudioWidget() {
  useEffect(() => {
    if (document.getElementById('kugelaudio-widget')) return
    const script = document.createElement('script')
    script.id = 'kugelaudio-widget'
    script.src = 'https://cdn.kugelaudio.com/widget/v1/widget.js'
    script.async = true
    script.dataset.agent = 'YOUR_WIDGET_ID'
    document.body.appendChild(script)
  }, [])

  return null
}

Copy the code from the dashboard rather than from this page: it carries your widget's id and any other attribute your widget needs.

• HTML works on any site, including WordPress: paste the tag before </body>, or in your theme's footer.
• React works with Next.js, Vite and Create React App. Render <KugelAudioWidget /> once, for example in your root layout. It adds the script a single time, however often it mounts.

Options

Each option is a data-* attribute on the script tag. The dashboard writes only the ones you changed; an attribute you leave out keeps its default. data-title has no setting in the dashboard: add it to the tag yourself. To pass context about the page to the agent, see Tell the agent where a call comes from.

Place the button yourself

With data-position="inline" the widget does not float over your page. It draws the button into every element marked data-kugelaudio-widget, so put one where the button belongs:

<script src="https://cdn.kugelaudio.com/widget/v1/widget.js" data-agent="YOUR_WIDGET_ID" data-position="inline" async></script>

<div data-kugelaudio-widget></div>

The React component renders that element itself; place <KugelAudioWidget /> where the button should appear.

Start a call from your own button

The widget is a <kugelaudio-agent> element on your page. Its start() method starts a call, as a click on the widget's button does, and end() hangs up. Call start() from a click: a browser lets a page use the microphone and play sound only after the visitor clicks, so no page can start a call on its own.

<button type="button" id="talk" disabled>Talk to us</button>

<script>
  const talk = document.getElementById('talk')
  customElements.whenDefined('kugelaudio-agent').then(() => { talk.disabled = false })
  talk.addEventListener('click', () => document.querySelector('kugelaudio-agent')?.start())
</script>

The button turns on once the widget's script has loaded. The call panel still opens from the widget's own button, which stays on the page.

Tell the agent where a call comes from

Two attributes and a property pass context about the page to the agent, so it knows, for example, which event a visitor is calling about or who is logged in, without asking. The dashboard has no setting for them: add them to your page yourself.

• data-context is a JSON object written into the tag, such as data-context='{"page":"pricing"}'.
• data-context-params names query parameters of the page's address to copy in, separated by commas. With data-context-params="event,ref", a visitor on https://example.com/call?event=webinar-11-04&ref=newsletter brings event and ref along. The widget reads only the parameters you name, never the rest of the address.
• The widget's context property sets that JSON object from your page's script, for what the page learns after it loads, such as who has logged in: widget.context = { email: user.email }, where widget is document.querySelector('kugelaudio-agent'). The next call to start carries it in place of the tag's data-context ({ ...widget.context, email: user.email } keeps both). It stays in the page's memory and is never written into its HTML, so a session recording, which captures the HTML, does not capture the email. null clears it, and data-context applies again.

<script src="https://cdn.kugelaudio.com/widget/v1/widget.js"
  data-agent="YOUR_WIDGET_ID"
  data-context='{"page":"pricing"}'
  data-context-params="event,ref"
  async></script>

A key in data-context or the context property wins over a parameter of the same name, and a parameter that is missing or empty is left out. The agent reads each key as client.<key>, for example client.event, from the start of the call, so its greeting can already use it. The webinar recipe shows the agent's side.

The limits:

• At most 16 keys. A key starts with a letter and has at most 40 letters, digits and underscores.
• A value is a string of at most 256 characters, a number or a boolean. The agent reads a number or a boolean as text, for example "120".
• All of it together fits in 8,000 bytes of JSON. Sixteen values of 256 letters and digits fit; long values in other scripts may not.
• When the context breaks a limit or data-context is not valid JSON, the widget writes the reason to the browser console and starts the call without context. The visitor still reaches the agent.

Anyone can change a page's address or what its script sets, so treat the context as a hint from the page: use it to prefill and to skip questions, never as proof of who the visitor is or to unlock their account's data. Put no email address, name or other personal detail into a link: use an id that means something only to you, such as webinar-11-04. A page that knows its logged-in visitor passes those through the context property instead, as in this recipe.

The KugelAudio badge

The widget shows a small KugelAudio badge. On plans that include it, switch on Hide KugelAudio badge where you style the widget in the dashboard; there is no attribute for it.

Which sites can start calls

A call starts only from a site on the widget's list. A page on any other site that copies your code gets no call. To add a site later, create another widget for it on Phone & web.

Next steps