Tiledesk Developer Hub
WebsiteCommunityTutorialsGet started
  • Introduction
  • Community
  • Ask for Support
  • Public Roadmap and Changelog
  • Tutorials
  • Widget
    • Widget SDK
    • Javascript API: Methods
    • Javascript API: Attributes
    • Javascript API: Listeners/Events
    • Widget Authentication
    • Widget Angular integration
    • Widget React integration
    • Widget for Android with WebView
    • Widget for iOS with WKWebView
    • Widget for Flutter with WebView
    • Widget for React with WebView
    • Widget for Wix Website platform
    • Tutorials
      • Hide widget
      • Show/Hide widget programmatically
      • Force widget loading without user interaction
      • Mobile positioning
      • Custom size (width/height)
      • Installing widget on selected pages
    • Conversation Embedded Apps
      • Payment App Tutorial
      • Prechat form App Tutorial
    • Advanced
      • Preset the Widget on a specific Department
      • Authentication Flow
      • Widget protocol specs
      • Prechat Form JSON specs
      • Prevent multiple conversations
      • Old versions
        • Web SDK v4
  • External Chatbot
    • Introduction
    • Hello World tutorial
    • Chatbot to Human handoff
    • Send Text Buttons
    • Advanced Tutorials
      • Introduction
      • Tutorial 1 - Dialogflow as external chatbot
      • Tutorial 2 - Buttons and images
      • Tutorial 3 - Automatic human handoff with fallback intent
      • Tutorial 4 - Explicit Human handoff with user intent
      • Tutorial 5 - Gracefully handling operating hours during handoff
      • Generate Dialogflow Google Credentials file
    • Rasa tutorials
      • Rasa Tutorial 1 - Rasa as external chatbot
  • Resolution bot
    • Introduction
    • Quickstart
    • Webhook service
    • Rich messages
    • Tutorials
      • Chatbot chooser (multilanguage)
      • Department chooser
      • Order info (webhook)
  • APIs
    • REST APIs
      • Introduction
      • Authentication
      • Requests
      • Leads
      • Messages
      • Activities
      • Projects
      • Team
      • User
      • Analytics
      • Canned responses
      • Tags
      • Events
      • Jwt
      • Labels
      • Images
      • Files
      • Segments
      • Chatbots
      • Knowledge Bases
        • Knowledge Base
        • Contents
        • Question & Answer
      • Management Api
        • Departments
        • Groups
    • NodeJS SDK
    • Webhooks
      • Subscriptions
    • Conversation Messages APIs tips
    • Realtime API
    • JWT Authentication
      • JWT Custom authentication Tutorial
    • Tutorials
      • REST API
        • Sending and receiving messages with Tiledesk APIs
        • PHP Tiledesk REST API example
        • Import multiple messages into Tiledesk using REST APIs from third party app
      • Webhooks
        • Custom Request assignment
        • Request transcript on close
  • Apps
    • Build Custom App - Quick start
    • External Channels integration flow diagram
    • Telegram integration tutorial
  • Dashboard & AgentChat SDK
    • Dashboard SDK
    • Agent Chat SDK
  • Architecture
    • Architecture overview
    • Components list
    • Bot Design diagram
    • Multi Channel Message Flow
  • Installation
    • Installation
    • Running Tiledesk using Docker Compose
    • Running Tiledesk with Kubernetes using Helm
    • Choosing Hardware
  • Configuration
    • Chat21 channel configuration
    • Email parameters and templates configuration
    • Configure the logging system
Powered by GitBook
On this page
  • Prechat Form JSON specs
  • Table of contents
  • Introduction
  • Default Prechat Form
  • Custom Prechat Form
  • Examples
  • Control types
  • Text
  • Text - Format specification
  • Textarea
  • Textarea - Format specification
  • Checkbox
  • Checkbox - Format specification
  • Static
  • Static - Format specification

Was this helpful?

  1. Widget
  2. Advanced

