Form prefill

With the Prefill form type, the assistant copies details from the conversation into a form on your website. It asks for the values, shows the visitor a proposal in the chat window and writes into the mapped fields only once the visitor has confirmed it. This page covers the settings, the messages and the report you see in the app afterwards.

How a call works

1. 1

   Step 1

   Set up the tool

   You define which form is meant and which fields the assistant may ask for. When you save, the service checks the selector, the page and the mapping.

2. 2

   Step 2

   The assistant asks

   If the description under When should the assistant use it? matches the conversation, the assistant asks for the values. If a required value is missing, no proposal is created and it asks again.

3. 3

   Step 3

   Proposal in the chat window

   The visitor sees every value that is to be entered and whether the form will be submitted afterwards. They choose Confirm or Reject.

4. 4

   Step 4

   Filling in on your page

   After confirmation, the loader enters the values into the form. If the form is on another page of the same origin, that is with the same protocol, host and port, it opens that page first.

5. 5

   Step 5

   Report

   The loader reports which fields were filled in, which were not and whether the form was submitted. The visitor reads a short sentence about it; you see the details in the app.

Where to set up the tool

Open Triggers › Tools (app.xicbot.de/werkzeuge) and pick, under Assistant at the top, the assistant whose chat window should fill the form. The Assistant tools card lists its tools by key. In the Add tool area, change Type from the preset Capture enquiry to Prefill form in the Built in group. Only then do the Form on your website area and the field mapping appear.

Each row of the list shows the label, key and description, followed by “Prefill form · writing · with confirmation” and the Minimum role. If the tool is not active, “· inactive” is appended. Edit opens it in the form; users with read-only access see View there instead. Delete first asks “Delete this tool? Cases already triggered are kept.” and then reports “The tool has been deleted.”

Settings

General fields

The Minimum role decides who may trigger the tool. The chat window on your website counts as a visitor, even if someone is signed in to the app in the same browser. A form tool for the chat window therefore needs Visitor (public chat). You can choose levels up to your own role, plus the value an existing tool already has. Below the locked Approval selection, this type shows the sentence “Tools of this type change something and therefore always run with confirmation.”

Form on your website

The area opens with the note “The assistant enters the values only after the visitor has confirmed the proposal. Password, hidden and file fields stay empty.”

The host of an address under Form page (optional) must match exactly one of the assistant’s allowed domains; case does not matter, and a subdomain does not count. If no domains are set, only a path is possible. The check runs when you save, against the domains set at that moment. Where to maintain the domains is described under Allowed domains. Leave the field empty if the form is on the page with the chat window.

Input fields

“Each row links a field of your form (name attribute) to a value the assistant asks for in the conversation. It does not fill any other field.” As long as there is no row, it reads “No mapping yet.” Add field adds a row with the field type Text and without Required; after the 20th row the button is disabled, and “At most 20 mappings.” appears below it. Remove field takes a row out. A tool needs at least one row.

The Required fields area of other types is missing here because the Required column takes over that role; the list still shows the required values after “Required fields:”. The service removes leading and trailing spaces from the selector, page, field names, values and labels when saving. If Allow submitting is on, the assistant also gets the yes-or-no value absenden, described in German as: only true if the visitor explicitly wants the form to be submitted after filling in; without it, the visitor submits the form themselves.

Field types

For each value the assistant sees the first 200 characters of the label; for Number, Selection and Date the German hint from the table is appended. The field type controls how the assistant supplies the value. Whether a field on your page can be written to depends on the kind of field in the form itself, see the section “What gets filled in”.

Messages when saving

If a form setting is not valid, the service saves nothing and responds with status 422 and a code under error. The app shows these messages for it:

Proposal and confirmation

The service offers the assistant only active tools whose Minimum role the person in the conversation reaches. When the assistant calls the tool, the service accepts only the values from the mapping and cuts texts to 2000 characters. From these it builds a preview following this pattern:

Prefill form “Contact” without submitting it. Entered: Name: Erika Muster; Email: erika@example.com; Callback requested: yes

