The conversation in the widget

The chat window on your website runs every conversation in the same order: on opening it loads the assistant's settings, creates a conversation as soon as the visitor may write, and shows each answer while it is being written. Below an answer there can be citations, a contact offer, follow-up questions, tool and product cards and a rating. This page describes each of these parts with its limits and quotes every message a visitor can see.

Opening: the assistant's settings

The window runs in an isolated frame that the loader places on your page (see Embed the widget). The first thing it does is call GET /api/v1/public/widget/{key}. The request carries the address of your page as host, a language wish from the embed code as language, and preview=1 in the app's preview window. Among others, the response contains these fields:

The window's labels exist in German and English. If the embed code names de or en, that language applies; otherwise the language of the active version. Which language the assistant answers in is decided by each message instead: it answers in the language it recognises in the visitor's message. If it recognises none, the language it first recognised in this conversation applies, then the version's. The attribute for the language wish is described in Script attributes.

When the settings do not arrive

• Key unknown or demo access expired (404 with unknown_widget or demo_expired): the loader closes the window, removes the frame from the page and hides the launcher. Only if the loader cannot do that does “This chat is not available.” remain in the window. The window takes the same route when this response arrives while creating or resuming a conversation or while sending a message.
• Too many requests (429): “Too many requests right now. Trying again in … seconds.” The service states the waiting time; otherwise 30 seconds apply. The window works with 1 to 3600 seconds and switches to minutes from 90 seconds.
• Service unreachable (network error or 5xx): “The chat cannot be reached right now. Trying again in … .” New attempts follow after 15, 30, 60, 120 and 240 seconds.
• After six attempts, on any other error and if the response cannot be applied, “The chat cannot be reached right now.” remains. This includes a 404 without the codes above, for instance when data-api points to a wrong address.

The conversation starts

As soon as the visitor opens the window, it creates a conversation with POST …/conversation. If the assistant requires Consent before the first conversation, the window first shows the Before we start screen with I agree, start the chat and Decline and close; the input field and sending stay locked until the visitor agrees, and only agreeing creates the conversation. If the visitor writes before the conversation exists, the window creates it first and sends the message 400 milliseconds later. The consent flow and its wording are described in Consent and visitor rights.

The service creates the conversation with the channel widget and the assistant's currently active version and replies with 201 and conversation_id. The loader keeps this ID for the page, see JavaScript and storage. With consent, the service records its time. If a webhook for conversation.started is set up, it goes out now, see API keys and webhooks.

• 404 with unknown_widget or demo_expired: “This chat is not available.” The window locks itself, also when loading a conversation.
• 422 no_version: the assistant has no active version.
• 403 host_not_allowed or blocked: the page is not on the list of allowed domains, or the visitor is blocked. The window shows “This chat is not enabled for this website.”
• 422 consent_missing: consent is missing. The window shows “The chat could not be started.”, as for any other rejected start.
• 429: “Too many requests right now. Trying again in … .” Without a value from the service, the window waits 20 seconds and then tries again on its own.
• Network error or 5xx: up to three new attempts after 15, 30 and 60 seconds with “The chat cannot be reached right now. Trying again in … .”, then “The chat cannot be reached right now.”

Resuming after a reload

If the loader already knows a conversation ID, for instance after the visitor moves to another page of your website, the window does not create a new conversation. It loads the last 50 messages with GET …/conversation/{conversation} and shows them in order:

• The visitor's messages, the assistant's answers and your team's messages, labelled Staff without a name.
• In addition, up to 50 tool cards in their most recent state, placed between the messages by time.
• On each assistant answer, the question Was this helpful? with the rating last chosen.
• Citations appear again below the answer. The highlighting of unbacked passages does not come back after a reload.
• If your team has taken over the conversation, “A member of staff has joined and is answering personally.” appears again.
• If the conversation is empty, the greeting appears.
• The list of attached files is reloaded as well.

• 404 not_found: the conversation is unknown, belongs to another assistant or has been deleted. The window forgets the ID, shows the greeting and starts a new conversation on the next occasion.
• Other errors: up to five new attempts, for 429 after the stated waiting time (otherwise 20 seconds), otherwise after 30 seconds, with “The conversation could not be loaded. Trying again in … .” After that, “The conversation could not be loaded.” remains. The ID is kept.

Changes to an open window

If you change the title or appearance of the chat window while a visitor has your page open, the window checks for it: on each opening and each time the browser tab returns to the foreground, at most once every 60 seconds. Title, colour, position, offsets, size, scale, corner radius and the assistant's picture, as well as the notice below the title and the limits notice, are applied without reloading the page; this also applies if only one of the two notices has changed. Greeting, consent requirement and readiness do not change in an open window; they apply from the next page load. The fields are described in Widget settings.

