Conversations

The Conversations area lists your assistants' conversations from the widget, from test conversations and from the API. You can filter and search the list, read a history with citations, verification and tool calls, take over a running widget conversation yourself, hand over to a human, flag and tag, block visitors and decide how long conversations are kept. This page covers the fields, limits, roles and messages involved.

Where to find conversations

Conversations sits in the sidebar in the Work group; its address is https://app.xicbot.de/gespraeche. The page opens with: “Every conversation is tied to the version that applied when the answer was given. Test an assistant here before a visitor sees it.”

Two tabs split the list: All conversations and Inbox. The Inbox shows only “Conversations handed over to a human and still open.” If no handover is open, it reads “No open handover. As soon as a conversation is handed over to a human, it appears here.” How handovers are routed and worked through is described on the Inbox page.

A link from the case list opens the matching conversation directly; the address then carries ?g= with the conversation ID (see Appointments and cases). While there is no conversation yet, the page reads: “Conversations are created as soon as visitors write to an embedded assistant. You can start a conversation of your own in the “Test conversation” section.”

Who can do what

The roles build on each other: Read, Edit, Administration, Owner. Each role can do everything the roles below it can. With the Read role the work panels say “With the Read role this area is view-only. Changes need at least the Edit role.” Roles are assigned under Team and roles.

Filtering and searching the list

The Filters area sits above the list. Filters applies the selection, Reset filters clears every field and resets the sort order to start time, newest first. Next to the buttons you see the number of matches, for example “128 matches”.

• The search covers titles and messages. The owner searches the plain text. All other roles only find what they can see, which is the masked text: searching for an email address that the list shows as [E-Mail] returns no match for them.
• If a search in the masked text finds more than 20000 conversations, it is rejected rather than cut short. Narrow the date range, assistant or channel in that case.
• The characters % and _ in a search term are treated as ordinary characters.
• A filter value in the wrong format is rejected, not ignored.

The list

The list shows 25 conversations per page. Back and Next move between pages, with “Page 2 / 7” or similar in between. Open handovers carry the badge “Inbox · Frustration signals: 3”, flagged conversations show “Flagged” followed by their tags.

• Sort order: time (start), messages, frustration signals, status or Handed over. Clicking the selected field toggles between descending and ascending; a new field starts descending. The default is the start time, newest first; ties are broken by the ID.
• Fields per row: assistant, title, state, channel, language, messages and time can each be unchecked. “Unchecked fields disappear from the list. The choice applies to this browser and survives a reload.”
• Search the list in the List in this area column narrows the loaded page by title, assistant, origin and channel without a new request.
• Refresh list: every 30 seconds the page checks in the background whether the list has changed, as long as the window is visible. The rows stay as they are. If you are on the first page, conversations have been added and a different conversation is now at the top, “There are new conversations.” appears above the list, in the Inbox tab “There are new handovers.”; for other changes, including on later pages, “The list has changed in the meantime.” Next to it is the Refresh list button; it reloads the page you are on. While a search under Search in title and messages applies, the page does not check.

Downloading the list as CSV

Filtered conversations as CSV downloads the conversations matching your filters as the file conversations.csv. While it runs the button reads “Exporting …”, afterwards “128 rows exported”. Next to it: “The export contains masked text only.” CSV export is one of your plan’s limits; under Billing it is called Conversation export. If your plan does not include it, you see: “Your plan does not cover this. See Billing for the overview.” More under Plans and quotas.

• Columns: id, created_at, assistant, channel, language, status, messages, title, escalation (reason for the handover). The separator is a semicolon, line endings are CRLF, the encoding is UTF-8; every field is quoted.
• The order follows the list's sort order. Title and handover reason are masked.
• At most 5000 conversations per file. If the filters match more, no file is created and you see “Too many conversations for one export. Please narrow the date range.”
• If a field starts with =, +, -, @ or a tab, an apostrophe is put in front so spreadsheet software does not read it as a formula. Line breaks inside a field become spaces.
• The export is recorded in the activity log before the file is delivered, with the row count and filters. For a search term, the log only notes that a search was used. If the entry cannot be written, the masked file is still delivered; a plain-text file is not.

Test conversation

In the Test conversation section you pick an Assistant and start a conversation in the Test channel with Start conversation; meanwhile it reads “Starting …”. This needs the Edit role and an active version of the assistant, otherwise no conversation is created. If there is no assistant yet, it says “Create an assistant first.” The conversation is tied to the active version and opens with its greeting. How to check an assistant before release is described in Test and acceptance.