Whether the form will be submitted is stated before the first value: if submitting is allowed and requested, it reads “and submit it”, otherwise “without submitting it”. Each value appears with its Label, a checkbox as “yes” or “no”; without values the sentence ends with “nothing”. The preview is in the language of the reply above it: in German it begins with “Formular”, says “vorausfüllen, ohne es abzuschicken” or “vorausfüllen und danach abschicken” and then “Eingetragen wird:”; a checkbox appears there as “ja” or “nein”, without values it says “nichts”. The reply follows the language of each individual visitor message; if the visitor switches language mid-conversation, the preview switches with it. If the service does not recognise the language of a message, the conversation language applies, which is set by the visitor’s first sentence whose language the service recognises; after that it stays fixed. If that is not set yet either, the assistant’s language applies. If the reply language is neither German nor English, the preview is in the conversation language or, if that is also neither German nor English or not set yet, in the assistant’s language. The label and field labels appear as you entered them. The card headings in the following table follow the same language; in German they read “Unbekanntes Werkzeug …”, “Nicht freigegeben: …”, “Unvollständige Angaben für …” and “Zu lange Angaben für …”. Empty values are not entered by the loader; existing content in the form then stays in place. Each value is trimmed of leading and trailing spaces and cut to 1000 characters.

In the chat window, only “The step could not be carried out.” appears instead of the error text, or “Der Schritt konnte nicht ausgeführt werden.” in the German chat window; you see the exact text in the app after Error.

States

In the chat window the card shows the preview as its heading, below it the state word and, on an error, the fixed sentence “The step could not be carried out.” While the proposal is open, Confirm and Reject appear below. After a click both are disabled. If the request fails or the service responds with an error, they are enabled again and “The step could not be completed.” appears below the conversation. If the service refuses a confirmation because consent has been withdrawn in the meantime, the buttons stay disabled, the chat window no longer accepts messages, and “Consent has been withdrawn. This step will no longer be carried out.” appears below the conversation.

On confirmation the service checks again: if the tool has been deleted in the meantime, the call fails with “Das Werkzeug wurde inzwischen entfernt.” (the tool has since been removed); if it has been switched off, with “Das Werkzeug ist inzwischen ausgeschaltet.” (the tool has since been switched off). Role and required values are checked against the current state. The selector, page and field names are only now read from the saved settings; only the values come from the proposal. If the settings are no longer valid, the call fails with “Die Formulareinstellungen dieses Werkzeugs sind unvollständig.” (the form settings of this tool are incomplete).

What happens on your page

When the chat window loads, the loader on your page receives the settings of the form tools: tool, selector, page, field names with field type and whether submitting is allowed, but no labels and no values. It receives at most ten active form tools that a visitor may call and whose settings are valid, in order of their keys. Tools with a Minimum role above visitor or with invalid settings are not passed on and do not take up any of the ten places. Changes to a tool reach an open page only after the next load. If the loader knows no settings with the same selector for an instruction, it enters nothing and reports the form as not found.

Which page gets filled in

• If Form page (optional) is empty, the loader looks for the form on the page where the chat window is open.
• If the setting points to the current page, it fills in there. Origin and path are compared without a trailing slash, plus the query if the setting contains one.
• If it points to another page of the same origin, the loader stores the instruction in sessionStorage for two minutes and opens that page. There it fills in once the chat window has loaded.
• If the page is on another origin, such as another subdomain, nothing is entered and the report reads “form not found”. The same applies if the browser does not allow sessionStorage.

The visitor’s values are not put into the address. The target page needs the chat window’s embed code, otherwise nothing reads the handover. The loader reads it once and removes it; if it is older than two minutes, it lapses. Details of the entry are under Form handover.

What gets filled in

The selector must point at a form element. Inside it, the loader looks up each mapped field by its name attribute, and only for values that are not empty. Each field ends up in exactly one of three groups:

For a selection list, the loader first looks for an option with exactly this value, then for one whose visible text matches regardless of case; disabled options do not count. A checkbox is ticked for “yes” and cleared otherwise, by a click as the visitor would do it. A single-line field gets line breaks as spaces, a multi-line field keeps them. After setting a value, the loader fires the input and change events so that validation and counters on your page run along.

Submitting

The loader submits the form only if all of these conditions are met:

