Widget settings

Every assistant comes with its own chat window. This page covers all of its settings in the section Chat window on your website: each field with its limits and default, who may change what, what happens when you save, when a change reaches your website, what the preview and the embedding status show, and how to generate a new key. How the line of code gets onto your website is explained under Embed the widget.

Where the settings are

Open Work › Assistants (app.xicbot.de/assistenten) and click Edit next to the assistant you want; with the Read role the button is labelled View. The panel that opens contains the section Chat window on your website with the note “The chat window runs in its own frame. It can neither read nor change the page it sits on.” Close collapses the panel again.

The section has four parts: at the top the form with every setting and the Save button, below it the embed codes for copying, then the Embedding on your website display with the preview, and at the end the Public key part. The settings apply per assistant: each assistant has its own chat window with its own key and its own embed code.

Who may change what

The service checks the role itself, not only the app. It refuses a save without the Edit role, and the app reports “With the Read role this area is view-only. Changes need at least the Edit role.” A new key without the Administration role ends with “This needs at least the Administration role.” Everything on this page also requires being signed in, an active account and a confirmed email address. How roles are assigned is covered under Team and roles.

All fields at a glance

None of the fields is required. The browser already rejects values outside the limits when you save, and the service checks them a second time. The table lists each label as it appears in the app, in the order of the form, together with what is allowed and what applies as long as you change nothing. Numbers are whole numbers.

A number field you clear is saved with its default. An empty text field counts as not set, so the default from the table applies.

Enabling the chat window

The Enable chat window switch carries the note “Only with this setting does the snippet answer on other sites. Without it, it stays inert.” In addition, the assistant's Status under Basics must be active. If either is missing, the service answers the embed code as if the assistant did not exist, and the loader removes the trigger from the screen. The same happens when the account is not active or a demo has expired.

Switching it off leaves the other settings, the key and the embed code untouched. Once you switch it back on, the existing code on your pages works again. To take the chat window offline for a while, use this switch or the Status, not a new key. More on the two switches is under Assistants and Embed the widget.

If you delete the assistant (Administration or Owner role), all settings in this section and the key go with it, and the embed code no longer finds an assistant. Deleting is described under Assistants.

Heading, colour and image

Heading in the window

Heading in the window takes up to 80 characters. If it stays empty, the window shows the assistant's name, and the app displays that name as a placeholder in the empty field. Screen readers use the same heading as the name of the window and, while it is closed, of the trigger.

Colour

Colour opens the browser's colour picker, and the chosen value is shown next to it as #RRGGBB. The service accepts only this six-digit hexadecimal form. The colour fills the trigger and the brand areas inside the window. The field comes with the note “The text colour inside the window is derived from this colour so contrast holds up on light tones as well.” Text on the colour is set to either black or white; there is no separate text colour setting.

If the embed code carries its own data-farbe, it only applies until the window has loaded the settings from the service; after that the colour from the app wins. The same goes for data-platz and data-senkrecht versus Window corner. The precedence is described under Script attributes.

Image in the title bar

Use Choose file to load a PNG, JPEG or WebP image; Remove image clears the field. Both only take effect with Save. The image appears in the title bar of the window and on the trigger. Cropping, limits, messages and display are covered under Image in the title bar.

Position and size

Window corner offers bottom right, bottom left, top right and top left. That is where the trigger sits and where the window opens. Distance from the side edge (px) and Distance from the top or bottom edge (px) come with the note “Measured from the trigger to the respective window edge. On devices with a rounded screen the protected margin is added on top.” Which edge is meant follows from the chosen corner.

Window width (px) and Window height (px) carry the note “A target size. On a small screen less applies so the window stays in view; up to 560 pixels of width it fills the whole area.” Precisely: the width is at most the browser window width minus the side distance and 16 pixels. The height is at most the browser window height minus 32 pixels and minus the distance the chat window keeps from the edge; that distance is the edge distance plus the trigger size plus 12 pixels. If an element of your page covers the trigger’s spot, such as a consent banner, the trigger moves vertically away from it. The window moves by the same amount, and its maximum height shrinks accordingly. If the browser window is 560 pixels wide or less, the chat window fills the whole area.