Prechat Form JSON specs

PreviousWidget protocol specsNextPrevent multiple conversations

Last updated 1 year ago

Was this helpful?

Prechat Form JSON specs

image

Table of contents

Introduction

The Prechat Form is used to collect some end-user data before starting a conversation. Generally this info are asked to guests users, because of authenticated users already providing some "certified" information into a custom JWT. The info collected by the Prechat Form will be used either by Agents, by the Tiledesk platform itself or by developers trough APIs.

The prechat form is asked just once to the user, on the first conversation. Once filled and submitted the form data is saved in the browser Local Storage database. If the user wants to fill the prechat form again after the first submission he must "logout" from the widget. This will also change his anonymous user ID.

To logout and reset the widget status, press the option menu (gear icon) in the bottom left corner of the widget home screen and click "logout".

Default Prechat Form

To activate the prechat form, got to the Tiledesk Dashboard, then Settings > Widget > Prechat form (section). Open this section and activate the form through the provided switch:

If you activate the Prechat Form and no custom format is specified, the default form is shown before starting any conversation. The default form asks the basic info necessary to interact with a Guest user: email and a fullname.

For the default prechat form, useremail and fullname are required fields.

Custom Prechat Form

The prechat form provides customization, so if email is not enough you can ask a telephone number or you can make the user agree to your terms and conditions before proceeding with a conversation. Custom forms use a special (and easy) JSON syntax to customize the form fields. You can specify the fields type choosing the right "control type" (i.e. text/textarea, checkbox, static text etc.). You can also provide some options, useful to validate the field, show a custom validation error or make the field mandatory or not. Multilanguage for labels is also supported.

Inspect filled-in user data

The operator can see the filled-in form data looking at the "Prechat form section" of the conversation detail, as in the following picture:

Examples

To understand how prechat form works we can start with some examples.

These examples will show how to accomplish some common tasks with the prechat form. We will start asking the user's telephone number. In the second example we'll propose to read & accept a Privacy Policy and finally, in the third example, a form will ask the user to fill the first question in order to proceed to a new conversation.

Example 1: ask the telephone number

In this first example we'll show you how to ask the user telephone number in addition to email and fullname. To customize the prechat form, first sign in the Tiledesk dashboard using your credentials, then choose a project (if you have more then one). Move to the widget section, scroll down to the prechat form section and enable the prechat form using the switch.

Now activate the custom form editor using the switch, as in the following figure:

You will see the JSON source for an already provided example.

Please replace the provided JSON with the following code:

[
    {
        "name": "userFullname",
        "type": "text",
        "mandatory": true,
        "label": {
            "en": "Your name",
            "it": "Il tuo nome"
        }
    },
    {
        "name": "userEmail",
        "type": "text",
        "mandatory": true,
        "regex": "/^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+(.[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/",
        "label": {
            "en": "Your email",
            "it": "La tua email"
        },
        "errorLabel": {
            "en": "Invalid email address",
            "it": "Indirizzo email non valido"
        }
    },
    {
        "name": "tel",
        "mandatory": true,
        "label": {
            "en": "Your phone number",
            "it": "Il tuo numero di telefono"
        }
    }
]

Now save the pasted source pressing the UPDATE WIDGET button.

On the top bar, press the green button to open the widget. Now Start a conversation.

NOTE: If you don't see the prechat form after starting a conversation, don't panic. You probably already submitted the prechat form. Open the option menu (gear icon) in the bottom left corner of the widget home screen and select "logout". On the next conversation start the form will appear again.

We just added a phone number text field to the basic form. As you can guess, the form JSON is an array of "controls". Each control has some attributes that allow to fine tuning the control itself. In this case the first two elements (controls) of the array are a "name" textfield and an "email" textfield. We just focus on the added one, the phone number. The phone number is mandatory (mandatory attributes set to true) and we set a couple of multilanguage labels, to show you how multi-language is supported using the languages iso codes (en, it) of the desired languages (English and Italian in this example, respectively).

