Inbox and routing

The Inbox collects the conversations that were handed over to a human and are not yet done. There you decide who takes care of a handover, mark finished cases as done and maintain the rules under Routing that assign new handovers to a queue and, if you like, to a person. This page describes the fields, messages and limits involved.

Where to find the inbox

The Inbox sits in the sidebar in the Work group right below Conversations; its address is https://app.xicbot.de/postfach. The page has two parts: the list of open handovers at the top and the Routing section with the rules below it. When a handover is waiting, the number of open handovers appears next to Inbox; screen readers announce, for example, “3 open handovers”. It is counted when the app loads, then every minute while the window is visible, and right after a handover, a resolution or a deletion on the Conversations and Inbox pages. If you switch accounts, the number disappears until the one for the new account has been counted. If the number cannot be fetched, none is shown, not even 0.

The Conversations page shows the same conversations in its Inbox tab, with 25 rows per page and paging. In the conversation list, a conversation that is handed over and still open carries the badge “Inbox · Frustration signals: …” with its score. See Conversations.

How a conversation reaches the inbox

A conversation is in the Inbox as long as its status is handed over and it has not been marked as done. It gets there in six ways, and each one appends a reason to the Request field:

Each reason is appended to the existing Request with “; ”. The field holds at most 300 characters; anything beyond is cut off at the end. Frustration signals are recorded even below the threshold, so the request of a handover can contain signals from earlier messages. The reasons are written in German: Bitte um einen Menschen ("…") (asks for a human), Ärgerliches Wort ("…") (angry word), Sensibles Thema: … ("…") (sensitive topic), Tabuthema ("…") (taboo topic), Frage zum N. Mal gestellt (question asked for the Nth time), Überwiegend großgeschrieben (mostly capitals), Häufung von Frage- und Ausrufezeichen (many question and exclamation marks) and Zweimal in Folge keine echte Antwort (no real answer twice in a row). For a sensitive topic one of these labels follows: medizinisch, rechtlich, Finanzierung, Allergie, Notfall, Beschwerde, Datenschutz, Zahlungsdaten. On the assistant you set the threshold under Custom handover score and add words to these topics under Custom trigger words per topic; the points per signal and the topics themselves cannot be changed, see Handover to a human. The tool is described under Tools.

What happens on every handover

1. 1

   Step 1

   Routing

   The rules under Routing assign the handover to a queue and, if configured, to a person. This happens first, so that everything after it already knows the queue.

2. 2

   Step 2

   Event for connected systems

   The event handoff.triggered goes out with conversation_id, reason (the reason, masked as in the app, at most 300 characters) and queue; queue is null if no rule matched or the assignment failed. How to receive events is described under API keys and webhooks.

3. 3

   Step 3

   Email to the handover address

   If a Handover address is set on the assistant, an email goes there. A manual handover with Hand over to a human on the Conversations page sends none: whoever hands over there already has the case in front of them. The address of the version the conversation belongs to applies. Without an address nothing is sent, and the handover is only in the inbox. If the email cannot be sent off, the handover stands all the same.

When the assistant hands over through the tool Hand over to a human, XICBOT also creates an enquiry: with name (up to 120 characters), email address (up to 190 characters) and phone number, as far as the visitor gave them, and the reason as its subject. The lead.created event only goes out when the enquiry is first created. If the same call with the same details arrives a second time in the same conversation while it is handed over, nothing changes: no second enquiry, no second email, the reason is not appended again, no routing and no second handoff.triggered. If the conversation has been marked as done in the meantime, the same call hands it over again, with routing and handoff.triggered, but without a new enquiry and without an email. If routing or the email fails after the enquiry has been created, the call still counts as carried out: enquiry and handover stay in place. The tool tells the assistant that the conversation is now in the inbox and a human will get in touch; how the business is notified is not something it should tell the visitor.

The handover email

