Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

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


(information)

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(link takes you to an external page). 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

before-you-begin page anchor

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

configuring-a-pre-engagement-form page anchor

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

enable-pre-engagement-form page anchor

_29
const 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
};

Enable Pre-Engagement Context

enable-pre-engagement-context page anchor

_32
_32
// WebchatConfig.js
_32
_32
const 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(link takes you to an external page).

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

example-pre-engagement-form page anchor
PreEngagementCanvas.

Webchat configuration with Pre-Engagement Form

webchat-configuration-with-pre-engagement-form page anchor

_30
const 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
};

Supported field types and validations

supported-field-types-and-validations page anchor
  • InputItem
  • SelectItem
  • TextareaItem
Field AttributeDescription
requiredValidates whether a form field is required or optional. Can be set to true or false.
email.valueChecks 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

pre-engagement-config-field-types page anchor

_67
preEngagementConfig: {
_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
}

Posting user questions as a chat message

posting-user-questions-as-a-chat-message page anchor

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(link takes you to an external page).


_10
_10
FlexWebChat.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

gathering-and-sending-context page anchor

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


_10
const 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.


Accessing and using pre-engagement data and context

accessing-and-using-pre-engagement-data-and-context page anchor

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(link takes you to an external page). 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
_41
preEngagementConfig: {
_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\"}"

Pre-engagement and context data in Studio

pre-engagement-and-context-data-in-studio page anchor

An incoming message sent to the chat channel triggers the Webchat Flow for your Flex instance, which you can customize within the Twilio Console(link takes you to an external page).

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:

Send to Flex widget initial question.

_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.



Rate this page: