Prechat Form JSON specs

Introduction

The Prechat Form is used to collect some end-user data before starting a conversation. Generally this info are asked to guest users, because authenticated users already provide 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 through 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 they must "logout" from the widget. This will also change their 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, go 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 fullname.

For the default prechat form, userEmail and userFullname 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 field types 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

Once you fill the custom prechat form, the operator can find the filled-in user data in the dedicated section of the conversation detail. For example, filling the custom form of Example 2 will populate the "Prechat form" section of the conversation detail:

Examples

The following examples show common tasks with the prechat form.

Example 1: ask the telephone number

Add the user's telephone number in addition to email and fullname. In the Tiledesk dashboard, choose a project, go to the widget section, enable the prechat form and activate the custom form editor.

Replace the provided JSON with the following:

prechat-form-example-1.json

[
  {
    "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"
    }
  }
]

Save the source (UPDATE WIDGET) and open the widget to start a conversation.

Note: If you don't see the prechat form, you probably already submitted it. 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.

Reserved fields names: While choosing the controls "name" attribute keep in mind reserved Tiledesk names: userEmail, userFullname and firstMessage.

Example 2: accepting Privacy and ToS

Add a static notice and a checkbox to require acceptance of Terms and Privacy before proceeding. Replace the JSON with:

prechat-form-example-2.json

[
  {
    "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"
  }
]

Save and test the widget. The form will block proceeding until the checkbox is checked.

Example 3: ask the first message

Request a first message from the user and send it as the conversation's initial message. Use the reserved name firstMessage for the control. Replace the JSON with:

prechat-form-example-3.json

[
  {
    "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"
    }
  }
]

Save and test. The widget will start a conversation and send the firstMessage as the conversation's initial message.

Control types

List and description of all control types supported by the Tiledesk prechat form.

Text

Default control: a simple text field. When type is omitted a Textfield control is rendered. You can provide a regex to validate the field.

Example:

text-example.json

[
  {
    "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

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

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

  • 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

  • Default is false. If true, filling some text is mandatory.

• value attribute

  • optional — the pre-defined value for the field.

• regex attribute

  • optional — field value will be validated with this regex.

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

• label attribute

  • optional — control's label. Multilanguage supported using ISO codes. If no supported language is found, the "default" label value will be used.

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

  • If label is not configured, the "name" attribute is used as the control's label. If label's value is a string (not an object), it will be used as a key for Tiledesk translations. Example: "label": "email"

• errorLabel attribute

  • optional — shown if regex doesn't match. If not set the standard message is displayed.

  • Example: { "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" for type. You can provide regex and rows to specify initial number of rows.

Example:

textarea-example.json

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

Textarea - Format specification

• name attribute

  • mandatory

  • Example: name: "description"

  Reserved names same as for Text (userEmail, userFullname, firstMessage).

• type attribute

  • optional, case insensitive — use "textarea".

• mandatory attribute

  • optional, boolean — default false.

• value attribute

  • optional — pre-defined value.

• regex attribute

  • optional — validation regex. Example: "regex" : "/^[a-zA-Z\s]*$/"

• label attribute

  • optional — multiline label support (default/en/it). Example: "label": "description"

• errorLabel attribute

  • optional — shown if regex doesn't match. Example: { "en": "Pattern not valid. Insert only 10-digits number", "it": "Campo non valido. Insersci solo un numero di dieci cifre" }

• rows attribute

  • optional — specifies initial number of rows. Example: { "name": "firstMessage", "type": "textarea", "rows": 5 }

Checkbox

Represents an HTML checkbox. Use "checkbox" for type. It can assume two values: 'checked' and 'unchecked'.

Example:

checkbox-example.json

[
  {
    "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 same as above.

• type attribute

  • optional, case insensitive — use "checkbox".

• mandatory attribute

  • optional, boolean — default false. For checkbox this means that checking the box is mandatory.

• value attribute

  • optional — pre-defined value.

• label attribute

  • optional — multilang supported; if a string, used as Tiledesk translation key.

Static

Static type is simple text. Use "static" for type. You can use plain text or HTML for complex text.

Example:

static-example.json

[
  {
    "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 — use "static".

• label attribute

  • optional — multilang supported; if not configured, the “name” attribute is used as the control's label. If label is a string it is used as a Tiledesk translation key. Example: "label": "terms"

---

Reserved names recap:

• userEmail — email used by Tiledesk to send automated messages.

• userFullname — used to identify the user by fullname in Tiledesk.

• firstMessage — used as the first message sent by the Widget when the conversation starts.

For more details see:

• Widget protocol specs: https://developer.tiledesk.com/widget/advanced/widget-json-protocol

Last updated 2 years ago