• Subject: “Übergabe aus dem Chat” (handover from chat) followed by the assistant's name. The preview line starts with “Ein Besucher möchte mit einem Mitarbeiter sprechen” (a visitor would like to talk to a staff member) and names the request; the first paragraph reads “ein Gespräch mit dem Assistenten „…“ wurde an einen Mitarbeiter übergeben.”
• The “Kontakt” block shows name, email, phone and request, as far as available. For handovers without the tool it only shows the request; if everything is missing it shows “Kontaktdaten: nicht hinterlassen” (contact details: not provided).
• The button “Gespräch öffnen” (open conversation) leads to the conversation in the app.
• If the visitor gave a valid email address, it becomes the reply-to address, and the email says: “Eine Antwort auf diese E-Mail geht direkt an …” (a reply goes directly to …).
• Under “Gesprächsverlauf” (conversation history) you find the messages up to the handover, at most the last 200, each labelled Besucher, Assistent or Mitarbeiter with date and time; empty messages are left out. If the history is longer, the email says: “Der Verlauf ist länger als 200 Nachrichten. Diese Nachricht trägt die letzten 200; der vollständige Verlauf steht in der Oberfläche.”
• It ends with “Sie erhalten diese E-Mail, weil Ihre Adresse für Übergaben aus dem Chat hinterlegt ist.” The email is written in German, whatever the language of the conversation.
• If the conversation is deleted before the email goes out, it is dropped. If the tool's enquiry has been deleted in the meantime, the email names no contact details.
• If a conversation is first handed over by frustration signals and afterwards again by the tool, two emails arrive.

The list of open handovers

Above the table you see the number of open handovers, for example “12 open handovers”. The list is sorted by the time of handover: whoever has waited longest is at the top. One page shows 50 handovers. If there are more in the inbox, a line above the table says which part is shown, for example “Showing handovers 51 to 100 of 120, longest-waiting first.”, and below the table you page with Back and Next, with “Page 2 / 3” between them. Changing the filter takes you to the first page. If the current page is empty on reloading because handovers have since been marked as done, the list jumps to the last page that still exists. The rows do not change on their own: every 30 seconds the page checks in the background while the window is visible. New handovers go to the end of the list. If handovers have been added and the end of the list is on the page you are viewing, “There are new handovers.” appears above the table, for other changes “The list has changed in the meantime.”, together with the Refresh list button; the list reloads only when you click it.

The inbox shows Title and Request masked: email addresses appear as [E-Mail], phone numbers with seven or more digits as [Telefon], IBANs as [IBAN] and postal addresses as [Adresse]. If masking fails, [nicht maskierbar] is shown. The Queue is not masked, as it comes from your rules. See Privacy and legal.

The Assigned to choice lists the people in your team sorted by email address, with their name or, if none is set, their email address. At most 200 are loaded; if there are more, the line “The first 200 people are shown.” appears above the table. If the team list cannot be loaded, the choice is locked, in the rows as in the form for rules. Whoever may make changes then sees above the table and below the form “The team list could not be loaded. A responsible person can be selected after reloading the page.” A person already assigned is still shown by name; Take on and Release remain usable.

Filter and empty list

The Queue field above the table filters the list. The options are All queues, No queue and every queue used in a rule; the list reloads as soon as you choose and starts on the first page. The queue of a deleted rule disappears from the options even if handovers are still in it. The name none stands for No queue and cannot be given to a queue in any capitalisation, not even as None or NONE. An older rule that already has the lowercase name none does not appear in the options; you find its handovers under All queues.

• “Loading …”: the list is being fetched.
• “No open handover.” with the sentence “As soon as a conversation is handed over to a human, it appears here. Which queue it goes to is set below under “Routing”.” and the Routing button, which jumps to the rules section.
• “No open handover in this queue.” when a filter is set, with “The “Queue” filter hides handovers in other queues.” and the Reset filters button.
• If the list cannot be loaded, only an error message appears in its place, without the empty-state sentence and without a table.

Assignment and availability

Choose a person under Assigned to and they are assigned at once; Nobody releases the handover again. Take on assigns you, even if someone else is already set; if you already are, the button reads Release. Below the choice “assigned since” shows the time of assignment. Only that one row is redrawn afterwards. The chosen person receives no notification. Being assigned does not mean running the conversation: the assistant only falls silent once someone takes over the conversation on the Conversations page.

