Using Pre-Engagement Form Data and Context (Webchat 2.0)
Info
This guide is for Flex UI 1.x.x and channels that use Programmable Chat and Proxy. If you are using Flex UI 2.x.x or you are starting out, we recommend that you build with Webchat 3.0.
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.
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.
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.
_29const defaultConfiguration: Config = {_29 disableLocalStorage: false,_29 available: true,_29 colorTheme: {_29 baseName: "BlueMediumTheme"_29 },_29 componentProps: {_29 MessagingCanvas: {_29 avatarCallback: (identity: string) => SessionActions.getAgentAvatar(identity),_29 showTrayOnInactive: true_29 },_29 MessageCanvasTray: {_29 onButtonClick: () => Actions.invokeAction("RestartEngagement")_29 },_29 PreEngagementCanvas: {_29 // ..._29 }_29 },_29_29 tokenServerUrl: "https://iam.twilio.com/v1/Accounts/{accountSid}/Tokens",_29 flexWebChannelsUrl: "https://flex-api.twilio.com/v1/WebChannels",_29 context: {_29 friendlyName: "Anonymous"_29 },_29 startEngagementOnInit: false,_29 preEngagementConfig: {_29 // ..._29 }_29};
_32_32// WebchatConfig.js_32_32const defaultConfiguration: Config = {_32 disableLocalStorage: false,_32 available: true,_32 colorTheme: {_32 baseName: "BlueMediumTheme"_32 },_32 componentProps: {_32 MessagingCanvas: {_32 avatarCallback: (identity: string) => SessionActions.getAgentAvatar(identity),_32 showTrayOnInactive: true_32 },_32 MessageCanvasTray: {_32 onButtonClick: () => Actions.invokeAction("RestartEngagement")_32 },_32 PreEngagementCanvas: {_32 // ..._32 }_32 },_32_32 tokenServerUrl: "https://iam.twilio.com/v1/Accounts/{accountSid}/Tokens",_32 flexWebChannelsUrl: "https://flex-api.twilio.com/v1/WebChannels",_32 context: {_32 friendlyName: "Anonymous"_32 },_32 startEngagementOnInit: false,_32 preEngagementConfig: {_32 // ..._32 }_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!"
_30const defaultConfiguration: Config = {_30 // ..._30 preEngagementConfig: {_30_30 description: "Please provide some information",_30 fields: [_30 {_30 label: "What is your name?",_30 type: "InputItem",_30 attributes: {_30 name: "friendlyName",_30 type: "text",_30 required: true_30 }_30 },_30 {_30 label: "What is your question?",_30 type: "TextareaItem",_30 attributes: {_30 name: "question",_30 type: "text",_30 placeholder: "Type your question here",_30 required: false,_30 rows: 5_30 }_30 }, _30 ],_30 submitLabel: "Ok Let's Go!"_30 }_30};
-
InputItem -
SelectItem -
TextareaItem
| 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.
_67preEngagementConfig: {_67_67 description: "Please provide some information",_67 fields: [_67 {_67 label: "What is your name?",_67 type: "InputItem",_67 attributes: {_67 name: "friendlyName",_67 type: "text",_67 placeholder: "Enter your name",_67 required: true,_67 value: "Bob",_67 readOnly: false_67 }_67 },_67 {_67 label: "What is your email?",_67 type: "InputItem",_67 attributes: {_67 name: "email",_67 type: "email",_67 placeholder: "Enter your email",_67 required: true,_67 value: "Bob@bobson.com",_67 readOnly: false_67 }_67 },_67 {_67 label: "My awesome dropdown",_67 type: "SelectItem",_67 attributes: {_67 name: "My awesome dropdown",_67 required: true,_67 readOnly: false_67_67 },_67 options: [_67 {_67 value: "value1",_67 label: "label1",_67 selected: false_67 },_67 {_67 value: "value2",_67 label: "label2",_67 selected: true_67 }_67 ]_67 },_67 {_67 label: "What is your question?",_67 type: "TextareaItem",_67 attributes: {_67 name: "question",_67 type: "text",_67 placeholder: "Type your question here",_67 required: false,_67 rows: 5,_67 value: "My awesome question",_67 readOnly: false_67 }_67 }_67 ],_67 footerLabel: "I am a footer",_67 submitLabel: "Ok Let's Go!",_67}
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.
_12// post question from pre-engagement into chat_12_12 FlexWebChat.Actions.on("afterStartEngagement", (payload) => {_12 const { question } = payload.formData;_12 if (!question) return;_12_12 const { channelSid } = manager.store.getState().flex.session;_12 manager.chatClient.getChannelBySid(channelSid)_12 .then(channel => {_12 channel.sendMessage(question);_12 });_12 });
When posting an initial message on behalf of the customer, consider changing the introductory message or turning off the predefinedMessage MessagingCanvas prop.
_10_10FlexWebChat.MessagingCanvas.defaultProps.predefinedMessage = false;
To learn more about using React Default Props to configure your Webchat components, see Webchat Configuration: React default props API.
The following code sample shows how you can set the context object in your Webchat configuration:
_10const defaultConfiguration: Config = {_10 // ..._10 context: {_10 locationOrigin: window.location.origin,_10 someContextProp: "ContextProp1",_10 }_10}
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.
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:
_41// context set in the WebChat_41_41 context: {_41 friendlyName: "Anonymous",_41 locationOrigin: "http://someOriginUrl.com",_41 someContextProp: "ContextProp1",_41 },_41_41// pre-engagement config set in WebChat_41_41preEngagementConfig: {_41_41 description: "Please provide some information",_41 fields: [_41 {_41 label: "What is your name?",_41 type: "InputItem",_41 attributes: {_41 name: "friendlyName",_41 type: "text",_41 required: true_41 }_41 },_41 {_41 label: "What is your question?",_41 type: "TextareaItem",_41 attributes: {_41 name: "question",_41 type: "text",_41 placeholder: "Type your question here",_41 required: false,_41 rows: 5_41 }_41 }, _41 ],_41 submitLabel: "Ok Let's Go!"_41}_41_41// Chat channel attributes saved on chat initiation_41_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\"}"
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:
_10_10"{{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:
_10{"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.