Using pre-engagement form data and context (Webchat 3.x.x public beta)

(information)

Public Beta

Flex Webchat 3.x.x is currently available as a public beta product and the information contained in this document is subject to change. This means that some features are not yet implemented and others may be changed before the product is declared as generally available. Public beta products are not covered by a Twilio SLA.

(information)

Info

Not a HIPAA Eligible Service
Webchat 3.x.x is not a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA.

(information)

Info

This page applies to Webchat 3.x.x. If you are using Webchat 2.0, see the Webchat 2.0 version of this page instead.

When using chat as a communications channel for your contact center, you can use a pre-engagement form to gather relevant user information (such as name and email) before the start of a chat. Alternatively, you can gather relevant context from the data you already have, such as a user's login name or HTTP referer. You can use pre-engagement form data and context for routing the task to the right agent or displaying relevant user information to the agent.

The default pre-engagement form collects the user's name, email address, and query, which are considered to be personally identifiable information (PII). You can configure the pre-engagement form to collect additional information.

Before you begin

To initiate a chat with a pre-engagement form, a user's friendlyName must be set. The friendlyName attribute is set to "Anonymous" in the context object of your default Webchat configuration. The friendlyName value is displayed to the agent in the Flex UI. When set in both the Webchat context object and a pre-engagement form, the pre-engagement form value overrides the context object value.

Configure a pre-engagement form and context

This section explains how to customize your pre-engagement form to collect the most important data from your customers. The pre-engagement form is enabled by default. If you want to turn off the pre-engagement form, set disablePreEngagementForm: true in your Webchat configuration.

The following example form shows many types of input fields, including required and optional input fields, a required checkbox for customers to acknowledge terms and conditions, and a submit button with the label "Let's chat." While this example shows many types of fields that you might want to use, we recommend limiting your pre-engagement form to 3-5 fields to avoid overwhelming your customers. However, there is no limit on the number of fields that you can include.

Example pre-engagement form and context

1// WebChat Config    
2deploymentKey: "{your_key}", 
3    appStatus: "open",
4    theme: {
5        isLight: true
6    },
7    context: { 
8locationOrigin: window.location.origin,
9someContextProp: "ContextProp1",
10},
11    disablePreEngagementForm: false,
12    preEngagementConfig: {
13        title: "Pre-Chat Form",
14        description: "Complete this form to start the chat",
15        submitLabel: "Let's chat",
16        footerLabel: "Powered by Twilio",
17        fields: [
18{
19   label: "Name",
20   type: "InputItem",
21   attributes: {
22       name: "friendlyName",
23       type: "text",
24       placeholder: "Enter your name",
25       required: true,
26       pattern: "^[a-zA-Z]+(([',. -][a-zA-Z ])?[a-zA-Z]*)*$",
27       readOnly: false,
28       value: "Bob"
29   }
30},
31{
32   label: "Email address",
33   type: "InputItem",
34   attributes: {
35       name: "email",
36       type: "email",
37       placeholder: "Enter your email address",
38       required: true,
39       readOnly: false,
40       value: "bob@gmail.com",
41       pattern: "{Your_email_pattern}"
42   }
43},
44{
45   label: "Date of birth",
46   type: "InputItem",
47   attributes: {
48       name: "dob",
49       type: "date",
50       placeholder: "Enter your date of birth",
51       required: false,
52       readOnly: false,
53       pattern: "{Your_date_of_birth_pattern}"
54   }
55},
56{
57   label: "Phone number",
58   type: "InputItem",
59   attributes: {
60       name: "phone",
61       type: "tel",
62       placeholder: "Enter your phone number",
63       required: false,
64       readOnly: false,
65       value: "0123456789",
66       pattern: "{Your_phone_number_pattern}"
67   }
68},
69{
70   label: "Ask a question",
71   type: "TextareaItem",
72   attributes: {
73       name: "question",
74       type: "text",
75       placeholder: "Type your question here",
76       required: true
77   }
78},
79{
80   label: "Question category",
81   type: "SelectItem",
82   attributes: {
83       name: "Question category dropdown",
84       required: false,
85       readOnly: false
86   },
87   options: [
88       {
89           value: "value1",
90           label: "label1",
91           selected: false
92       },
93       {
94           value: "value2",
95           label: "label2",
96           selected: true
97       }
98   ]
99},
100{
101   label: "Agree to our terms and conditions",
102   type: "CheckboxItem",
103   attributes: {
104       name: "termsCheckbox",
105       required: true,
106       refLink:
107           "<span>Review our  <a href='{Your_link_here}' target='_blank'>terms and conditions</a></span>"
108   }
109}
110        ]
111    }

