Servly
Docs: Widget reference

Get started

Build

Reference

Widget reference

Everything the avatar widget reads: element attributes, console settings, display modes and how they combine.

Element attributes

HTML
<script src="https://avatar-cdn.syntiva.tech/v1/YOUR_WIDGET_KEY/avatar-widget.iife.js"></script>
<avatar-widget
  api-url="https://avatar-api.syntiva.tech"
  widget-key="YOUR_WIDGET_KEY"
  position="bottom-right"
  theme="light"
  primary-color="#0B7A6C"></avatar-widget>
api-urlrequiredURL
The Servly API base URL: https://avatar-api.syntiva.tech.
widget-keyrequiredstring
The knowledge base's public widget key.
positionstring
bottom-right (default), bottom-left, top-right or top-left.
themelight | dark
Color scheme of the widget panel. Defaults to light.
primary-colorhex color
Accent color for buttons and highlights.

Console settings

These are saved per knowledge base in the console's widget settings and delivered to the widget when it loads. They aren't element attributes.

enabledboolean
The widget only loads for knowledge bases where it's enabled.
allowed_domainsstring[]
Domains allowed to load the widget. See domain allow-lists.
titlestring
Header title. Defaults to the knowledge base's name.
display_modefloating | inline
Floating launcher (default) or embedded in the page.
inline_chat_positionstring
Where the chat panel sits in inline mode. Defaults to top-right.
primary_color, position, themestring
Defaults used when the element doesn't set them.
voice_inputboolean
Lets visitors speak instead of typing. On by default.
show_chat_historyboolean
Keeps earlier messages visible in the panel. On by default.
auto_expandboolean
Opens the panel when the page loads. Off by default.

Display modes

Floating

A launcher anchored to a corner of the window. Visitors click it to open the avatar and chat. This is the default.

Inline

The widget renders inside your page layout and is always expanded. Give the element a size with CSS:

CSS
avatar-widget {
  display: block;
  width: 100%;
  height: 600px;
}

What happens on load

  1. The script defines the <avatar-widget> custom element, which renders inside a shadow root so your page's CSS doesn't leak in.
  2. The widget requests its configuration from GET /widget/config/{widget-key}. The API checks that the widget is enabled and that the page's domain is allowed.
  3. It shows the avatar's idle loop, applies your settings and starts a session. Questions go to POST /widget/query, and speech is transcribed by POST /widget/speech-to-text.

Troubleshooting

The widget doesn't appear

  • Check that the widget is enabled for the knowledge base in the console.
  • Check that the script URL and the element use the same widget key.
  • Open the browser console. 403 Domain not allowed means the page's domain is missing from the allow-list.

The avatar shows but doesn't answer

  • Make sure the knowledge base has Q&A pairs and that they've been indexed.
  • Try the same question in the console's playground to see whether it matches.