Example 2: accepting Privacy and ToS

In this example we'll add an option for the user to proceed in the conversation only if "You accept our Terms and Conditions and Privacy Policy". We will add a couple of controls: 1. Static text to show the notice, 2. Checkbox to declare acceptance. We can modify the JSON for the Example 1, adding the new controls:

Please replace the provided JSON with the following code:

[
    {
        "name": "userFullname",
        "type": "text",
        "mandatory": true,
        "label": {
            "en": "Your name",
            "it": "Il tuo nome"
        }
    },
    {
        "name": "userEmail",
        "type": "text",
        "mandatory": true,
        "regex": "/^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+(.[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/",
        "label": {
            "en": "Your email",
            "it": "La tua email"
        },
        "errorLabel": {
            "en": "Invalid email address",
            "it": "Indirizzo email non valido"
        }
    },
    {
        "name": "tel",
        "mandatory": true,
        "label": {
            "en": "Your phone number",
            "it": "Il tuo numero di telefono"
        }
    },
    {
        "type": "static",
        "label": "Before proceeding in the conversation please agree to our <a href='https://tiledesk.com/termsofservice/' target='_blank'>Terms</a> and <a href='https://tiledesk.com/privacy.html' target='_blank'>Privacy Policy</a>"
    },
    {
        "type": "checkbox",
        "name": "acceptedTermsPrivacy",
        "label": {
            "en": "I agree",
            "it": "Accetto"
        },
        "mandatory": "true"
    }
]

Now save the pasted source pressing the UPDATE WIDGET button.

On the top bar, press the green button to open the widget. Now Start a conversation.

As you can see the new controls are shown on the footer. If you try to proceed without accepting, the form will block you.

Now check the option to accept the Terms of use and proceed with the conversation 😅

Example 3: ask the first message

In this example we'll add an option for the user to write the first message before starting a conversation. This option is extremely useful when you don't have a chatbot and you want your agents get in contact with a great first message from the end-user, that exactly describes the problem. Note that with this special field (that uses for the "name" property the reserved value "firstMessage") the widget instantly sends the message to Tiledesk. We will add a new textarea control with firstMessage as the value of the name property. This will tell Tiledesk to use this value as the first message of the conversation. We can modify the JSON for the Example 1, adding the new textarea control:

[
    {
        "name": "userFullname",
        "type": "text",
        "mandatory": true,
        "label": {
            "en": "Your name",
            "it": "Il tuo nome"
        }
    },
    {
        "name": "userEmail",
        "type": "text",
        "mandatory": true,
        "regex": "/^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+(.[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/",
        "label": {
            "en": "Your email",
            "it": "La tua email"
        },
        "errorLabel": {
            "en": "Invalid email address",
            "it": "Indirizzo email non valido"
        }
    },
    {
        "name": "firstMessage",
        "rows": 5,
        "type": "textarea",
        "mandatory": true,
        "label": {
            "default": "Your message for the support team"
        }
    }
]

Now save the pasted source pressing the UPDATE WIDGET button.

On the top bar, press the green button to open the widget. Now Start a conversation.

You can see the new control, "Your message for the support team", shown as the last one. It's a mandatory field, you must fill it or the form will block you.

As soon as you fill the form, the new conversation starts, with the first message appearing as the first one of the conversation. The agent (or the chatbot) will receive it and happily reply 😎

Control types

Here follows a list and a description for all the control types actually supported by the Tiledesk prechat form.

Text

This is the default control, it's a simple text field. When type is omitted a Textfield control is rendered. You can provide a regex to validate the field.

Example:

[
  {
    "name": "userFullname",
    "type": "text",
    "mandatory": true,
    "label": {
        "default": "Your name",
        "en": "Your name",
        "it": "Il tuo nome"
    },
    "regex": "/^[a-zA-Z\\s]*$/",
    "errorLabel": {
        "default": "Incorrect name, only letters and spaces are allowed",
        "en": "Incorrect name, only letters and spaces are allowed",
        "it": "Nome errato, sono permesse solo lettere e spazi"
    }
  }
]

