Script attributes of the embed code

The chat window's embed code is a single <script> element. Its data- attributes control the loader einbetten.js: which assistant appears, where the window and its requests come from, which colour and corner the launcher uses, which language applies and whether the window waits for consent. For each attribute, this page states whether it is required, which values it accepts, what applies when it is omitted and what an invalid value does.

The attributes at a glance

The embed code from the app

You find the finished embed code in the app under Work › Assistants (app.xicbot.de/assistenten), in the Chat window on your website section of the assistant in question. It holds two read-only fields: Embed code via our address and Embed code via your own address. The second one only appears once Your own path on your domain has been filled in and saved; until then its place shows "As soon as an own path is entered above and saved, the matching embed code appears here." After Save the app fetches the embed code again, and Copy embed code takes it over. How to place it in your page is covered in Embedding the widget.

<!-- Embed code via our address -->
<script src="https://cdn.xicbot.de/einbetten.js" data-xicbot="…" data-api="…" defer></script>

<!-- Embed code via your own address, path https://example.com/chat -->
<script src="https://example.com/chat/einbetten.js" data-xicbot="…" data-basis="https://example.com/chat" defer></script>

<!-- The same code with consent before the first conversation -->
<script src="https://example.com/chat/einbetten.js" data-xicbot="…" data-basis="https://example.com/chat" data-einwilligung="erforderlich" defer></script>

The embed code via our address carries data-api; the one via your own address carries data-basis and no data-api. The app appends data-einwilligung="erforderlich" to both as soon as Consent before the first conversation is switched on and saved. Neither contains colour, corner or language; to set them, add them to the copied code:

<!-- Embed code with colour, corner and language -->
<script src="https://example.com/chat/einbetten.js" data-xicbot="…" data-basis="https://example.com/chat"
        data-farbe="#0f766e" data-platz="left" data-senkrecht="bottom" data-sprache="en" defer></script>

data-xicbot

data-xicbot holds the assistant's public key. The app assigns it when the assistant is created: 32 characters made of digits and the letters a to f. In the app it appears under Public key, with the note "It appears in plain text on every foreign page. It only permits using this one chat window." The loader strips leading and trailing spaces; if nothing is left, it stops and nothing shows up on the page.

• The loader finds its own <script> element through document.currentScript. Where that does not work, it takes the first script[data-xicbot] element on the page.
• One embed code takes effect per page. The first one to run builds the chat window; any further one ends without effect. As a result, two assistants cannot be embedded on the same page.
• The key is part of the names under which the browser keeps the running conversation and the consent: xicbot.gespraech.<key> and xicbot.einwilligung.<key>. Details are in JavaScript and storage.
• After Generate a new key the interface no longer accepts the previous key. On every page loaded afterwards with the previous embed code, launcher and chat window disappear as soon as the chat window receives the interface's response. With the new embed code, conversation and consent start afresh for visitors, because the names change with the key. See Public key.

data-basis

data-basis sets the directory from which the loader fetches the chat window, rahmen.html. Without it, that is the directory einbetten.js itself was loaded from. The embed code via your own address still states it explicitly: anyone who later bundles the file or serves it from another directory would otherwise move the chat window along with it, without noticing.