Availability is not on the inbox page but at the bottom of the sidebar in the Availability group. There you see “Available” or “Unavailable”, below it “available since” with the time when you are available, otherwise the sentence “Anyone marked available is shown in the inbox as available for a handover.” The button reads Mark me available or Mark me unavailable and is disabled while the switch runs. You only switch your own availability, with any role. Switching on again keeps the first time, switching off clears it. If the switch fails, the previous state stays and a message appears below the button. The button only appears once your email address is confirmed; until then its place reads “You can mark yourself as available once your email address is confirmed.”

Mark as done

Mark as done takes effect at once and without a confirmation. The conversation gets the status closed and leaves the inbox, and the list reloads; until then the button is locked. If you are handling the conversation yourself, your takeover ends with it and the assistant answers again. If another person is handling it, it is not marked as done: you see “… has already taken over this conversation. Only the person who took it over can write in it or release it.”, and the list reloads. Request, Queue and Assigned to stay on the conversation, so it remains clear later why it was in the inbox. Connected systems receive the event conversation.ended with conversation_id and assistant_id, once per closing: if two people marked the same conversation as done, the first time stays. The same button exists in the detail view on the Conversations page.

Routing

The Routing section below the list shows the sentence “The first rule whose keyword occurs in the request sets queue and assignee. Rules are checked from top to bottom.” Below it each rule has a row with queue, keywords, assigned person or Nobody and the state Active or Paused. Without rules it reads “No rule yet. Without a rule every handover stays without a queue.” If the rules cannot be loaded, an error message appears there instead, and the form for adding rules is missing.

How a handover is matched

• The reason of this handover is compared together with the title of the conversation, which is the visitor's first question. For a manual handover this is the reason entered, for the tool the reason from the call, otherwise the request as it then stands on the conversation.
• Upper and lower case do not matter, and a keyword also matches inside a word: “rechnung” matches “Rechnungen” and “Abrechnung”.
• Only rules in the Active state count, in the order of the list. The first rule with a matching keyword wins; further matches do not matter.
• If no rule matches, the handover stays without a queue and without an assigned person. There is no catch-all rule.
• If the conversation already has a queue, it stays, and routing does not set a person either.
• A rule only sets its person if nobody is assigned yet and the person still belongs to your team; otherwise it only sets the queue. If it sets the person, the assignment gets the current time.
• If the rules cannot be read at the moment of handover or the assignment fails, the handover still reaches the inbox, just without a queue, and the handoff.triggered event still goes out.
• Routing only runs at the moment of handover. A new or changed rule has no effect on conversations already in the inbox.

Rule fields

Add rule puts the new rule at the end of the list and then clears the three fields. Before sending, the page checks the entries: if Queue is empty or named none in any capitalisation, if no keyword is given, or if there are more than 20 keywords or one is longer than 60 characters, the message appears at the affected field, and “Please check the marked fields.” appears at the top of the page. The form only appears with the Edit role or higher, while fewer than 50 rules exist and the rules have loaded. An existing rule cannot be edited in the app: delete it and add it again, although it then sits at the end.

Order, pausing, deleting

• Move up swaps the rule with the one above it. The top rule does not have this button.
• Pause sets a rule to Paused, Activate sets it back to Active. A paused rule keeps its place but is skipped on handovers.
• Delete asks in the row: “Delete this rule? New handovers will then be routed without it.” Only Delete next to it removes the rule, Cancel keeps it. Handovers that already got a queue from it keep that queue.

Each of these changes and every new rule first writes an entry to the audit log, with queue, keywords, person, position and state; on deletion the state before deleting. If the entry fails, everything stays as it was and the top of the page shows “Not saved: the entry in the audit log could not be written. Please try again.”

Who may do what

With the Read role you see the list and the rules but no button to change anything, and the Assigned to choice is disabled. In the Routing section and, as soon as there are handovers in the list, below their count the page then shows “With the Read role this area is view-only. Changes need at least the Edit role.” The page shows the same sentence if the server rejects a change because of the role. Roles are described under Team and roles.

Messages

Errors of an action appear at the top of the page below the introduction. If the list or the rules cannot be loaded, the message appears in that place; input errors when adding a rule appear at the field.

Via the API

All calls are under /api/v1 and need a signed-in session with a confirmed email address. Further filters of the conversation list and the other calls on conversations are described under API: conversations and management.

Frequent questions