Sending and the answer

The input field Your message (placeholder Write a message) accepts at most as many characters as are set for your account as Message length (characters) and grows up to 140 pixels in height as the visitor types. The length lies between 200 and 4000 characters, new accounts start at 4000; the operator sets it for each account individually in the Operations area. The Enter key sends; Shift and Enter start a new line. On touch devices without a mouse, only the Send message button sends, because Enter is the line break of the on-screen keyboard there. Spaces at the start and end are removed; an empty field sends nothing.

When the visitor sends, the field empties, the message appears as the visitor's bubble, and any suggestions from the previous answer disappear. Until the answer is finished, Send message is disabled and three dots labelled “Answer is being written” appear in the conversation. The answer arrives as a stream (text/event-stream) and grows piece by piece in its bubble. For screen readers the conversation is marked as busy meanwhile, so that each piece is not read out on its own.

What the answer stream contains

The stream consists of named events. This table lists every event the service sends to the widget and what the window does with it:

If your account's quota is used up, the assistant answers with its Fallback answer without calling the model; in the conversation the answer then has the state quota used up. If a maximum number of visitor questions per conversation is set for your account and reached, the answer is “This conversation has reached its agreed length. I am handing it over to a person – please leave your question together with a way to reach you, or start a new conversation.” This answer also has the state quota used up in the conversation, and the conversation is handed over to a person. After this answer the window offers the button Start a new conversation. It starts a new conversation in the same window; the previous one is not deleted but is no longer visible in the window. If the assistant requires consent, the consent screen appears again. The operator sets this number for each account individually in the Operations area, see Tenants and limits; new accounts start at 60, and at 0 this limit does not exist. If the answering service fails, the Fallback answer is sent as well; any text already started is discarded, and the answer has the state fallback answer. Quotas are described in Plans and quotas.

When sending fails

• If sending fails before the answer begins, the visitor's bubble disappears and the text returns to the input field, provided nothing new was typed there. This applies to all of the following cases.
• 409 reply_in_progress: an answer is already running for this conversation, for instance from a second tab. Message: “An answer is already running. Your message is back in the input field.”
• 404 not_found: the conversation no longer exists, for instance because it was deleted. The window clears the history and starts afresh, with the consent screen if the assistant requires consent, and with the greeting. Message: “This conversation no longer exists. Your message is back in the input field; sending it starts a new conversation.”
• 404 with unknown_widget or demo_expired: the window disappears as described above under “When the settings do not arrive”; where that is not possible, it locks itself with “This chat is not available.”
• 429: Message: “Too many messages in a short time. Your message did not arrive and is back in the input field — please send it again in … .” Until the waiting time is over (30 seconds if none is stated), each new attempt to send shows the remaining time without sending.
• 403 consent_revoked: “Consent withdrawn. This conversation is closed.” The window locks itself.
• 403 consent_missing: the assistant now requires consent that this conversation does not have. The window clears the history, shows the consent screen and “Please give your consent first. A new conversation will then begin.” The message stays in the input field and can be sent in the new conversation after consent; the previous conversation is no longer visible in the window.
• 403 blocked: the visitor is blocked. Message: “This chat is currently not available to you.” The window locks itself.
• 413 input_too_long: the text is longer than the maximum length set for your account. The response states limit and length. Message: “Your message is too long: the limit is … characters. It is back in the input field.” From then on the input field accepts only that many characters.
• Any other error before the answer begins, including 422 (more than 4000 characters, which the input field does not accept anyway, or no_version), a server error or a dropped connection: “Your message could not be sent and is back in the input field.” If the connection drops after the answer has begun, the window shows “The answer could not be loaded.” and the visitor's message remains in the history.

Citations below the answer

The assistant receives the matching excerpts from your knowledge base with numbers and refers to them in the answer as [1], [2] and so on. After a complete answer, the window shows a list of the excerpts actually referred to below the bubble, at most four. The list is headed “Sources”. Each entry shows its number without brackets in a framed box, next to it the document name and below that the heading; without a heading only the document name appears, without a document name only the heading. The entries are plain text, not links. If an answer from the model names no number, no list appears. How excerpts are created and found is described in Knowledge and answers.