Pre-engagement form as it appears to your customers.

Form attributes

The following attributes are available for your pre-engagement form:

Form attribute	Description
`title`	Name or greeting that appears as the heading at the top of the form.
`description`	Introductory text for the form.
`submitLabel`	Label that appears on the button to submit the form.
`footerLabel`	Optional text that appears at the bottom of your form.

Field attributes

Field setting	Description	Applies to these field types
`label`	Name of the field.	All field types
`type`	The following field types are supported: `InputItem` `SelectItem` `TextareaItem` `CheckboxItem` If you enter any other field type, it won't be displayed.	All field types
`options`	Add an array with `value`, `label`, and `selected` elements for each option that users can select. To set a default value, set `selected: true` for that option.	`SelectItem`

Input attributes and validations

For the input area of each field, you can set the following attributes and validations:

Input attribute	Description	Applies to these field types
`name`	Name of the input.	All field types
`type`	Format of the input that the user can enter and method of entry: `text`: A single-line text input. `email`: Looks like a text input field, but has validation parameters and relevant keyboard in browsers and devices with dynamic keyboards. `number`: Accepts numbers only. Users can change the value by entering a number, using keyboard arrow keys and increment buttons. `tel`: An input for entering a telephone number. It displays a telephone keypad in some devices with dynamic keypads. `date`: An input for entering a date. `time`: An input for entering a time. `password`: An input whose value is obscured. This input alerts a user if the site isn't secure.	`InputItem`, `TextareaItem`
`placeholder`	Example text that appears in the field and disappears when the user begins typing.	`InputItem`, `TextareaItem`
`required`	Validates whether a form field is required or optional. Can be set to `true` or `false`.	All field types
`pattern`	Checks the validity of the input item against the pattern you specify. Enter the expected pattern as a regular expression (regex).	`InputItem`
`readOnly`	Determines whether the field can be edited. Set to `false` in most cases. When set to `true`, the field can't be edited but can receive focus to allow users to highlight the text in the field. You may want to set a default value with the value attribute.	All field types
`disabled`	Similar to `readOnly`, except that this attribute can be dependent on the value entered in another input field. For example, if your form asks whether the chat is about an existing order, you could enable an order number field only if the customer has answered yes.	All field types
`value`	Default field value. This is typically used with `readOnly` fields.	All field types
`refLink`	Descriptive text that optionally includes HTML formatting, such as links. A common use case is to include a checkbox to acknowledge terms and conditions, with a link to your terms and conditions webpage.	`CheckboxItem`

Gathering and sending context

You can use context data to pass additional information, beyond pre-engagement form details, to the Flex platform when a webchat is initiated. This information enables you to provide a more personalized and informed interaction between your customers and your agents.

To get started, configure the context object in your Webchat configuration. For an example, see the context section in the example pre-engagement form and context section above.

Accessing and using pre-engagement data and context

When enabled, pre-engagement form and context data are both automatically saved as Conversations attributes (for example, conversation.attributes.pre_engagement_data) when a chat is initiated. Your form and context data can then be accessed in the Studio chat flow. See the Studio documentation to learn more about how Studio uses variables.

Pre-engagement and context data in Studio

An incoming chat conversation triggers the Webchat flow for your Flex instance, which you can customize within Twilio Console.

In the Studio chat flow, you can:

Trigger a bot conversation based on gathered pre-engagement data
Use pre-engagement data for decisions in the flow, like when to send the conversation to an agent
Add pre-engagement data to task attributes for routing decision or information display to an agent in Flex

Studio uses Liquid syntax to access the pre-engagement data in a Studio widget. For example, here's how you would access the question attribute from your pre-engagement form data:

Send to Flex widget with user question in chat attributes.

"{{trigger.conversation.ChannelAttributes.pre_engagement_data.question}}"

Here's how you would add the initial user question to your chat task attributes in the Send To Flex widget:

{"initial_question": "{{trigger.conversation.ChannelAttributes.pre_engagement_data.question}}"}

Next Steps

Check out the Twilio Studio User Guide