Text - Format specification

name attribute

mandatory

Example:

name: “phone”

Reserved names

While choosing the controls "name" attribute, keep in mind that there are three reserved Tiledesk names:

  1. userEmail It's the email used by Tiledesk to send automated messages.

  2. userFullname When available it is used to identify the user by his fullname around Tiledesk.

  3. firstMessage When provided, this value is used as the first message sent by the Widget as soon as the conversation starts.

type attribute

optional, case insensitive

For Textfield use text value.

mandatory attribute

optional, boolean

This property denotes if is mandatory to have a value for this control.

“mandatory”: true | false

Default is false

If true filling some text is mandatory.

value attribute

optional

The pre-defined value for the field.

regex attribute

optional

If set, the field value will be validated with this regex.

Example:

"regex" : "/^[a-zA-Z\\s]*$/"

label attribute

optional

This is the control's label. Multilanguage is supported. Simply add the language's ISO code as in the following example to add languages. If no supported language is found, the "default" label value will be used.

"label": {
  "default": "Your name",
  "en": "Your name",
  "it": "Il tuo nome"
}

If label attribute is not configured, the “name” attribute is used as the control's label. If the label's property value is a string (not a JSON object with ISO language value) the translation is searched in Tiledesk translations using the label's string property as the key for the translation.

Ex. label as string "email" will use the Tiledesk translation key "email".

"label": "email"

errorLabel attribute

optional

If available the errorLabel will be displayed if the regex doesn't match. If not set the standard message is displayed.

errorLabel: {
  "en": "Pattern not valid. Insert only 10-digits number",
  "it": "Campo non valido. Insersci solo un numero di dieci cifre"
}

Textarea

Textarea is a multi-line text input. Use "textarea" value for "type" property to render a Textarea. You can provide a regex to validate the textarea input text. Use the optional property "rows" to render a specific number of initial rows.

Example:

[
  {
    "name": "firstMessage",
    "type": "textarea",
    "label": {
      "default": "Your message"
    },
    "mandatory": true,
    "rows": 5
  }
]

Textarea - Format specification

name attribute

mandatory

Example:

name: “description”

Reserved names

While choosing the controls "name" attribute, keep in mind that there are three reserved Tiledesk names:

  1. userEmail It's the email used by Tiledesk to send automated messages.

  2. userFullname When available it is used to identify the user by his fullname around Tiledesk.

  3. firstMessage When provided, this value is used as the first message sent by the Widget as soon as the conversation starts.

type attribute

optional, case insensitive

For Textarea use textarea value.

mandatory attribute

optional, boolean

This property denotes if is mandatory to have a value for this control.

“mandatory”: true | false

Default is false

If true filling some text is mandatory.

value attribute

optional

The pre-defined value for the field.

regex attribute

optional

If set, the field value will be validated with this regex.

Example:

"regex" : "/^[a-zA-Z\\s]*$/"

label attribute

optional

This is the control's label. Multilanguage is supported. Simply add the language's ISO code as in the following example to add languages. If no supported language is found, the "default" label value will be used.

"label": {
  "default": "Your name",
  "en": "Your name",
  "it": "Il tuo nome"
}

If label attribute is not configured, the “name” attribute is used as the control's label. If the label's property value is a string (not a JSON object with ISO language value) the translation is searched in Tiledesk translations using the label's string property as the key for the translation.

Ex. label as string "email" will use the Tiledesk translation key "email".

"label": "description"

errorLabel attribute

optional

If available the errorLabel will be displayed if the regex doesn't match. If not set the standard message is displayed.

errorLabel: {
  "en": "Pattern not valid. Insert only 10-digits number",
  "it": "Campo non valido. Insersci solo un numero di dieci cifre"
}