Conversation details

Clicking a row opens the conversation. The header shows assistant, status and language, below it the channel and, where one is stored, the Origin with at most 120 characters. For widget conversations this is the website the widget ran on. For test and API conversations it is the host name from the request's origin information (Origin, otherwise Referer); a test conversation you start in the app therefore shows the app's address. A conversation's title is derived from the first question and holds at most 120 characters. Below follow the Channel line, a line about masking, the history and, at the bottom edge, Your message; the input field stays there even when the history is long. On opening, the newest message sits directly above the input field. Below the input field come the boxes Handover, Flag and note, Attachments and plain-text access and Block visitors; they are open and can be collapsed via their heading. A box in which an error message appears opens by itself.

History as CSV

This conversation as CSV downloads the history as gespraech-<id>.csv; while it runs you see “Creating file …”, afterwards the number of “rows in the file”. The columns are time, role, text, state, rating, tool_key and tool_state; messages and tool calls each get their own row. The file name carries only the ID, not the title, because the title comes from the visitor. If the file is cut short, the view says: “The file shows an excerpt: very long histories are cut off at 500 messages and 500 tool calls.” This file is also part of your plan’s CSV export, see Downloading the list as CSV.

Taking over a conversation

The Channel line directly below the header shows the channel and the “last update” and says who is answering: without a takeover in the widget, “The assistant answers.” For widget conversations it offers Take over conversation, because only there is a visitor at the other end. As long as nobody has taken over, it says next to it: “Without taking over, your message does not reach the visitor: the assistant answers in the widget.” The same sentence and the same Take over conversation button also appear below the locked Your message field.

• After taking over, you see “You are handling this conversation. The assistant does not answer.”, everyone else sees “… is handling this conversation.” with the person's name and the time after taken over.
• Whoever takes over is also set as the assignee. A second click does not reset the time.
• If someone else has taken over, you can neither take over, end the takeover nor write. If your view still shows an older state, “… has already taken over this conversation. Only the person who took it over can write in it or release it.” appears with the person's name, or their email address if no name is set, and the page fetches the current state of the conversation.
• If the visitor has withdrawn consent, the conversation cannot be taken over.
• While a person is handling the conversation, a new visitor message does not go to the assistant; no assistant reply is created.
• If the person who took over no longer belongs to the team, or nobody is assigned to the takeover any more, it counts as free: you can end it, take over yourself or mark the conversation as done.
• End takeover hands the conversation back to the assistant. The assignee stays; you change it in the Inbox.

After a takeover the widget shows “A member of staff has joined and is answering personally.”, and your messages appear there under Staff. The widget checks for new messages every 6 seconds while its window is visible and stops on its own after half an hour. After the takeover ends, the widget says “The assistant is answering again.” More on the visitor's view under Chat in the widget.

While a widget conversation is open, the page fetches new messages every 5 seconds as long as the window is visible; below the history it says “New messages appear here on their own while this window is visible.” While the window is in the background, fetching pauses and resumes as soon as you return. Along with the messages, the status, assignment and takeover are updated, and for a handover also its time, Frustration signals and Reason for the handover. Anything you have typed into fields, including tags and the note, stays untouched, and if you are at the newest message, the view moves along; if you have scrolled up in the history, it stays there. New visitor messages are announced to screen readers. If no new message arrives for half an hour, fetching pauses: “No new message for half an hour – refreshing is paused.” Check again resumes it. If the history cannot be fetched, it says “New messages could not be fetched just now. The page keeps trying.”; such attempts do not count towards the half hour. If the conversation has been deleted in the meantime, fetching ends and the panel only shows “This conversation no longer exists. It was deleted or removed after the retention period.”, see Messages. The page also fetches a widget conversation marked as done: if the visitor writes in it again, their message reopens it, and the new status arrives with it. Conversations from tests or the API are not fetched again.

Handing over to a human

