Using Pre-Engagement Form Data and Context (Webchat 2.0)

(warning)

Warning

Webchat 2.0 is no longer supported. It uses Flex UI 1.x.x's legacy messaging, which has reached end-of-life.

If you are using Webchat 2.0, migrate to Webchat 3.x.x.

If you are starting out with Webchat, build with Webchat 3.x.x instead.

When using chat as a communications channel for your contact center, you can configure 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.

Before you begin

To initiate a chat, 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.

Configuring a pre-engagement form

The pre-engagement form is disabled by default. To require details from your customers before they engage with your agents, enable the pre-engagement form by setting the startEngagementOnInit attribute to false in your Configuration object.

Enable Pre-Engagement Form

1const defaultConfiguration: Config = {
2    disableLocalStorage: false,
3    available: true,
4    colorTheme: {
5        baseName: "BlueMediumTheme"
6    },
7    componentProps: {
8        MessagingCanvas: {
9            avatarCallback: (identity: string) => SessionActions.getAgentAvatar(identity),
10            showTrayOnInactive: true
11        },
12        MessageCanvasTray: {
13            onButtonClick: () => Actions.invokeAction("RestartEngagement")
14        },
15        PreEngagementCanvas: {
16            // ...
17        }
18    },
19
20    tokenServerUrl: "https://iam.twilio.com/v1/Accounts/{accountSid}/Tokens",
21    flexWebChannelsUrl: "https://flex-api.twilio.com/v1/WebChannels",
22    context: {
23        friendlyName: "Anonymous"
24    },
25    startEngagementOnInit: false,
26    preEngagementConfig: {
27        // ...
28    }
29};

Enable Pre-Engagement Context

1
2// WebchatConfig.js
3
4const defaultConfiguration: Config = {
5    disableLocalStorage: false,
6    available: true,
7    colorTheme: {
8        baseName: "BlueMediumTheme"
9    },
10    componentProps: {
11        MessagingCanvas: {
12            avatarCallback: (identity: string) => SessionActions.getAgentAvatar(identity),
13            showTrayOnInactive: true
14        },
15        MessageCanvasTray: {
16            onButtonClick: () => Actions.invokeAction("RestartEngagement")
17        },
18        PreEngagementCanvas: {
19            // ...
20        }
21    },
22
23    tokenServerUrl: "https://iam.twilio.com/v1/Accounts/{accountSid}/Tokens",
24    flexWebChannelsUrl: "https://flex-api.twilio.com/v1/WebChannels",
25    context: {
26        friendlyName: "Anonymous"
27    },
28    startEngagementOnInit: false,
29    preEngagementConfig: {
30        // ...
31    }
32};

Within your Webchat configuration, you can define the preEngagementConfig object for the PreEngagementCanvas component.

The following example form shows a required input field for the username, an optional text area field for the user's question, and a submit button with the label "Ok Let's Go!"

Example Pre-Engagement Form

Webchat configuration with Pre-Engagement Form

1const defaultConfiguration: Config = {
2    // ...
3    preEngagementConfig: {
4
5        description: "Please provide some information",
6        fields: [
7            {
8                label: "What is your name?",
9                type: "InputItem",
10                attributes: {
11                    name: "friendlyName",
12                    type: "text",
13                    required: true
14                }
15            },
16            {
17                label: "What is your question?",
18                type: "TextareaItem",
19                attributes: {
20                    name: "question",
21                    type: "text",
22                    placeholder: "Type your question here",
23                    required: false,
24                    rows: 5
25                }
26            },
27        ],
28        submitLabel: "Ok Let's Go!"
29    }
30};

Supported field types and validations

Field Types

InputItem
SelectItem
TextareaItem

Field Validations

Field Attribute	Description
`required`	Validates whether a form field is required or optional. Can be set to `true` or `false`.
`email.value`	Checks the validity of the value attribute for an email input item.

The following example shows a preEngagementConfig object with all supported form field types and their properties and attributes.

Pre-Engagement Config Field Types