If the question matches an active question and answer pair, no model is asked. The pair's answer arrives word for word and in one piece, and below it there is a single entry with the number 1 and the pair's question, even though the text names no number. Your assistant's fixed rules apply here too: if the question touches a restricted topic or a taboo, the defined notice appears below the wording and the question is handed to a person. The check of hard details described in the next paragraph does not take place, and such an answer has neither follow-up questions nor a contact offer below it. You maintain pairs under Knowledge.

After an answer from the model, the service checks hard details: prices, percentages, periods, quantities, email addresses, web addresses, phone numbers and promises. A detail counts as backed if it appears in the excerpts provided, in what the tools returned, in the visitor's questions or in the texts of the version (role, topic scope, handover rule, greeting). Earlier answers of the assistant do not count. For up to eight passages per answer that appear nowhere, the following applies:

• If excerpts or tool results were available, the service replaces the passage with [not backed] (German [nicht belegt]). The window swaps the bubble text for the corrected version; if a tool card has split the answer across several bubbles, it does so for each bubble separately. If a passage spans the boundary between two bubbles, the previous wording remains in all bubbles and the window highlights nothing.
• If neither was available, the text remains as it is.
• In both cases the window highlights the passages once the stream has ended; hovering shows “Not backed by the stored sources.” Passages that do not fit the text are skipped; where they overlap, the first one counts. With several bubbles, each bubble highlights the passages that lie entirely within it; a passage across a bubble boundary is dropped. If the text of a bubble differs from the text the passages refer to, no highlighting takes place.
• If Answer only from the knowledge base is switched on, a note follows below the answer, see below.
• The highlighting exists only in the open window. After a reload, the conversation shows the saved text without highlighting.

A second correction concerns required notices: if the answer touched a restricted topic or taboo of your assistant and wrote the notice in a different form, the service replaces it with the defined notice. The question is then handed to a person. Restrictions and taboos are described in Assistants.

Contact offer and follow-up questions

Below a complete answer there may be a row of buttons:

• Talk to a person, if the assistant offers contact with your team. The button sends “I would like to talk to a person.” as the visitor's message, so the request appears in the conversation. Which route you offer next is set in the assistant's handover rule.
• Up to three follow-up questions of at most 200 characters each. If a knowledge base exists, only questions that the knowledge base can answer remain; without a knowledge base, the questions are shown unchecked. A click sends the question and marks it as a suggestion.
• The buttons do nothing while an answer is running or after consent was withdrawn. The row disappears with the next message sent.

Tool cards

If the assistant calls a tool while answering, a card appears in the conversation. Its heading says what is about to happen or has happened, with the state below it. Depending on the tool, product cards, basket lines or a Continue link follow. If a step failed, the card reads “The step could not be carried out.”; the exact reason stays in the app. Which tools an assistant has and how to set them up is described in Tools.

What runs without asking

• A tool of the kind read-only whose Approval is set to without asking runs straight away.
• For the Book appointment tool, looking up free slots runs straight away even if the tool otherwise needs confirmation. The card is then headed “Check available times”.
• Everything else becomes a suggestion: tools of the kind writing or irreversible and every tool set to with confirmation. The card shows “Waiting for your confirmation” and the buttons Confirm and Reject. Nothing runs until the visitor clicks.

The seven states

Confirming and rejecting

• A click locks both buttons on the card and sends the decision. The response contains the card in its new state, and the window redraws it in the same place.
• On Confirm, the service checks role, plan and required details once more. If any of them changed since the suggestion, or the tool has been removed in the meantime, the call ends as failed without running.
• If the suggestion is older than 60 minutes at the time of the click, it ends as expired, on Reject as well.
• A second click on a suggestion that has already been decided does not run anything again. The response shows the card as it is and carries duplicate: true.
• After consent has been withdrawn, the window locks the buttons of all open suggestions. A click after that, or a 403 consent_revoked, for instance after a withdrawal in another window, shows “Consent has been withdrawn. This step will no longer be carried out.”
• If the request fails, the buttons are released again and the line below the conversation reads “The step could not be completed.”

Card headings

The heading states what the tool intends to do and with which details. For your own tools it shows the tool title followed by the details passed in. The ten types that address a connected system, such as Read order status or Book appointment in calendar, build their heading themselves, for example “Check order status for order …”, in German “Bestellstatus abfragen zu Bestellung …”; these types are described under Tools. The headings of these types and of the built-in tools follow the language of the answer the card appears under: English under an English answer, German under a German one. If the answer is in neither German nor English, the conversation's language applies and, if that is neither German nor English either, the version's; without an English version the heading is then in German. The headings of the built-in tools read:

When a tool may not run

