Create and maintain assistants

An assistant has two layers. The Basics with name, status and fallback answer take effect as soon as you save. The Answer building blocks live in numbered versions: every publish creates a new version, the previous one is kept, and a running conversation keeps the version it started with.

Where to find assistants

The Assistants page is at https://app.xicbot.de/assistenten. At the top are the New assistant form and the Quota this month card, below them the list of all assistants, sorted by name and up to 200 entries long. The overall layout of the app is described in App interface.

The Setup path leads through four steps: Create, Connect knowledge, Test and Embed. On larger screens it sits at the top of the page, on phones below the form. As long as there is no assistant, Embed is locked and shows the note “after step 1”. You can also create an assistant from a proposal based on your website; see Setup. That assistant also starts as a draft with version 1.

The context column of the app repeats the list with the Search the list field. It matches name and short name; clicking a hit opens that assistant's card and scrolls to it. Adding ?a= with an assistant ID to the address opens exactly that card. If nothing matches, it reads “No entry matches this search term.”

Who can do what

Permissions follow the team role. Every role can view; each further action needs at least the role listed.

With the Read role the page shows: “With the Read role this area is view-only. Changes need at least the Edit role.” Roles below Administration see under the list: “Deleting assistants needs the Administration or Owner role.” In the open card, these roles see this under Public key instead of the button: “Generating a new key needs the Administration or Owner role.” With the Administration or Owner role, Generate a new key first asks: “Generate a new key? The current embed code stops working immediately.” What to do on your website afterwards is covered in Public key. How to assign roles is covered in Team and roles.

Create an assistant

The New assistant form has three fields. Create assistant creates the assistant; while the request runs, the button reads “Creating …”. The new assistant then appears in the list, sorted by name. If the list could not be loaded beforehand, the page instead reports “The assistant has been created.” and reloads the list.

A template pre-fills role, tone, topic boundary, handover rule, greeting and fallback answer; some also bring entries for the never-discuss list and additional handover topics. It is a copy: everything stays editable afterwards, and a later change to the template does not reach your assistant.

What creating sets up

• The assistant is a Draft and has Version 1.
• Answer only from the knowledge base is switched on.
• Maintained facts, Structured master data and Handover address are empty.
• Without a template the Tone is factual, the Greeting reads “Hello. How can I help?” in English and „Guten Tag. Was kann ich für Sie tun?“ in German, and a standard Fallback answer is filled in.
• Enable chat window is off, so the assistant does not answer on any website yet.
• The short name is derived from the name: lower case, with hyphens, with a base of at most 50 characters. If it is taken, the app appends -2, -3 and so on. If the name yields no short name, it is assistant. It stays the same when you rename the assistant later.

The assistant list

Each row shows the name and below it status, version, template and short name, for example active · Version 4 · Trades · customer-service. The template only appears if one was chosen. Edit opens the assistant's card; with the Read role the button reads View, with the card open Close. For the Administration and Owner roles, Delete sits next to it.

Without assistants it reads “No assistant created yet.” with the link Go to the “New assistant” form. If the list cannot be loaded, the page reports “The list could not be loaded.” and offers Load again.

The open card has five parts: Answer building blocks, Basics, Versions, Fixed rules and Chat window on your website. Embedding and styling the chat window are covered in Embed the widget and Widget settings, the rules for approaching visitors in Outreach rules.

Basics

The Basics apply from the moment you save, including conversations already running. Save shows “Saving …” while it works and “Saved.” afterwards. A saved change appears in the Audit log as Assistant changed; if that entry cannot be written, the change is not applied and the page reports “Not saved: the entry in the audit log could not be written. Please try again.”

When the chat window answers

The chat window only answers when two switches agree: Status is active, and Enable chat window is on under Chat window on your website. Right after creation neither is the case. If either is missing, the chat window launcher disappears on the next page load.

Answer building blocks

The building blocks determine how the assistant answers. There is no free-form instruction field: each setting has its own field with its own limit. Publish new version stores all fields of this part as a new version.

The handover fields between Handover rule and Greeting are described in the section “Handover to a person” further down.

Answer only from the knowledge base

When switched on, the assistant is instructed to answer solely from the supplied knowledge base excerpts and the maintained facts. If no excerpt carries the answer, it is to say exactly that. The app calls this the safe setting: “Without a citation there is then no statement.”

When switched off, the excerpts still take precedence over anything else the model knows. It is still told not to state prices, deadlines, commitments or legal information that no excerpt contains. How excerpts are built and selected is covered in Knowledge and answers.

Never discuss and Maintained facts

• One line per entry; empty lines do not count.
• More than 8 never-discuss lines or 12 facts: the field shows “Too many lines. Please shorten.” and Publish new version stays disabled.
• A never-discuss entry applies when it appears in the visitor's question, regardless of case and from a length of four characters. The conversation then goes to a person and the answer gets the mandatory notice.
• Maintained facts count like an excerpt from the knowledge base and need no citation. They suit short, fixed statements such as a callback time.

Structured master data

Master data is sent with every request, even when no excerpt mentions it. Each group has Add row, each row Remove.

Entirely empty rows are not sent. An opening-hours row with only a start or only an end, and a price row without a service, without Price from or with an amount the app cannot read, are not dropped: the app names the error at the row and blocks publishing until it is corrected. Locations without a label and contacts without a role or a further detail are not saved, as described in the table. More rows than allowed show “Too many entries. Please shorten.” and block publishing. After publishing, the form shows the saved state.

