Elements Interactive Forms
Symphony Elements Forms enable bots to send messages that contain interactive forms with pre-designed text fields, dropdown menus, person selectors, buttons and more. This allows bots to interact with users in a very easy and guided way.
By reusing our pre-designed standard UX component libraries, Elements provide developers with out-of-the-box tools to easily create interactive bot messages that look and feel like they belong in Symphony. To use the Elements, you just need to call the Create Message endpoint with your bot, using the MessageML format.
Here after, you will find a brief introduction of how to send Elements, then an update of the message flow for Elements, and finally the form specifications.
Sending Elements
To start using Symphony Elements, you first need to create a form element using the <form>
MessageML tag. The form element can be considered the "frame" of a message, containing elements that will be sent by the bot and subsequently read by the datafeed.
You can see below an example of how a user can interact with a form that was sent by a bot, as well as the messageML structure of the message that was sent by the bot, and the payload that is generated and therefore delivered to the bot via the datafeed, containing the information completed and submitted by the user. Please use the tabs to navigate between these 3 documents.
To begin leveraging Symphony Elements in your bot workflows continue onto our Available Elements that you can find in the subpages.
Message Flow (for Forms)
Every message exists as part of a flow, in a continuum of events that results in user interaction.
Here is that flow in colorful diagram form, for you to know more about each stage of the message:
A Bot sends a message with Symphony Elements in a form
The message/from is visible to users. Users interact with the elements
Once submitted, the data is submitted to the bot
Bots can access the data, by reading the datafeed.
Form specification
MessageML Tag
Forms are represented by the <form> tag, as you can see in the examples above.
Attributes
Attribute | Type | Required? | Description |
| String | Yes | Identifies the form. |
| String | No | Specifies that the form can be submitted several times by the user and the reset behavior. See the possible values and behaviors in Rules and Limitations below. |
Rules and Limitations
The form element can be considered the "frame" of a message, containing elements that will be sent by the bot and subsequently read by the datafeed.
To be considered valid, the form tag must contain at least one action type "Button" as a child. For more information, refer to Buttons.
All of the data within a form element will be sent to a bot via the datafeed when a user clicks one of the action buttons in that form. The
name
attribute of the button will be the value of theaction
field within the datafeed payload. That way the bot manager can know which button triggered the submission of that form. Starting with Agent 23.11, the auto-submit feature allows to submit the form with a TextField, or with a DropDown Menu.If there is more than one element in the form having the same
name
attribute, the value is converted to an array. Every index of the array is related to a specific element value. The index order is not guaranteed, so the developer needs to iterate through this array and collect the values.When a form is submitted and
multi-submit
attribute is not specified, all the elements within it will be disabled, not being possible to edit or resend the same form. However, if the page is refreshed, the user can fill out the form again and submit it as a new form.The attribute
multi-submit
allows the us to submit the form several times even without needing to refresh the page. It can take 2 different string values:reset
which resets the form to the default value when enabling it again for the user,no-reset
which keeps the values that were submitted by the user when enabling it again for the user.
When designing forms, it is important to consider the message size limit. For more information refer to Message size limits.
Examples
The following example shows three forms being used as follows:
The first form (default) shows how Symphony users interact with a form, and how the Elements are disabled once the form is submitted.
The second form (multi-submit-reset) shows how to create a form that can be submitted several times and which resets all its Elements to their default value once the user submits it. You note the Elements are first disabled while loading, then the button shows the user the form has been submitted, before the form is enabled back to its default value for the user to submit it again.
The third form (multi-submit-no-reset) shows how to create a form that can be submitted several times and which keeps last submitted values once the user submits it. You note the Elements are first disabled while loading, then the button shows the user the form has been submitted, before the form is enabled back to its last submitted value for the user to submit it again.
Versions and Compatibility
Main features introduced | Agent needed to parse message sent by the bot | Client 2.0 release | Client 1.5 release | Backward client-compatibility behavior (e.g. external rooms) |
Initial release | 2.55.9 | Since first version | 1.55 | Not working |
Multi-submit attribute | 20.13 | 21.8 | - | - |
Last updated