Scale (%) carries the note “Affects the trigger and the text size inside the window. 100 means unchanged.” At 100 the trigger measures 56 pixels and the base text 16 pixels, at 150 they are 84 and 24 pixels, and at 80 they are 45 and 12.8 pixels. Scaling leaves the width and height of the window unchanged.

Corner radius (px) rounds the corners of the window and of the trigger; 0 gives sharp corners. On the trigger the radius goes up to half of its edge length at most, which makes a circle. With the defaults (radius 18, trigger 56 pixels) it is a square with rounded corners. When the window fills the whole area on a narrow screen, its corners are square.

Proactive outreach

The note on this field reads “One event and one sentence per rule. The first rule that applies speaks; after that the widget stays quiet for this visit. Without a rule nothing appears unasked.” Add rule adds another rule, up to five; a counter such as 2/5 shows how many there are, and at five rules the button disappears. The app drops rules without a sentence when you save. The sentence of a rule has at most 200 characters; a path filter starts with / and has at most 120 characters, otherwise the service refuses to save. Events, path filters and order are covered under Proactive outreach.

Files from visitors

Accept files from visitors names the limits in its note: “Images and PDF, at most 5 MB and five files per conversation.” Allowed are PNG, JPEG, WebP and PDF, recognised by the file content; SVG, Office formats and archives are excluded. The window offers a file picker only while the switch is on, and not in the preview.

While the switch is off, the service refuses every file. A page still open with the old setting then reports “Files are not enabled here.” How visitors send files is covered under Chat in the widget.

Consent before the first conversation

The Consent before the first conversation switch carries the note “The window then shows a gate: without agreement nothing can be typed and nothing can be sent. Whoever declines closes the window without a conversation coming into being.” The Consent wording field can only be edited while the switch is on and takes up to 500 characters. Its note: “Leaving it empty means our default wording applies, in the language of the window.” The default wording is:

The window language follows data-sprache in the embed code (de or en), otherwise the language of the active version, otherwise German. Your own wording is shown exactly as written, whatever the window language.

After saving, the embed code also carries data-einwilligung="erforderlich". Replace the code on your pages: without this attribute the loader loads the window and its settings as soon as your page has loaded, that is, before any consent. The service itself requires consent from that moment on and refuses to start a conversation without it. Along with the consent it stores the time and a SHA-256 fingerprint of the wording the visitor agreed to, the privacy policy version and the page. That wording is your Consent wording, or, if the field is empty, the default text in the language of the window. More under Script attributes and Consent and visitor rights.

Allowed domains

The note on this field reads “One per line. Subdomains are included. Empty means any website may embed the window.” The field takes up to 500 characters. Besides line breaks, commas also separate entries; surrounding spaces and upper or lower case make no difference. Enter domain names only, without https:// and without a path: the comparison uses the domain name of the page. An entry example.com allows example.com and shop.example.com.

The check happens when a conversation starts: the page the window runs on has to match an entry or be a subdomain of one. If the list has entries and no page is known, the service refuses as well. The window then shows “This chat is not enabled for this website.” The list does not affect loading and displaying the window, nor the Embedding on your website display. More under Embed the widget.

Your own path on your domain

With Your own path on your domain, the window and its requests run through an address on your domain, such as https://example.com/chat. A full address with http:// or https:// and a host name is allowed, at most 200 characters, without ? and without #. Trailing slashes are removed on saving. The browser already rejects an incomplete address; if the address breaks one of the other rules, the service rejects it. The app then states the reason below the field, for example “The address of your own path must not contain “?” or “#”.”, and also reports “Please check the marked fields.” The note on the field ends with “Empty means no own path is set up.”

