The `<agent-widget>` AI agent widget

A web component that puts a confcall AI agent on your page, as a text chat, a voice call, or both. It talks to the AI conference agent at agent.confcall.app and works in any framework.

What it is

<agent-widget> embeds an AI agent you configured in the Builder. It is different from the <conference-room> widget, which embeds a live room (people in a call). An agent inside a meeting is invited into a room and reached through <conference-room>; <agent-widget> is for talking to the agent directly.

Install

<script src="https://widget.confcall.app/agent-widget.umd.js"></script>

The script registers the agent-widget custom element. Load it before you use the element.

Text mode quick start

Text chat is the default. You need a config-id, the api-url, and an api-key (see Authentication).

<script src="https://widget.confcall.app/agent-widget.umd.js"></script>
<agent-widget
  config-id="YOUR_CONFIG_ID"
  api-url="https://agent.confcall.app"
  api-key="YOUR_API_KEY"
  title="Support"
></agent-widget>

Voice mode

Add voice-enabled together with signalr-url and agent-api-url. The widget then shows a microphone control. The browser asks for microphone permission when the user starts a call, or when your code calls startVoice().

<script src="https://widget.confcall.app/agent-widget.umd.js"></script>
<agent-widget
  config-id="YOUR_CONFIG_ID"
  api-url="https://agent.confcall.app"
  api-key="YOUR_API_KEY"
  title="Support"
  voice-enabled
  signalr-url="https://meet.confcall.app"
  agent-api-url="https://agent.confcall.app"
></agent-widget>

Voice needs a page served over HTTPS (or localhost) so the browser allows microphone access.

Hybrid mode

With the voice snippet above, the same widget offers both text and voice and the user switches between them. widget.widgetMode reports chat, voice or hybrid, and the agent-widget-mode-changed event fires when it changes.

Authentication

There are two ways to authenticate the widget:

Publishable API key (api-key). Keys start with pk_live_ or pk_test_ and are safe to put in page source. A pk_live_ key can be restricted to a list of allowed origins; requests from any other origin are rejected.
Short-lived JWT (auth-token). Mint a token on your server and pass it to the widget. Set auth-token before open when you set attributes from script.

A JWT needs these scopes, depending on the features you use:

Feature	Scope
Chat sessions	`use:chat-agent`
Voice calls	`use:voice-agent`
IVR config access	`read:ivr-config`

Find your config-id and create a key

In the Builder, open your agent and choose Embed. The dialog shows a ready-made snippet with your config-id filled in. Create a publishable key in the Builder's API keys page, add your site's origin to its allowed origins, and replace YOUR_API_KEY.

Attributes

Attribute	Required	Description
`config-id`	Yes	The agent configuration ID from the Builder.
`api-url`	Yes	Base URL of the chat API, `https://agent.confcall.app`.
`api-key`	One of `api-key` / `auth-token`	Publishable key (`pk_live_…` or `pk_test_…`).
`auth-token`	One of `api-key` / `auth-token`	Short-lived JWT sent as a Bearer token.
`tenant-id`	No	Tenant identifier (default `default`).
`title`	No	Header title (default `Chat`).
`agent-name`	No	Agent name shown in the header. Overrides the name saved in the Builder.
`agent-avatar`	No	Avatar image URL shown in the header. Overrides the avatar saved in the Builder.
`builder-url`	No	Builder base URL the widget reads saved branding from (default `https://builder.confcall.app`). Attributes on the tag always win over the saved branding.
`open`	No	Boolean. Show the widget on load.
`embedded`	No	Boolean. Fill the parent container instead of floating.
`voice-enabled`	No	Boolean. Enable voice calling.
`signalr-url`	With voice	Base URL of the SignalR server for voice signaling (e.g. `https://meet.confcall.app`). The widget appends the `/videohub` hub path itself — do not include it.
`agent-api-url`	With voice	Agent API URL used to invite the agent to the call.
`position`	No	`bottom-right` (default) or `bottom-left`.
`fab-icon`	No	URL of an image to use for the floating launcher button.
`visualization`	No	Voice-call visualizer: `aurora`, `constellation`, `halo` or `silk`. Default: `silk`. Unsupported values fall back to `silk`.
`mode`	No	Modality: `chat` (transcript and text input, no call button), `voice` (voice panel, no text input) or `mixed` (both). Default: `mixed` when `voice-enabled` is set, otherwise `chat`.
`lang`	No	Widget language: `en`, `es`, `fr`, `nl`, `de`, `hu`, `ro`, `sr`, `cs`, `sk` or `it`. Default: the visitor's browser language, falling back to English. Unsupported values are ignored.

Methods

Method	Description
`open()` / `close()`	Show or hide the widget.
`endSession()`	End and clear the current session.
`restartSession()`	End the current session and start a new one.
`startVoice()` / `endVoice()`	Start or end a voice call (needs `voice-enabled`).
`toggleVoice()` / `toggleMute()`	Toggle voice, or mute the microphone.

Events

Events are CustomEvents on the element; payloads are in e.detail.

Event	Fires when
`agent-widget-session-started`	A new session starts.
`agent-widget-session-restored`	A saved session is restored after a reload.
`agent-widget-session-ended`	The session ends.
`agent-widget-message-sent`	The user sends a message.
`agent-widget-message-received`	The agent replies.
`agent-widget-close`	The user closes the widget.
`agent-widget-voice-started`	A voice call starts.
`agent-widget-voice-ended`	A voice call ends.
`agent-widget-voice-status`	The voice status changes.
`agent-widget-mode-changed`	The widget mode changes.

Theming

Style the widget with CSS variables on the element:

agent-widget {
  --cw-primary-color: #2563eb;
  --cw-primary-hover: #1d4ed8;
  --cw-background: #ffffff;
  --cw-surface: #f1f5f9;
  --cw-text: #1e293b;
  --cw-text-muted: #64748b;
  --cw-border: #e2e8f0;
  --cw-radius: 12px;
}

Session persistence

The widget saves its session in localStorage under agent-widget-session-{config-id}, one per config-id. After a reload it restores the conversation until the session expires on the server. Call endSession() to clear it.

Troubleshooting

401 or "Origin not allowed": the page's origin is not in the key's allowed origins, or the key is wrong. Add the origin in the Builder, or check the key prefix and the token scopes.
Microphone blocked: allow microphone access for the site in the browser. The prompt appears only after a user gesture.
Mixed content: an HTTPS page cannot call http:// URLs. Use HTTPS for api-url, signalr-url and agent-api-url.
Voice does not connect: check that voice-enabled, signalr-url and agent-api-url are all set.
Nothing renders: load the script tag before the element and check the browser console.

The <agent-widget> AI agent widget