Create and approve tools

Tools let an assistant act in a conversation rather than just answer: capture an enquiry, book an appointment, hand over to a human, search the catalogue or query a connected system. Every tool belongs to one assistant. This page explains how to create tools, which tool types are available, how to connect your own interface, which details are required and who may trigger, change and approve a tool.

Where to find tools

Open Triggers › Tools (app.xicbot.de/werkzeuge). On the Tools tab, pick the assistant whose tools you want to view or change under Assistant. The Assistant tools card lists them sorted by key. The Catalogue tab next to it belongs to product search, see Catalog and shop.

• If there is no assistant yet, the card asks you to create one first.
• The Add tool form only appears once an assistant is selected and the tool list has loaded. Without an assistant, the same hint with Create assistant takes its place; while loading and after a failure it says “The form is available once the tool list has loaded.”
• If the assistant has no tool yet, it says “No tool has been set up for this assistant yet.” Add tool takes you to the form.
• If loading fails, “The list could not be loaded.” appears with a Load again button.
• From six tools on, a Filter tools field appears. It searches by name or type and shows how many entries match. If none does, it says “No entry matches this input.”; Clear filter resets the search.

What a row shows

• The label, with key and description below.
• Tool type, kind and approval, for example “Book appointment · writing · with confirmation”. The kind is read-only, writing or irreversible.
• For a tool that is not active, additionally inactive.
• Minimum role and Required fields with the field names that must be filled when the tool is called.
• On the right, Edit and Delete. Deleting asks first: “Delete this tool? Cases already triggered are kept.” With the Read role only View is shown. Edit and View open the tool in the form, scroll it into view and move the focus to its heading “Edit: …” with the label. After deleting, “The tool has been deleted.” appears below the list heading.

Tool types

The Type defines what a tool does, which fields it expects and whether it reads, writes or acts irreversibly. The selection groups the types. The approval in the last column is the type's default: it applies when a tool is created through the API without approval. In the app, the form starts every new tool on with confirmation; for read-only types you can change it there, for writing and irreversible types it cannot be changed.

The built-in types come with the service. Capture enquiry records name, email, phone and request as an enquiry and attaches files from the conversation. Own interface calls an address of your choice, and the ten types in the other groups also talk to a system you connect. The Tool kit describes how that system has to respond. For enquiries, handoffs and appointments see Appointments and cases, for forms Form prefill, for catalogue and basket Catalog and shop.

What a handover triggers

The Hand over to a human type requires the reason for the handover (reason) and also takes name (name), email address (email) and phone number (phone) if the visitor gives them. The visitor sees the proposal “An einen Menschen übergeben:” with the reason, under an English answer “Hand over to a person:”, and confirms it. The service then carries out these steps in order:

1. 1

   Step 1

   Hand over the conversation

   The conversation gets the status handed over, even if it was already closed. If it is still handed over, the previous handover time is kept; otherwise the handover counts from now. The new reason is appended to any earlier one with a semicolon, up to 300 characters in total.

2. 2

   Step 2

   Create an enquiry

   An entry is created under Cases › Enquiries, with the reason as its Request plus name (up to 120 characters), email address (up to 190) and phone number (up to 60) if given. The Source column shows the key of the tool. If the visitor confirms the same input for the same tool a second time in the same conversation, there is still only one entry, and the result reports duplicate_prevented: true.

3. 3

   Step 3

   Inbox and routing

   The conversation appears in the Inbox. Routing rules are applied and the handoff.triggered event is fired. If the assignment fails, the conversation is in the inbox without a queue, and the event still goes out, then usually with queue: null. If the visitor confirms the same input a second time while the conversation is still handed over, the first step and this one are skipped; if it is no longer handed over, it is handed over again.

4. 4

   Step 4

   Email to your team

   If the enquiry is new, an email to the Handover address is queued, taken from the assistant version the conversation runs on, with priority 3 instead of the usual 5. A repeated call does not send a second email. Inbox describes what the email contains.

5. 5

   Step 5

   Feedback to the assistant

   The result contains lead_id, handed_off: true, duplicate_prevented and, for a new enquiry, email_notified. email_notified: true means the email was queued, not that it was delivered. The assistant is also told that the conversation is now in the inbox and a person will get in touch, and that how the business is notified does not belong in its answer.

Creating a tool

1. 1

   Step 1

   Choose the assistant

   Under Assistant, choose the assistant that should use the tool and click Add tool.

2. 2

   Step 2

   Choose the type

   Set the Type. The default is Capture enquiry. Once the tool is saved, its type can no longer be switched.

3. 3

   Step 3

   Enter the basic details

   Fill in Key, Label and When should the assistant use it?. For Own interface and the types for connected systems, Interface address and Access token are added.

4. 4

   Step 4

   Define fields and required fields

   For Own interface you define under Input fields what the assistant passes on. For Prefill form the fields follow from the mapping. For all other types the fields are fixed and you only choose which of them are Required fields.