The matching Embed code via your own address only appears once the path has been saved. Until then its place shows “As soon as an own path is entered above and saved, the matching embed code appears here.” What your server has to forward for this is described under Embed the widget.

Saving

Save applies every field in the section at once. While the request runs the button reads “Saving …”, then the app reports “Saved.” The settings belong to the assistant, not to a version: they take effect without publishing, and restoring an older version leaves them unchanged.

• Empty text fields are saved as not set, so the respective default applies.
• Cleared number fields are saved with their defaults: 20, 20, 384, 620, 100 and 18.
• Proactive outreach rules without a sentence are dropped.
• Afterwards the app reloads the embed codes and the embedding display. If only this step fails, the settings are still saved; the app then reports “Saved. The embed code for “…” could not be reloaded afterwards. Open that assistant again to see it.” and, instead of the codes, shows “The current state could not be loaded.”
• Each signed-in person has 30 actions per minute. Besides this Save, they include Save under Basics, creating assistants, publishing and restoring versions, Generate a new key, creating and changing tools, and creating and changing check questions and starting runs in Acceptance. Beyond that the app reports “Too many attempts. Please wait a moment.”

When changes reach your website

Every page that loads after you save receives all settings. A page that is already open checks back at most once a minute, namely when the visitor opens the window or returns to the tab. If that check fails, everything stays as it is.

Copying the embed code

Below the form there are up to two embed codes in read-only fields, each with a Copy embed code button. First Embed code via your own address with the note “The recommended route: window and requests run through your domain, the visitor talks to no external address.”, then Embed code via our address with the note “This line belongs in the head of every page the window should appear on. The visitor loads the window from our address.” Every role can view and copy them.

If no own path has been saved yet, the first position reads “As soon as an own path is entered above and saved, the matching embed code appears here.” After copying, the app reports “Embed code copied.” If the browser refuses access to the clipboard, you see “Copying was not possible. Please select the text by hand.” While the codes are loading it says “Loading …”, and if they could not be loaded, “The current state could not be loaded.” This is what an embed code via the own path https://example.com/chat looks like with consent switched on, where … stands for your key:

<script src="https://example.com/chat/einbetten.js" data-xicbot="…" data-basis="https://example.com/chat" data-einwilligung="erforderlich" defer></script>

Where the line goes and how the two routes differ is covered under Embed the widget, and every attribute of the line under Script attributes.

Embedding and preview

The Embedding on your website display shows when and on which page the window last loaded on an external page, for example “Last loaded: 28/09/2026, 14:05:00” and “Page: www.example.com”. If that has not happened yet, it says “The window has never loaded on your website.” When an entry is written, when it changes and what it does not tell you is covered under Check the embedding.

Show preview opens the window below the display, and Close preview closes it again; every role can open the preview. What it shows and what it does not is covered under Preview in the app.

Public key

At the end of the section, Public key shows the key itself, the same value as data-xicbot in the embed code. With Generate a new key the Administration and Owner roles replace it, and the current embed code stops working at once. How the exchange works, what the app reports and what to have ready beforehand is covered under Public key. To switch off temporarily, Enable chat window is the better choice.

Messages

Via the API

The same settings can be set through the API. The fields are named as follows:

All assistant endpoints are described under Knowledge and assistant endpoints, the public window endpoints under Widget endpoints and the rate limits under API limits.

Further reading

• Embed the widget: embedding routes, domain list, own path and checking the embedding.
• Script attributes: every attribute of the embed line and their precedence.
• Appearance and accessibility: how the window looks and works for visitors.
• Proactive outreach: rules, events and the speech bubble.
• Consent and visitor rights: the gate, withdrawal and access requests.
• JavaScript and storage: what the window stores in the browser.
• Widget delivery: where the window's files come from.
• Assistants: basics, status, versions and deleting.

Frequent questions