Installation

Keys you'll use#

• API key: authenticates server-to-server calls with the X-API-Key header. It has full access to your tenant. Keep it secret.
• Widget key: a public key scoped to one knowledge base, safe to put in a web page. Create or read it in the console under the knowledge base's widget settings, or with POST /knowledge-bases/{id}/widget-key.

Avatar widget#

The avatar widget shows the persona's face and a chat panel. Visitors can type or speak.

<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>

Place it anywhere in the page body. Inline mode, title, voice input and other options come from the widget settings in the console; see the widget reference.

Browser copilot#

The copilot moves its own cursor through your pages while it speaks: it points at fields, highlights buttons, fills ordinary inputs and waits for the user to click or type. It never fills passwords, one-time codes, card numbers, IBANs or national IDs, and it never presses pay, submit or delete for anyone.

<script src="https://file.syntiva.tech/latest/cobrowse-webcomponent.umd.js"></script>

<cobrowse-widget
  copilot-api-url="https://avatar-api.syntiva.tech"
  knowledge-base-id="YOUR_KB_ID"
  api-key="YOUR_WIDGET_KEY"
  language="en"
  position="bottom-right"></cobrowse-widget>

copilot-api-urlrequiredURL

The Servly API base URL.

knowledge-base-idrequiredstring

The knowledge base the copilot answers from.

api-keyrequiredstring

The knowledge base's public widget key.

languageen | ar

Interface and voice language. Defaults to English.

positionstring

Launcher position, for example bottom-right.

system-promptstring

Extra persona rules for the copilot on this site.

page-instructionsstring

Facts about the current page to ground the copilot.

tenant-idstring

Routes live-support requests to your human agents.

cobrowse-rtc-urlURL

Enables human hand-off over WebRTC co-browsing.

Describe your application to the copilot in the console's copilot workspace: list each system and its screens, matched by URL pattern, with guidance and step hints. The copilot uses those descriptions to explain a page and walk people through it.

Mendix widget#

The Servly Assistant for Mendix is a pluggable widget that puts a knowledge base on any Mendix page, in copilot or avatar mode. Put it on a layout to have the assistant on every page.

1. Copy the .mpk file into your Mendix project's widgets/ folder, or use App, Import widget.
2. In Studio Pro, press F4 to synchronize the app directory.
3. Add the widget to a page or layout, choose the assistant mode and set its properties.

Assistant modeCopilot | Avatar

Copilot is the default.

API URLURL

Defaults to https://avatar-api.syntiva.tech.

Widget keyrequiredstring

The knowledge base's public widget key.

Knowledge base IDstring

Copilot mode: the knowledge base this page is bound to.

Theme, primary colorstring

Avatar mode appearance. Empty uses the console settings.

Position, languagestring

Launcher position and language (en or ar).

AI system prompt, page instructionsexpression

Literal text or a database value that grounds the copilot.

Copy the exact values from the console: Copilot workspace, Widget, Mendix, or Embed code, Mendix channel.

Allow your domains#

Each knowledge base's widget has an allow-list of domains. When the list isn't empty, the widget refuses to load anywhere else and the configuration request returns 403 Domain not allowed.

Matching rules#

• Exact domains match on host name, ignoring protocol and port: www.example.com.
• Wildcards match subdomains: *.example.com.
• localhost and 127.0.0.1 are always allowed, so you can test locally.

Set the list in the console, or with PATCH /knowledge-bases/{id}/widget and a body such as {"widget": {"enabled": true, "allowed_domains": ["www.example.com", "*.example.com"]}}.