• Allow submitting is set on the tool.
• The assistant has sent the absenden value, and the confirmed preview says “and submit it”, or “vorausfüllen und danach abschicken” in German.
• At least one field has been filled in and no value is in the “Could not be filled” or “Blocked” group.
• The browser supports requestSubmit().

requestSubmit() goes through the browser’s required-field check and your page’s submit scripts. The loader reports the form as submitted only if the submit event actually fired. Otherwise the visitor checks and submits the form.

Report to the chat window and the app

After filling in, the loader passes the result to the chat window. The chat window writes a sentence below the proposal card and sends the report to the service, even if the page is being left because the form was submitted. Only field names are transmitted, at most 20 per group, plus whether the form was found and whether it was submitted; no values are sent.

The number covers values from both groups. If the visitor reloads the page, the chat window restores the sentence from the stored report, with the same number.

In the app, the report appears on the tool call in the conversation history, for example “Reported by the website: 3 field(s) filled · not submitted” or “Reported by the website: form not found”. Below it follow the field names under Filled, Could not be filled and Blocked; the values of the call are listed under Input.

If the loader knows no settings with the same selector, for example because the tool was switched off when the page loaded, its selector was changed afterwards, or it is not among the ten form tools the loader receives, it enters nothing and reports the form as not found; below the card it then says “The form was not found on this page. Please fill it in yourself.” No report is produced if the visitor leaves the page beforehand. The card then shows only “Done”.

Via the API

Via the API the tool has the type form_fill. The form settings go under settings; the service replaces any schema you send with the one generated from the mapping and sets approval to confirm. The field rules are the same as in the app.

{
  "type": "form_fill",
  "key": "contact_form",
  "title": "Fill in contact form",
  "description": "When the visitor wants to send an enquiry and has given their name, email and request.",
  "min_role": "public",
  "is_active": true,
  "settings": {
    "selector": "#contact",
    "page": "/contact",
    "submit_allowed": false,
    "fields": [
      { "name": "name", "key": "name", "label": "Name", "type": "text", "required": true },
      { "name": "email", "key": "email", "label": "Email address", "type": "email", "required": true },
      { "name": "message", "key": "message", "label": "Request", "type": "textarea", "required": false }
    ]
  }
}

Roles

With the Read role, the form is headed “With the Read role this area is view-only. Changes need at least the Edit role.” The fields are then locked. Without Administration, the Minimum role selection is locked when editing and below it reads “The minimum role of an existing tool can be changed by the Administration or Owner role.” Anyone choosing a level above their own role gets “This minimum role is above your own role. You can choose levels up to your own role.”

Editing and deleting

• Type and Key are fixed once the tool has been created. For a different key, create a new tool.
• Every save checks all settings again, including the page against the domains allowed at that point. If it holds an address on a domain that is no longer allowed, you can save only after adjusting the page.
• Creating, changing and deleting are recorded in the log. If the entry cannot be written, nothing is saved and the app reports “Not saved: the entry in the audit log could not be written. Please try again.”
• After a successful save the app clears the form for the next tool and reports “Saved: …” with the label next to the button.
• Deleting removes the tool; cases already triggered are kept. An open proposal fails on confirmation with “Das Werkzeug wurde inzwischen entfernt.” (the tool has since been removed).
• A change via the API without is_active leaves the switch as it is; a switched-off tool stays switched off.

Practical tips

• Set the Minimum role to Visitor (public chat). With a higher level the loader does not receive the settings, and the service does not offer the tool in the chat window at all.
• Per assistant, the loader receives at most ten form tools, ordered by key. Tools with a higher minimum role or invalid settings do not count towards this. If more than ten tools qualify, the loader does not receive those with the later keys.
• Embed the chat window on the page with the form as well and add its domain as an allowed domain, see Embed the widget.
• Check the selector in the browser console on the form page with document.querySelector('#contact'): the result must be the form element itself, not a surrounding element.
• Map only fields the loader can write to, and choose the Selection field type for selection lists so that the assistant names the entry as it appears in the list.
• Describe briefly under When should the assistant use it? when the form is meant, and try the flow in the chat window on your own page: only there are values entered.

Frequent questions