5. 5

   Step 5

   Set minimum role, approval and active

   Choose Minimum role and Approval. The defaults are Visitor (public chat), with confirmation and a ticked Active box.

6. 6

   Step 6

   Save

   Click Save. While the service checks, the button reads Saving …. After that the tool is offered to the assistant, provided it is active and matches the role and plan. The form is then empty again, “Saved: …” with the label appears next to the button, and the focus is on the Edit button of the saved tool.

Key, label and description

If the key is already taken for the assistant, the form reports “This key already exists for this assistant.” For tools that do more than read, the service adds to your description on its own: the assistant learns that the call does not run anything straight away but shows the visitor a proposal to confirm or decline, and that it should call the tool no more than once per request. You do not need to write this yourself.

Connecting your own interfaces

Own interface and the ten types for connected systems call an address that you store. There are two fields for this:

• Interface address: required, starts with http:// or https:// and takes up to 500 characters in the form, for example https://example.com/tool.
• Access token: optional, up to 500 characters, entered hidden. If one is stored, it is sent with the call as the header authorization: Bearer …. The service does not hand it back but shows __set__ in its place. Below the field you then see “A token is stored. A new value replaces it, an empty field leaves it unchanged.”
• Through the API, a stored token is kept if token is missing or contains __set__; an empty value removes it.

The address and access token are entered or changed by someone with the Administration or Owner role. With the Edit role both fields are locked: such a tool cannot be created, but the other details of an existing one can be changed. The form states “Address and access token can be changed by the Administration or Owner role. The other details can be changed with the Edit role.”

Which addresses are allowed

The service checks the address when you save and again on every call. http and https are allowed. It does not check the name but every address the name resolves to: if any of them does not point to the open internet, the target is refused. On the call it connects to exactly the address it checked, so a name record changed in the meantime cannot redirect to another target. On save it answers with status 422 and one of these codes. The app shows the sentence from the last column at the Interface address field and also at the top of the page:

What your system receives

Every call is a POST with a JSON body and the headers content-type: application/json and accept: application/json, plus authorization: Bearer … if a token is stored. An Own interface sends the tool key, the input and the conversation ID:

{
  "tool": "delivery_time",
  "input": { "zip": "10115" },
  "conversation_id": "…"
}

The types for connected systems also send adapter, domain, operation and action. If the type does more than read, the call also carries the header idempotency-key: a 64-character key that stays the same for the same input in the same conversation. Your system can use it to spot an order that arrived twice. The Tool kit describes the exact structure.

• Your system has 8 seconds to answer. Through the API, the setting deadline_s sets the limit anywhere from 1 to 20 seconds; the form has no field for it, and saving in the form resets the limit to 8 seconds. Establishing the connection may take at most 5 seconds.
• The service does not follow redirects; a response with status 300 to 399 counts as an error.
• The response may be at most 64 KB, otherwise it is discarded.
• For an Own interface, the service takes JSON as data. If the response is not JSON, it takes the first 2000 characters as text. The status is added.
• The types for connected systems expect a response with the field ok. Only the type's result fields are kept, texts up to 600 characters and lists up to 20 entries.

When the connection fails

A failed call is not retried. It ends with one of the following causes and then shows as failed or timed out in the tool card.

Input fields

The fields define which details the assistant passes on when it calls the tool. For every type except Own interface they are fixed, and the form shows “The fields of this type are fixed and cannot be changed.” For Prefill form they follow from the mapping to your form. For an Own interface you create them yourself under Input fields:

The service cleans up what the assistant passes on before the call: it keeps only fields that are in the schema, shortens texts to 2000 characters and lists to 50 entries.

Required fields

Under Required fields you tick which fields must be filled when the tool is called, up to 20. Some are demanded by the type itself: they are marked “required by the tool type” and cannot be unticked, for example subject for Capture enquiry, starts_at for Book appointment and reason for Hand over to a human. If a type has no selectable fields, it says “This tool type has no selectable fields.” Only fields that exist in the type can be ticked.

A value counts as empty if it is missing, a text of blanks only or an empty list; 0 and false count as given. The service checks when the tool is called and again when the visitor confirms. If something is missing, the call ends as failed with a preview saying the details are incomplete, and the assistant learns which details are missing so it can ask the visitor. The form puts it this way: “Without these the call is refused and the assistant asks for them instead of creating an incomplete entry.”

Minimum role

Minimum role defines who can trigger a tool. The levels build on each other; anyone who reaches a higher level may also use everything below it.

• The chat window on your website counts as a visitor, even if someone is signed in to the app in the same browser. The service does not offer a tool with a higher minimum role there; if it is called anyway, the call ends as failed with a preview saying it is not approved.
• The default is Visitor (public chat).
• When creating a tool you can choose levels up to your own role, so up to Signed in with the Edit role. The form states “You can choose levels up to your own role.” Through the API the service answers a higher level with 403 role_too_low and field: min_role.
• The minimum role of an existing tool is changed by someone with the Administration or Owner role. For everyone else the field is locked, with the note “The minimum role of an existing tool can be changed by the Administration or Owner role.”