• A relative value such as /chat is resolved against the address of the current page.
• Only http: and https: are accepted. With any other scheme, or a value that cannot be read as an address, the loader builds nothing: no launcher, no chat window, no message. It does not fall back to the default in that case.
• Query (?…) and fragment (#…) are dropped, and so are trailing slashes.
• If the base shares the page's origin, meaning scheme, domain and port, the requests run through that base as well, unless data-api is set. https://www.example.com and https://example.com count as different origins here.

In the app the matching field is called Your own path on your domain. It takes up to 200 characters and expects a full address with http or https, without query or fragment. The app removes a trailing slash when saving; an empty field removes the own path again. What your server has to provide for it is described under Own path.

data-api

data-api names the address the chat window sends its requests to. If the attribute is missing or empty, the rule is: when the base shares the origin of the page, the base is also the interface; otherwise the XICBOT interface is used. The loader removes trailing slashes. Otherwise it does not check a value that is set: surrounding spaces stay in place and the scheme is not checked.

The embed code via our address carries data-api with the address of our interface. The embed code via your own address deliberately leaves it out: there the interface follows from the base, and an explicit value would point back to an external address.

data-farbe

data-farbe colours the launcher until the settings from the app arrive. It accepts # followed by exactly six hex digits in upper or lower case, such as #0f766e or #0F766E. Short forms like #fff, colour names, rgb() and spaces around the value are invalid; #4f46e5 applies instead.

The attribute affects only the launcher. The chat window itself takes the Colour from the app, and once that arrives it recolours the launcher too. The first two dots inside the launcher are drawn in #000000 or #ffffff, whichever gives more contrast on the colour; the third dot is #22d3ee. If an Image in the title bar is set in the app, the launcher shows that image instead of the dots once the settings arrive; if the image fails to load, the dots return.

The Colour field in the app is a colour picker and stores the same format; new assistants start with #4f46e5. If data-farbe holds the same value as the app, the colour does not visibly change while the page loads.

data-platz and data-senkrecht

These two attributes set the corner where the launcher sits and where the chat window opens. They accept German and English values; case and surrounding spaces make no difference. The loader ignores any other value.

In the app this corresponds to the Window corner field; new assistants start with bottom right:

Offsets, window size, scale and corner radius cannot be set through attributes. Until the settings arrive, the launcher sits 20 px from the side edge and 20 px from the top or bottom edge, the window measures 384 × 620 px, the scale is 100 and the corner radius 18 px; the launcher itself is 56 px. After that, Distance from the side edge (px), Distance from the top or bottom edge (px), Window width (px), Window height (px), Scale (%) and Corner radius (px) from the app apply, as described in Widget settings.

data-sprache

data-sprache sets the language in which the chat window shows its fixed texts. It accepts a two-letter code, optionally with a region: de, en, en-gb. The loader strips surrounding spaces and lower-cases the value, so EN-GB works like en-gb. Forms such as de_AT, deu or zh-Hant are invalid and are treated as a missing attribute.

German and English take effect. Another valid code such as fr is still passed to the interface as the language request, but the chat window then uses the Language of the active version, which is Deutsch or English. The same version language applies when the attribute is missing. A German or English code takes precedence over the version language.

The attribute controls:

• the labels inside the chat window and its lang attribute,
• the launcher's labels for screen readers: "Chat öffnen" or "Open chat" until the settings arrive, and "Chat schließen" or "Close chat" while the window is open,
• the label of the cross on the outreach speech bubble: "Hinweis schließen" or "Dismiss message",
• the note about the assistant: "Sie schreiben mit einem automatischen Assistenten." or "You are chatting with an automated assistant.",
• the notice on the assistant's limits,
• the default consent wording when Consent wording is empty: "Ich bin damit einverstanden, dass mein Gespräch gespeichert und zur Beantwortung meiner Frage verarbeitet wird." or "I agree that my conversation is stored and processed in order to answer my question."

The attribute does not control:

• the name inside the chat window (Heading in the window), the greeting and the outreach texts: they appear as maintained in the app,
• your own Consent wording,
• the language of the replies: it follows what the visitor writes; if that cannot be detected, the language used so far in the conversation, and finally the version.

data-einwilligung

With data-einwilligung="erforderlich" the loader holds back the chat window until consent is given. The launcher still appears straight away. Only the exact lower-case value erforderlich is recognised; surrounding spaces do no harm, whereas Erforderlich or yes behave like a missing attribute.

Without the attribute, the loader builds the chat window once the page has finished loading, and the window requests the assistant's public configuration at that point.

The app adds the attribute to both embed codes when Consent before the first conversation is switched on and saved. An embed code that is already in place does not change by itself, so copy it again after switching.

The gate opens in one of these ways:

• Your page calls window.xicbot.einwilligen(), for example from your consent banner. The call stores the consent in the browser for 180 days, then builds the chat window and returns true. If the browser refuses to store it, the gate opens for the current page view only; on the next page the loader waits again for einwilligen() or a click on the launcher. window.xicbot is available once the loader has run; any object your page created under that name beforehand is replaced.
• The visitor consented on an earlier visit and the 180 days have not yet run out.
• On the previous page, the visitor confirmed a suggestion in the chat window to fill in a form; see Form prefill.
• The visitor clicks the launcher. Pressing it counts as asking for the chat, so the chat window is built even without consent. In doing so, the chat window requests the assistant's public configuration. If Consent before the first conversation is switched on, a conversation only starts once consent is given inside the window.

window.xicbot.stand() returns the state as an object: tor (attribute set), einwilligung (consent given), gespraech (a running conversation is known) and offen (chat window open).

Precedence between attribute and app

The loader sets up the launcher from the attributes straight away. Once the chat window has loaded its configuration, it reports the settings from the app and the loader adopts them.

• If the gate stays closed or loading the configuration fails, the attribute values remain in place.
• The chat window asks for the settings again when the visitor opens it or returns to the browser tab, at most once a minute. A change in the app thus reaches open pages without a reload.

How the loader evaluates the attributes

1. 1

   Step 1

   Find its own element

   The loader uses document.currentScript, otherwise the first script[data-xicbot] on the page. If there is none, it stops.

2. 2

   Step 2

   Read the key

   If data-xicbot is empty, the loader stops without showing anything.

3. 3

   Step 3

   Once per page

   If an embed code has already run on the page, this one stops. From here on the page counts as taken, even if a later step fails.

4. 4

   Step 4

   Determine the base

   From data-basis or the directory of src. Without a valid http: or https: base, the loader stops.

5. 5

   Step 5

   Read the remaining attributes

   Interface, colour, corner, language and gate. Invalid values for colour, corner, language and gate count as not set; the loader takes data-api as it is.

6. 6

   Step 6

   Place the launcher

   The launcher appears at once as a button in the colour and corner from the attributes, named "Chat öffnen" for screen readers, or "Open chat" with an English code in data-sprache.

7. 7

   Step 7

   Build the chat window

   After the page's load event; with the gate, only after consent or a handover. A click on the launcher builds it immediately. The chat window is loaded as rahmen.html from the base and runs in its own sandboxed frame.

8. 8

   Step 8

   Adopt the settings

   The chat window loads the assistant's configuration, passing data-sprache as the language request, and reports heading, colour, corner and dimensions to the loader. From then on the app's values apply.

Troubleshooting

How to check whether the embed code has arrived on your page is covered in Check the embedding; all messages of the chat window are listed under Messages.

Further reading

• Embedding the widget: embedding routes, own path and content security policy
• Widget settings: colour, corner, offsets and dimensions in the app
• Consent and visitor rights: the gate inside the chat window and the default wording
• Form prefill: the handover between two pages
• JavaScript and storage: window.xicbot and what the browser keeps
• Appearance and accessibility: launcher, keyboard and screen readers
• Chat in the widget: what visitors experience in the chat window

Frequent questions