rows attribute

optional

'rows' property specifies the initial number of rows of the Textarea control.

{
    "name": "firstMessage",
    "type": "textarea",
    "rows": 5
}

Checkbox

Checkbox represents an HTML checkbox. Use "checkbox" value for "type" property to render a Checkbox. It can only assume two values, 'checked' and 'unchecked'. Use "checkbox" value for "type" property to render a Checkbox.

Example:

[
  {
    "name": "acceptPrivacy",
    "type": "checkbox",
    "label": {
      "default": "Accept our privacy policy before contacting support"
    },
    "mandatory": true
  }
]

Checkbox - Format specification

name attribute

mandatory

Example:

name: “accept”

Reserved names

While choosing the controls "name" attribute, keep in mind that there are three reserved Tiledesk names:

  1. userEmail It's the email used by Tiledesk to send automated messages.

  2. userFullname When available it is used to identify the user by his fullname around Tiledesk.

  3. firstMessage When provided, this value is used as the first message sent by the Widget as soon as the conversation starts.

type attribute

optional, case insensitive

For Checkbox use checkbox value.

mandatory attribute

optional, boolean

This property denotes if is mandatory to have a value for this control.

“mandatory”: true | false

Default is false

In the case of checkbox this means that checking the box is mandatory.

value attribute

optional

The pre-defined value for the field.

label attribute

optional

This is the control's label. Multilanguage is supported. Simply add the language's ISO code as in the following example to add languages. If no supported language is found, the "default" label value will be used.

"label": {
  "default": "Your name",
  "en": "Your name",
  "it": "Il tuo nome"
}

If label attribute is not configured, the “name” attribute is used as the control's label. If the label's property value is a string (not a JSON object with ISO language value) the translation is searched in Tiledesk translations using the label's string property as the key for the translation.

Ex. label as string "email" will use the Tiledesk translation key "email".

"label": "accept"

Static

Static type is simple text. Use "static" value for "type" property to render a Static block of text. You can use simple text or HTML to render more complex pieces of text.

Example:

[
  {
    "type": "static",
    "label": {
      "default": "Accept the <a href='https://site.com/terms/' target='_blank'>Terms</a> before contacting support",
      "en": "Accept the <a href='https://site.com/en/terms/' target='_blank'>Terms</a> before contacting support",
      "it": "Accetta i <a href='https://site.com/it/terms/' target='_blank'>Termini</a> prima di contattare il supporto"
    }
  }
]

Static - Format specification

type attribute

optional, case insensitive

For Static use static value.

label attribute

optional

This is the control's label. Multilanguage is supported. Simply add the language's ISO code as in the following example to add languages. If no supported language is found, the "default" label value will be used.

"label": {
  "default": "Your name",
  "en": "Your name",
  "it": "Il tuo nome"
}

If label attribute is not configured, the “name” attribute is used as the control's label. If the label's property value is a string (not a JSON object with ISO language value) the translation is searched in Tiledesk translations using the label's string property as the key for the translation.

Ex. label as string "email" will use the Tiledesk translation key "email".

"label": "terms"

image
image

Once you fill the custom prechat form, the operator can find the filled-in user data in the dedicated section of the conversation detail. Suppose the user fills the custom form of as in the following picture:

image
image
image
image
image

Reserved fields names: While choosing the controls "name" attribute, keep in mind that there are some reserved Tiledesk names: userEmail, userFullname and firstMessage. We discuss about those fields

image
image
image
image
image
image
image
image
Introduction
Default prechat form
Custom Prechat Form
Inspect filled-in user data
Examples
Example 1: ask the telephone number
Example 2: accepting Privacy and ToS
Example 3: ask the first message
Control types
Text
Textarea
Checkbox
Static
Format specification
name attribute
Reserved-names
type attribute
mandatory attribute
value attribute
regex attribute
label attribute
errorLabel attribute
rows attribute
Example 2
here