1preEngagementConfig: {
2
3    description: "Please provide some information",
4    fields: [
5        {
6            label: "What is your name?",
7            type: "InputItem",
8            attributes: {
9                name: "friendlyName",
10                type: "text",
11                placeholder: "Enter your name",
12                required: true,
13                value: "Bob",
14                readOnly: false
15            }
16        },
17        {
18            label: "What is your email?",
19            type: "InputItem",
20            attributes: {
21                name: "email",
22                type: "email",
23                placeholder: "Enter your email",
24                required: true,
25                value: "Bob@bobson.com",
26                readOnly: false
27            }
28        },
29        {
30            label: "My awesome dropdown",
31            type: "SelectItem",
32            attributes: {
33                name: "My awesome dropdown",
34                required: true,
35                readOnly: false
36
37            },
38            options: [
39            {
40                value: "value1",
41                label: "label1",
42                selected: false
43            },
44            {
45                value: "value2",
46                label: "label2",
47                selected: true
48            }
49            ]
50        },
51        {
52            label: "What is your question?",
53            type: "TextareaItem",
54            attributes: {
55                name: "question",
56                type: "text",
57                placeholder: "Type your question here",
58                required: false,
59                rows: 5,
60                value: "My awesome question",
61                readOnly: false
62            }
63        }
64    ],
65    footerLabel: "I am a footer",
66    submitLabel: "Ok Let's Go!",
67}

Posting user questions as a chat message

You can use WebChat actions to trigger your Flex Webchat Flow to automatically post user questions from a pre-engagement form to a chat window.

The following code sample shows how you can pass the question (if any) from the submitted formData and post it to chat using the StartEngagement post-action event.

1// post question from pre-engagement into chat
2
3  FlexWebChat.Actions.on("afterStartEngagement", (payload) => {
4              const { question } = payload.formData;
5              if (!question) return;
6
7              const { channelSid } = manager.store.getState().flex.session;
8              manager.chatClient.getChannelBySid(channelSid)
9                  .then(channel => {
10                      channel.sendMessage(question);
11                  });
12          });
13

When posting an initial message on behalf of the customer, consider changing the introductory message or turning off the predefinedMessage MessagingCanvas prop.

1
2FlexWebChat.MessagingCanvas.defaultProps.predefinedMessage = false;

To learn more about using React Default Props to configure your Webchat components, see Webchat Configuration: React default props API.

Gathering and sending context

The following code sample shows how you can set the context object in your Webchat configuration:

1const defaultConfiguration: Config = {
2    // ...
3    context: {
4        locationOrigin: window.location.origin,
5        someContextProp: "ContextProp1",
6    }
7}
8

If context is set, the context prop will be saved as a chat channel attribute and can be accessed by the Send to Flex Studio widget.

Accessing and using pre-engagement data and context

When enabled, pre-engagement form and context data are both automatically saved as Programmable Chat channel attributes (i.e., channel.attributes.pre_engagement_data ) when a chat is initiated.

Your form and context data can then be accessed in the WebChat Studio Flow. Check out the Twilio Studio documentation to learn more about how Studio uses variables.You can also save pre-engagement and context data as chat channel attributes:

1// context set in the WebChat
2
3    context: {
4        friendlyName: "Anonymous",
5        locationOrigin: "http://someOriginUrl.com",
6        someContextProp: "ContextProp1",
7    },
8
9// pre-engagement config set in WebChat
10
11preEngagementConfig: {
12
13    description: "Please provide some information",
14    fields: [
15        {
16            label: "What is your name?",
17            type: "InputItem",
18            attributes: {
19                name: "friendlyName",
20                type: "text",
21                required: true
22            }
23        },
24        {
25            label: "What is your question?",
26            type: "TextareaItem",
27            attributes: {
28                name: "question",
29                type: "text",
30                placeholder: "Type your question here",
31                required: false,
32                rows: 5
33            }
34        },
35    ],
36    submitLabel: "Ok Let's Go!"
37}
38
39// Chat channel attributes saved on chat initiation
40
41"attributes": "{\"status\":\"ACTIVE\",\"long_lived\":false,\"pre_engagement_data\":{\"friendlyName\":\"Anonymous\",\"question\":\"Can you help me with my invoice?\",\"location\":\"http://localhost:8081/\",\"locationOrigin\":\"http://someOriginUrl.com\",\"someContextProp\":\"ContextProp1\"},\"from\":\"Bob\",\"channel_type\":\"web\"}"
42

Pre-engagement and context data in Studio

An incoming message sent to the chat channel triggers the Webchat Flow for your Flex instance, which you can customize within the Twilio Console.

In the Webchat Studio 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:

1
2"{{trigger.message.ChannelAttributes.pre_engagement_data.question}}"

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

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

You may access your pre-engagement form and context data via the Programmable Chat REST API.