Before a call becomes a suggestion or runs, the service checks a few conditions. If one fails, the card goes straight to failed and carries its own heading. These headings also follow the language of the answer as described above:

If an answer needs more than five rounds of tool calls, the assistant stops and writes in the conversation: “I needed too many steps in a row and stop here. Please tell me which part of it you need.” If your account is throttled because it has reached the warning threshold of its quota, this happens after the first round.

Prefilling a form on the page

After Confirm, a form tool fills in a form on your page. This happens once per approval: a repeated click or reloading the history does not fill anything again. The card then states what happened: “n field(s) filled in. Please check them and send the form yourself.”, or for a form that is sent automatically, “n field(s) filled in, the form has been sent.” If values could not be entered, for instance a date in the wrong format, “n value(s) could not be filled in.” follows. If the widget cannot find the form on the current page, the card reads “The form was not found on this page. Please fill it in yourself.” Setup and field mapping are described in Form prefill.

Basket on the card

• The card of a basket tool lists up to 12 lines. For more than one item, each line states the quantity, then the title and the price for that quantity, such as “2 × title · amount”.
• Below that, only the lines with values appear: Subtotal (if it differs from the total), Coupon with code and the amount deducted, Shipping with an amount or “free”.
• Total follows. If the basket is below a threshold for free shipping, the line below reads “amount to go for free shipping”.
• Amounts are shown in the basket currency and in the number format of the widget language. Without a currency, the currency code for euro applies.
• If an Address for the basket handover is stored in the tool, the card carries the Continue link. It opens that address in a new tab with a pickup token appended, which your shop uses to take over the basket.

Product cards

The Search the catalogue tool returns hits from your catalogue. Only items listed as available there are shown; an item that is not in the catalogue does not appear in any form. The search compares the search term with title and description. Items the assistant names by their shop ID come before search hits. If hits come from a connected shop, the tool asks the shop for price, strike-through price and delivery time; anything the shop does not report as available is left out. If the shop does not respond, the values of the last sync apply. How the catalogue is filled is described in Catalog and shop.

Four forms

For bundle and also_bought, the main item comes first and is highlighted. If nothing is stored for it, the widget shows only its card. Up to six references to other items are evaluated per item; the widget shows at most six cards in any form. Without a search term or ID, the tool does not search.

The comparison table

The table has the column Criterion and one column per item headed with its title. Where both items have a number and the numbers differ, the better value carries the Advantage mark. A missing value reads “not stated”.

Card layout

A card shows only the lines for which the catalogue has values, in this order:

• Image: placed before the text, 48 × 48 pixels and cropped to fit. It appears only with an https address, loads only once the card scrolls into view and has no alternative text. The window's security policy allows images from the address the window itself is served from, as data: addresses and from any https address; an image over http does not appear. You maintain the image address in the catalogue, see Catalogue and shop.
• Title: links to the product page if an http or https address is stored, and opens it in a new tab. If the card has no button, the whole card is that link.
• Price: amount in the item's currency, written according to the window language – with a decimal comma in the German window and a decimal point in the English one. If the currency is missing, the catalogue's price text is shown: the amount written in German, with two decimal places and a decimal comma, without a currency code.
• Strike-through price: only if the old price is above the current one and a currency is given. “Was” with the struck-out amount, plus “You save amount (n %)”.
• Rating: values above 0 up to 5, such as “4.5 out of 5 (12 reviews)”; for a single one “(1 review)”.
• Delivery time in business days from 0 to 365: “Ships today” for 0, “Delivery: 1 business day”, otherwise “Delivery: n business days”.
• Features: up to six, each at most 60 characters.
• Button: per item you set Add to cart or View product. It appears only if the matching http or https address is stored, and opens it in a new tab. For screen readers the button also states the title.

Rating an answer

• Below every answer from the assistant, “Was this helpful?” appears with the buttons Yes and No. The bar appears once the answer has finished arriving, and after a reload with the saved rating.
• There are three states: helpful (1), not helpful (0) and no rating (null). A second click on the chosen rating withdraws it.
• The choice shows immediately and is saved afterwards. If saving fails, the display returns to the previous state and the status line reads “The rating could not be saved.”
• After consent has been withdrawn, the buttons no longer accept anything. Messages from staff and the notices during a takeover carry no rating.

In the app, the rating appears on each answer under Conversations as Visitor rating: Helpful, Not helpful or No feedback. It is separate from the Rating of this reply given by your team; neither overwrites the other. Analytics counts the Visitor ratings and shows the share Rated helpful. More in Conversations and Analytics.

A member of staff takes over

Under Conversations, your team can take over a widget conversation. From then on the assistant no longer answers in that conversation; what the visitor writes is saved and answered by a person. Anyone with the role Edit or higher may do this. Roles are described in Team and roles, the conversation view in Conversations.

In the app

• Take over conversation starts the takeover and also makes you responsible. Next to it is the notice “Without taking over, your message does not reach the visitor: the assistant answers in the widget.”
• During the takeover the view reads “You are handling this conversation. The assistant does not answer.” with the time of the takeover. If someone else is handling it, it reads “Name is handling this conversation.”
• Only the person who took over can write in the conversation. The message appears to the visitor with the sender Staff. Without a takeover the service refuses writing into a widget conversation with 409 not_taken_over; the app then shows “This conversation has not been taken over. Take it over before you write to the visitor.” If another person has taken over, Your message and Send are locked for you; if your view still shows an older state, the message names who took the conversation over and the page fetches the current state.
• End takeover returns the conversation to the assistant. You remain entered as responsible.
• A second click on Take over conversation does not change the time of the takeover.

When a takeover is refused

What the visitor sees

• If the visitor writes into a conversation that has been taken over, the answer stream ends without text. The status line reads “A member of staff has joined and is answering personally.” The same happens when resuming after a reload if the conversation is taken over.
• From then on the window checks for new staff messages every 6 seconds and shows them with the sender Staff. A tab in the background does not check; a single failure does not stop the checking.
• After 300 rounds, about half an hour, the checking stops. Rounds in which the tab is in the background do not count towards this.
• Once a conversation exists, the window also checks every 30 seconds whether your team has taken over, as long as the window is open and visible and the visitor has typed or clicked in it, opened it or brought the tab back to the foreground within the last half hour; it also checks on opening and on returning to the tab. If your team has taken over, the status line from the first point and the staff messages written so far appear without the visitor writing, and checking every 6 seconds begins. After a reload their messages are in the history with the sender Staff.
• When your team ends the takeover, the line reads “The assistant is answering again.” and the assistant answers the next message again.

Files from visitors

Visitors can attach images and PDF files to a conversation if you enable it for the assistant: under Assistants in the section Chat window on your website, with the checkbox Accept files from visitors. It is off by default. The other fields of this section are described in Widget settings, the assistant itself in Assistants.

What is accepted

Attaching a file

• The Attach a file button next to the input field opens the file picker. If there is no conversation yet, the widget starts one first and sends the file afterwards.
• Before uploading, the widget checks size, type and number itself and reports straight away: “That file is too large (at most 5 MB).”, “That file type is not accepted.” or “At most 5 files per conversation.” If the browser does not know the type, the service decides.
• During the upload the status line reads “Uploading…” and the button is disabled.
• Attached files appear as a list with name and size in MB between the conversation history and the input field. The name is not a link; the file cannot be opened again in the widget. After a page reload, the widget fetches the list again.
• After consent has been withdrawn, the widget no longer accepts files.

When the service refuses a file

Files in the app

Under Conversations, a conversation's files are listed under Visitor attachments with name and size; without files the list shows No attachments. Clicking the name fetches the file. If an enquiry arises in the conversation, the files are attached to it, including those the visitor sent earlier; the line then shows “hangs on the enquiry”.

Limits per visitor

Widget requests pass two stages. If one is exceeded, the service responds with 429 and the widget shows a waiting line with the remaining time (see “Sending” and “Resuming” above). When attaching a file, it reads “Too many requests in a short time. The file was not attached — please choose it again in … .”; if the service states no waiting time, 30 seconds apply. Until that time has passed, the widget uploads no further file and shows the remaining time instead; afterwards it clears the line unless something else is shown there. The limits apply per visitor, not to your account as a whole; how many answers your plan includes is governed by the quota in Plans and quotas.

• A visitor is the address together with the widget key; with IPv6, the whole /64 network counts as one address. The limits from your account are counted in two places: at this address and, once a conversation exists, additionally per conversation. Either counter can refuse. Visitors behind a shared address, for instance in a company network or with IPv6 in the same /64 network, therefore share that address's counter for each widget; for sending, by default 10 questions per minute and 200 per day.
• The minute catches a burst, the day a steady long-running load. Only what has not already been refused is counted.
• A value below 1 switches the respective limit off.
• A refusal from your account's limits carries error too_many_requests, limit_per_min, limit_per_day and wait in seconds, plus the Retry-After header.

How limits and waiting times work across the API in general is described in API limits; all public widget calls are listed in Widget API endpoints.

Frequent questions