• Why hand this over? takes a reason of up to 200 characters. Without input, “Von Hand übergeben” (handed over manually) is stored. Hand over to a human sets the status to handed over and moves the conversation into the inbox.
• If a reason was already stored, the new one is appended after a semicolon; together at most 300 characters.
• If the conversation is already handed over and open, the field and button are not shown; instead it says “The conversation is in the inbox. Additions to the reason belong in the internal note.” If the assistant has handed it over in the meantime while your view still showed the old state, it stays unchanged and you see “The conversation was already in the inbox. Your reason “…” was not saved; add it to the internal note if needed.”, without a reason “The conversation was already in the inbox. The click changed nothing.”
• Manual handovers also run through the routing rules, see Inbox.
• The box shows Frustration signals with the score, the Reason for the handover and the time of the handover.
• Mark as done appears while the handover is open. It sets the status to closed and adds “done” next to the time; the reason stays. If you are handling the conversation yourself, your takeover ends with it and the assistant answers again. If another person on the team is handling it, it is not marked as done, and you see “… has already taken over this conversation. Only the person who took it over can write in it or release it.” Connected systems receive the conversation.ended event once per closing; a conversation that is already closed stays unchanged. While handing over or marking as done is running, the button is locked. If the visitor then writes again in the chat window, or your system asks again through the API, the message reopens the conversation and it is back in the inbox, see Inbox.

Flags, tags and internal notes

• Flag this conversation sets a flag with a timestamp (“flagged since …”), Remove flag takes it back. Flagged conversations show “Flagged” in the list.
• Tags: “Comma separated, ten at most, up to 40 characters each.” Surrounding spaces, empty and duplicate entries are dropped.
• Internal note up to 2000 characters: “For your team only. Neither the widget nor the data export hands this note to the visitor.”
• Save tags and note stores both; afterwards you see “Note saved.” Only fields that are sent are changed. An empty note removes the note.
• Flag, tags and note come from your team and are not masked.

Messages

The history starts with the greeting of the Assistant. Questions appear under You in a test conversation and under Visitor in widget and API conversations, your team's messages under Staff with the person's name, replies under Assistant. Without any message it says “No message yet.” A reply that is not complete shows its state:

• Citations: below a reply you see the first three sources it relies on; if there are more, a link such as “+ 2 more” reveals the rest. Citations are not masked.
• Verification: Not measured, No checkable claim, All claims covered, Uncovered claims or Answered without source material. With uncovered claims you see “Uncovered claims: 2” with the kind (price, percentage, deadline, quantity, promise, email address, URL, phone number) and the position (“Characters 12 to 30”). How verification works is described under Knowledge and answers.
• Rating of this reply: Helpful or Not helpful; without a rating it says “Not rated yet”. Only assistant replies can be rated, from the Edit role upwards. Clicking the chosen rating again withdraws it.
• Visitor rating: the feedback given in the widget, otherwise “No feedback”.
• Usage: input and output tokens, duration in milliseconds and “first character after” with the wait until the first character.

Tool calls

A tool call appears as its own Tool card in the history, with its state and duration in milliseconds, followed by Input, Result or Error. The states are proposed, confirmed, executed, declined, expired, failed and timed out. If a call is waiting for approval (“Waiting for confirmation.”), users with the Edit role or higher decide with Confirm or Decline. In widget conversations the visitor decides in the chat window; the card then shows “Waiting for the visitor to confirm in the chat window.” and no buttons. Free-text values in tool data are masked like messages. Setting up and running tools is described under Tools.

Writing yourself

Your message takes up to 4000 characters, Send submits it. If a shorter maximum length is set for your account, that limit applies. In a test or API conversation the assistant then replies; meanwhile the button reads “Answering …” and Cancel stops waiting. A test or API conversation marked as done stays done unless your message triggers a handover; an API conversation is reopened by the next question your system sends through the API. If the reply is not complete, the line above Your message then names its state, such as “fallback answer”, “quota used up” or, once the conversation has reached its maximum number of questions, “conversation message limit reached”. If a reply is already running, you see “An answer to this question is already running.” In a widget conversation a message only goes out after taking over: it then appears under Staff in the history, and no assistant is asked. Without a takeover the field is locked, and below it you read “Without taking over, your message does not reach the visitor: the assistant answers in the widget.” together with the Take over conversation button; after that the field is free. After sending, the history and the header are reloaded; anything you have typed into other fields, such as reasons, tags and the note, stays, and so does plain text you requested. If another person on the team has taken over the conversation, Your message and Send are locked for you, whether it is a widget, test or API conversation; below the field it then says “… is handling this conversation.” with the person's name.

Masking and plain text

The list, the detail view and CSV files show personal data masked; the detail view says: “Personal data is masked: email, phone, IBAN and postal address.” The history is stored as it was written. Masking only happens on output, so that a complaint can still be traced later.