Approval

Approval decides whether a call runs straight away or only after a confirmation. For writing and irreversible types it is fixed to with confirmation; the field is locked, even if the API sends something else. For read-only types you choose between with confirmation and without asking. A call only runs straight away if the tool is read-only and set to without asking. An exception is looking up free slots with Book appointment: it changes nothing and therefore runs without confirmation.

Active and turned off

The Active box turns a tool on or off without deleting it. From the assistant's next reply on, the service no longer offers a tool that is turned off, even in a conversation already under way; a call to it then ends as failed with a note that the assistant has no such tool. In the list it carries the addition inactive. A proposal that was already open when you turned the tool off can still be confirmed within its 60 minutes and is then carried out; only deleting the tool ends open proposals. Settings and earlier cases are kept.

Who in the team may do what

If the required role is missing, the API answers with 403 role_too_low. The field required names the role needed, field the field concerned, for example settings.url or min_role. Team and roles explains how roles are assigned.

Changing and deleting

• Type and key are fixed once the tool is created. Everything else can be changed. The change applies to every execution afterwards, including proposals still waiting for confirmation; calls already carried out stay as they are. Only the Active box does not stop an open proposal, see Active and turned off.
• If the type of an existing tool no longer exists, the form shows “This tool type no longer exists. The tool can therefore no longer be changed, only deleted.” below Type, and Save is disabled. The app shows the same sentence if the service refuses to save with shape_unknown.
• Every change writes an entry to the audit log: tool.created, tool.updated or tool.deleted, with the list of changed fields for updates. If the entry cannot be written, the service saves nothing and the app reports “Not saved: the entry in the audit log could not be written. Please try again.” You find the audit log under Team and roles.
• Deleting removes the tool; cases already triggered are kept. Afterwards “The tool has been deleted.” appears. If a visitor later confirms an open proposal of this tool, it ends with a note that the tool has since been removed.
• If the tool or its assistant has been deleted in the meantime, for example in another window, the app reports “This entry no longer exists. Reload the page to see the current state.” when saving or deleting.
• Creating and changing are limited to 30 operations per minute per signed-in person; the counter is shared with other changes to assistants. Beyond that the app reports “Too many attempts. Please wait a moment.”

The tool card in the conversation

When the assistant calls a tool, the service first checks whether it belongs to this assistant, whether the minimum role is met, whether the type is part of the plan and whether all required fields are present. If one of these checks fails, the call ends as failed with a preview naming the tool, for example that it is not approved or not available. Previews appear in the language of the answer the card sits under: under an English answer in English, for example “Not approved: …”, including the types for connected systems, for example “Check order status for order …” for Read order status. If the answer is neither German nor English, the preview follows the conversation and then the assistant version; if that does not result in English, it is in German. Every call is recorded in the conversation before it is carried out and updated with its result or error afterwards. If the tool does not run straight away, a proposal is created: the visitor sees a card in the chat window and confirms or declines. Chat in the widget shows what this card looks like in the chat window.

• A proposal is valid for 60 minutes. As long as nobody decides, it stays proposed. Anyone who confirms or declines later gets it back as expired, and nothing is carried out.
• On confirmation the service checks again whether the tool still exists, whether minimum role and plan still fit and whether the required fields are present. Only then does it carry out the call.
• A double click does not trigger anything twice. If a proposal has already been decided, the response reports duplicate: true and returns the existing state. If the assistant proposes the same input twice in the same conversation and both are confirmed, the enquiry, appointment or basket handoff is created only once.
• Each answer of the assistant can include at most 5 tool calls. If it calls one tool per round, it stops after the fifth round without another card and writes a note into its answer; this note and the tighter cap for a throttled account are described in Chat in the widget. If it requests several tools in one round and so exceeds the 5 calls, any further call ends as failed: under an English answer the conversation shows “The assistant needed too many steps for this answer and was stopped.”, under a German answer the same note in German, and the card in the app shows under Error that the cap of 5 tool calls per answer has been reached.

States of a call

Deciding proposals in the app

You see tool calls under Conversations in the history of each conversation. The card shows Tool with the key, the state, the duration in milliseconds and the preview, plus Input, Result and, if something went wrong, Error with the message. For an open proposal in a conversation of the Test and API channels, you decide with the Edit role or higher: it reads “Waiting for confirmation.” with Confirm and Decline. In the Widget channel the visitor decides in the chat window; the card then shows “Waiting for the visitor to confirm in the chat window.” and no buttons.

Tools through the API

Tools can also be managed through the API. Authentication and limits are covered in API authentication and API limits.

The endpoints the visitor uses to confirm or decline in the chat window are described in Chat in the widget. Further conversation endpoints are in API: conversations and management.

Frequent questions