Handover to a person

On a handover the conversation switches to the status handed over and appears in the Inbox. If the assistant hands over and a Handover address is set, an email goes there as well; without an address no email is sent. A manual handover with Hand over to a human on the Conversations page sends no email. A handed-over conversation does not revert to open by itself.

The eight topics are Medical, Legal, Finance, Allergies, Emergency, Complaints, Data protection and Payment details. If a request names a topic that does not exist, the message reads “No such topic: … Words can only be stored for the topics listed.”

When a handover happens

A conversation reaches a person in three ways: the assistant hands over itself according to the Handover rule, the conversation score reaches the threshold, or the question touches a fixed rule, a ticked topic or a never-discuss entry. Points are given per visitor message:

• Points add up over the conversation. With the default of 3, a request for a person is enough on its own.
• If a message points to a danger to life or health, the conversation reaches the threshold with that same message.
• While a conversation is handed over, these three paths trigger no further handover and no further email.
• Threshold and address come from the version the conversation started with.

How to continue handed-over conversations is described in Inbox and Conversations. What tools do in addition during a handover is covered in Tools.

Fixed rules

The Fixed rules card shows the layer behind your building blocks that also applies after the model has answered. It cannot be switched off and covers four restrictions:

• No legal advice
• No medical information
• No assessment of allergies
• No binding financing offer

If the question touches one of these restrictions, the conversation goes to a person and the answer gets the Mandatory notice in the answer. It starts with “Note: This assistant is a program, it can be wrong and it does not replace …” and then names the restriction touched. If a topic only appears in the answer, just the notice is added.

Under Emergency path, in the language of the version, is the sentence an answer carries when the question describes a medical emergency; the answer itself carries it in its own language. In English it reads: “If this is an emergency, please contact the emergency services immediately.” The German wording names the German emergency numbers. Handover from score shows the threshold that applies to this assistant.

Publish and restore versions

Publish new version stores the building blocks as a version with the next number and makes it active right away. While the request runs the button reads “Publishing …”, then the page reports “The new version is active.” New conversations start with this version; conversations already running keep theirs.

The Versions list shows the last 50, newest first. Each entry gives number, tone and language as a code (de or en), plus Answer only from the knowledge base or Topic boundary, for restored versions “restored from Version …”, and below that the Role text. The active version reads “This version is active.”

1. 1

   Step 1

   Choose a version

   Find the state you want to return to under Versions.

2. 2

   Step 2

   Restore

   Click Restore. While it runs, it reads “Restoring …”. The button needs the Edit role.

3. 3

   Step 3

   Check the result

   The page reports, for example, “Version 3 is active again as version 7.” The old state has been published as a new version; no version is lost in the process.

Via the API, a new version takes over the never-discuss list, maintained facts, master data, handover topics, threshold, trigger words and handover address from the active version when the request omits them. Restoring the active version is refused with status code 422, an unknown number with 404. Details are in Knowledge and assistants via the API.

Delete an assistant

1. 1

   Step 1

   Choose Delete

   Click Delete in the assistant's row. The button is available to the Administration and Owner roles.

2. 2

   Step 2

   Confirm the name

   The dialog “Delete: …” with the assistant's name explains: “This removes the assistant with all versions and conversations. It cannot be undone.” Type the name under “Type the name to confirm:”; spaces at the start and end are ignored.

3. 3

   Step 3

   Delete permanently

   Delete permanently only becomes available once the name matches; the Enter key works as well. Cancel closes the dialog without changes. Afterwards the page reports “The assistant has been deleted.”

The assistant takes its versions and all its conversations with it. An audit log entry is written first; if that fails, everything stays in place and the page reports “Not saved: the entry in the audit log could not be written. Please try again.” An embedded chat window disappears on the next page load. What else is deleted and when is covered in Retention and deletion.

Quota this month

The Quota this month card shows the month, how much is used and how much is left, the number of Messages and a bar. The quota applies to the whole account; all assistants draw on it.

Once it is used up, the card reads “The quota is used up. Until the next month the assistant only returns the fallback answer.” The chat window and the test conversation then show the Fallback answer; the API returns status code 429 with the wait time until the next month. If the figures cannot be loaded, it reads “The current state could not be loaded.” Quota size and warning levels are covered in Plans and quotas, plans are listed under Pricing.

Messages

Errors in a single field appear at that field. Everything else is reported by the page with these sentences:

Via the API

The actions on this page are also available through the API, with the same limits. Creating an assistant, changing it, publishing a version and restoring one write their audit log entry in the same step as the change. If that entry cannot be written, the API responds with 500 and the code not_logged, and the change is not applied: neither the assistant nor the version is created, the previously active version stays active, and changed fields keep their previous value. A change via PUT appears in the Audit log as Assistant changed. The table there shows Time, Action, Subject, Who and Details. Details lists what the entry records in its data field, which GET /api/v1/activity also returns: the field names under changed, and for status, widget_enabled (Enable chat window) and widget_consent (Consent before the first conversation) also the old and new value, shown in the table with an arrow between them and returned by the API under from and to. A PUT that changes nothing writes no entry. Requests, responses and examples are in Knowledge and assistants via the API.

Frequent questions