Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Pre-engagement and context

What can you do with pre-engagment form and context?

Pre-engagement form is a set of configurable form that you can use to gather information from a user, like their name or email, before starting the chat.

Instead of asking the user you can also gather the relevant context from the data you already have, like user name for logged in user or page url they have come from.

Pre-engagement form data and context can be used for routing the task to the right agent or giving the agent relevant information about the user.

How to gather and send context?

Below example shows how you can set context

    context: {
        locationOrigin: window.location.origin,
        someContextProp: "ContextProp1",
    },

If context is set, it will be saved in chat channel attributes and can be accessed by "Send to Flex" Studio widget.

How to configure pre-engagement form?

By default, the pre-engagement form is turned of and the user can start a conversation straight away, but if you want to ask user to provide some details before engaging with you agents, you can configure the form that a user has to fill out before starting the chat

How to turn on pre-engagement form?

To turn on the pre-engagement form and start the chat on entry point click:

1) add this to configuration:

startEngagementOnInit: false

2) set pre-engagement config. Below is an example of a pre-engagement config

Flex pre-engagement form example

preEngagementConfig: {    

    description: "Please provide some information",
    fields: [
        {
            label: "What is your name?",
            type: "InputItem",
            attributes: {
                name: "friendlyName",
                type: "text",
                required: true
            }
        },
        {
            label: "What is your question?",
            type: "TextareaItem",
            attributes: {
                name: "question",
                type: "text",
                placeholder: "Type your question here",
                required: false,
                rows: 5
            }
        }, 
    ],
    submitLabel: "Ok Let's Go!"
}

How to post users question as a chat message?

If you would like a user to specify a question in the pre-engagement form, you can then post it automatically into the chat on behalf of the user. This will trigger the Studio flow.

Below is an example of how to get question from submitted formData and post it into chat channel using WebChat actions

    // POST QUESTION FROM PREENGAGEMENT FORM INTO CHAT
          FlexWebChat.Actions.on("afterStartEngagement", (payload) => {
              const { question } = payload.formData;
              if (!question) return;

              const { channelSid } = manager.store.getState().flex.session;
              manager.chatClient.getChannelBySid(channelSid)
                  .then(channel => {
                      channel.sendMessage(question);
                  });
          });

If posting an initial message on behalf of the customer, you might want to change or remove the PredefinedMessage as a call to action.

FlexWebChat.MessagingCanvas.defaultProps.predefinedMessage = false;

Supported form fields and their attributes

The following form fields are supported:

  • InputItem
  • SelectItem
  • TextareaItem

The following form validations are supported:

  • Required field
  • Email field format

Below is a pre-engagement config with an example of all form field types and their components

preEngagementConfig: {    

    description: "Please provide some information",
    fields: [
        {
            label: "What is your name?",
            type: "InputItem",
            attributes: {
                name: "friendlyName",
                type: "text",
                placeholder: "Enter your name",
                required: true,
                value: "Bob",
                readOnly: false
            }
        },
        {
            label: "What is your email?",
            type: "InputItem",
            attributes: {
                name: "email",
                type: "email",
                placeholder: "Enter yout email",
                required: true,
                value: "Bob@bobson.com",
                readOnly: false
            }
        },
        {
            label: "My awesome dropdown",
            type: "SelectItem",
            attributes: {
                name: "My awesome dropdown",
                required: true,
                readOnly: false
   
            },
            options: [
            {
                value: "value1",
                label: "label1",
                selected: false
            },
            {
                value: "value2",
                label: "label2",
                selected: true
            }
            ]
        },
        {
            label: "What is your question?",
            type: "TextareaItem",
            attributes: {
                name: "question",
                type: "text",
                placeholder: "Type your question here",
                required: false,
                rows: 5,
                value: "My awesome question",
                readOnly: false
            }
        }
    ],
    footerLabel: "I am a footer",
    submitLabel: "Ok Let's Go!",
}

How to access and use pre-engagment data and context?

Pre-engagement form data and context data are both saved to Programmable Chat channel attributes automatically when chat is initiated.

Both pre-engagement and context data are saved under channel.attributes.pre_engagement_data

This data then can be accessed in the WebChat Studio Flow. You can find more information on how Studio Flow works for WebChat, here.

Below is an example of how the pre-engagement and context data are saved to chat channel

// context set in the WebChat

    context: {
        friendlyName: "Anonymous",
        locationOrigin: "http://someOriginUrl.com",
        someContextProp: "ContextProp1",
    },

// pre-engagement config set in WebChat

preEngagementConfig: {    

    description: "Please provide some information",
    fields: [
        {
            label: "What is your name?",
            type: "InputItem",
            attributes: {
                name: "friendlyName",
                type: "text",
                required: true
            }
        },
        {
            label: "What is your question?",
            type: "TextareaItem",
            attributes: {
                name: "question",
                type: "text",
                placeholder: "Type your question here",
                required: false,
                rows: 5
            }
        }, 
    ],
    submitLabel: "Ok Let's Go!"
}

// Chat channel attributes saved on chat initiation

"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\"}"

Accessing pre-engagement and context data in Studio

When an incoming message is sent to the chat channel, this triggers a Studio Flow. By default, this is the 'Webchat Flow', 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-engagment data to task attributes to be used for routing decision or be later displayed to an agent in Flex

All the pre-engagement data can be accessed by Studio widgets using Liquid syntax.. Here is an example of accessing the question attribute

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

For example in the 'Send to Flex' widget you could add the initial user question to task attributes:

Send to Flex widget initial question

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

Setting user friendlyName

To initiate a chat, setting user's friendlyName is mandatory. By default, friendlyName is set to Anonymous in the default configuration via context object. FriendlyName is automatically added to task attributes by "Send to Flex" widget as task.attributes.name and is displayed in Flex for the agent

Default friendlyName can be overriden in the following ways:

  • Set friendlyName in the context object
  • Add a field in pre-engagement form with name attribute friendlyName, so that it will be set with what user fills in the form

Note! FriendlyName set by pre-engagement form will override context object

Pre-engagement form data and context data can be accessed in via Programmable Chat REST API

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.