• Masking covers message text, title, handover reason, the values in tool calls and the wording of unsupported statements. Citations from your knowledge base, tags, note, queue and the Origin stay unchanged.
• When in doubt, text is masked. If masking itself fails, [nicht maskierbar] replaces the text.
• The handover email is not masked: when a handover goes to the address stored for it, the email carries up to the last 200 messages and any contact details supplied, exactly as written. This is why only the account owner can change that address, see Assistants.
• If you have requested plain text, it stays in place while new messages arrive. The new ones appear masked with the note masked, and the box says “New messages are masked.” This also applies to your own messages after sending. The page does not request plain text for them on its own: every request is logged. Request plain text again asks for a reason as the first time did. A Reason for the handover that is already shown also stays in plain text.

1. 1

   Step 1

   Request plain text

   Only the owner sees Request plain text. Other roles read: “Only the account owner can request the plain text – with a reason, and every access is logged.”

2. 2

   Step 2

   Give a reason

   Reason for this access is required, 5 to 200 characters, with no default. If it is shorter, you see “Please give a reason of at least five characters.”

3. 3

   Step 3

   Show plain text

   Show plain text first writes the log entry and only then returns the text. If the entry cannot be written, the text stays masked.

4. 4

   Step 4

   Read

   Above the history it says “Plain text visible – this access is logged.” The list keeps showing the masked version.

Plain-text access lists the last 20 uses of Show plain text on this conversation with time, the person's email address and Reason; plain-text exports do not appear there. If there has been no access yet, it says “No plain-text access so far”. The obligations behind this are described under Privacy and legal.

Attachments

Visitor attachments lists the files the visitor added to the conversation, with name and size in MB. If an attachment belongs to an enquiry, “hangs on the enquiry” follows it. Clicking the name downloads the file; this works for every role, counts towards the limit of 30 calls per minute per signed-in user and is recorded in the activity log. If the entry cannot be written, the app does not download the file and shows “Not saved: the entry in the audit log could not be written. Please try again.” Without attachments it says “No attachments”.

Blocking visitors

The Block list section in the detail view blocks the visitor of the open conversation. Administration and Owner can set and lift blocks; other roles see the list and the notice “Setting and lifting blocks needs the Administration or Owner role.”

• Block visitor sets the block. An address block also applies to later conversations: the visitor cannot start a new conversation. A conversation block applies to this one conversation only. If the log entry cannot be written, the block is neither set nor changed.
• The check runs when a conversation starts (address only) and on every widget message (address and conversation). Withdrawal, access requests and deletion remain open to a blocked visitor, see Consent and visitor rights.
• A test conversation has no visitor address. There you see “No visitor address is stored for this conversation – only the conversation itself can be blocked.”
• Blocking the same address again updates the existing block: reason and period are overwritten, the counter of rejected attempts stays.

The list shows up to 200 blocks of your account, newest first, each with kind, reason, expiry (“no end date” or a date), the number of rejected attempts (“3 rejected”) and the state Blocked or expired. Expired blocks no longer apply but stay in the list. Without blocks it says “No block set”. Lift removes a block; the log records it first, and without that entry the block remains.

Retention periods

Below the list is the Retention periods section. There you set for how many days conversations are kept, 1 to 3650 per field:

A new account starts with 90 days for all conversations; the page explains: “A new account starts with 90 days for all conversations. Leaving “All conversations” empty is a deliberate choice: conversations without a period of their own are then not deleted.” Periods count from the start of a conversation. Save stores all three fields and reports “Saved.” The change is recorded in the log; if the entry cannot be written, the old period stays. Administration and Owner can change the periods; for everyone else the fields are locked and it says “Retention periods can be changed by users with the Administration or Owner role.” If the current state cannot be loaded, you see “The current state could not be loaded.” More under Retention and deletion.

Deleting a conversation

Administration and Owner see Delete in every row. You confirm the question “Delete this conversation with all messages?” with Delete or dismiss it with Cancel; focus starts on Cancel. Deletion is final. The list then reloads; if it was the last conversation on a page, it shows the last page that still exists. It is recorded in the log first, in the same step; if the entry cannot be written, the conversation stays and the message says so. Other roles see “Deleting conversations needs the Administration or Owner role.” below the list.

Messages and errors

If an action fails, the message appears at the top of the page below the heading. Messages about plain text and blocking appear in their own section, an error while loading the open conversation inside the conversation itself. Which message you see depends on the cause:

If you have opened another conversation in the meantime, the message names the conversation the action failed on, with assistant, title and start, for example “The conversation “…” was not deleted: …”. Similar messages exist for tags and note, handover, changes and Mark as done.

Via the API

Everything on this page is also available via the API. Every call needs a sign-in, an active account and a confirmed email address; roles apply as in the app. The basics are under API basics, limits under API limits and examples under API: conversations and management.

Frequent questions