Important

Symphony Elements Beta is only available on pods that have been updated to 1.55.3 and running an agent 2.55.9 or above.

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.

All the Elements data within a Form element will be sent when the user clicks one of the action buttons within the same Form. The value of the attribute name of the button will be the value of the action field of the datafeed payload, so the bot manager can know what button triggered the action that sent the payload.

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.

For a list of all the available elements, refer to Elements.

The Message Flow

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:

Form Attributes

Attribute
Type
Required?
Description

id

String

Yes

Identifies the form.

Rules and Limitations

  • To be considered valid, the form tag must contain at least one action type "Button" as a child. For more information, refer to Buttons.
  • When a form is submitted, all the elements within it will be disabled, not being possible to edit or resend the same form. However, if the page is refreshed, you can fill out the form again and submit it as a new form.
  • When designing forms, it is important to consider the message size limit. For more information refer to messageML - Message size limits.

Examples

The following example shows a form being presented in MessageML. Also, you can see the returned datafeed payload.

<messageML>
  <form id="form_id"><h4>Personal Information</h4>
    <text-field name="name_01" required="true" placeholder="Name"/>
    <text-field name="email_01" required="true" placeholder="email"/>

    <h4>Select your country</h4>
    <select name="country">
    <option value="opt1">Australia</option>
    <option value="opt2">Brazil</option>
    <option value="opt3">China</option>
    <option value="opt4">Denmark</option>
    <option value="opt5">Ecuador</option>
    <option value="opt6">France</option>
    <option value="opt7">Germany</option>
    <option value="opt8">Italy</option>
    <option value="opt9">Japan</option>
    </select>

    <h4>Choose your option</h4>            
    <radio name="example_radio" value="option_01" checked="true">Marked</radio>
    <radio name="example_radio" value="option_02">Unmarked</radio>

    <h4>Choose your option</h4> 
    <checkbox name="checkbox_1" value="value01" checked="true">Checked</checkbox>
    <checkbox name="checkbox_2" value="value02">Unchecked</checkbox>

    <h4>Send a comment</h4> 
    <textarea name="comment" placeholder="Add your comment here" required="true"></textarea>
    
    <button type="reset">Reset</button>
    <button name="submit_button" type="action">Submit</button>

  </form>
</messageML>
[
    {
        "id": "HHZFPX",
        "messageId": "StQDPAYMXNz1ue4fcr5W7H___pQENqrGbQ",
        "timestamp": 1563297404217,
        "type": "SYMPHONYELEMENTSACTION",
        "initiator": {
            "user": {
                "userId": 7078106482890,
                "firstName": "User",
                "lastName": "Bot",
                "displayName": "User",
                "email": "[email protected]",
                "username": "user_bot"
            }
        },
        "payload": {
            "symphonyElementsAction": {
                "actionStream": {
                    "streamId": "0YeiA-neZa1PrdHy1L82jX___pQjntU-dA"
                },
                "formStream": {
                    "streamId": "YuK1c2y2yuie6+UfQnjSPX///pQEn69idA=="
                },
                "formMessageId": "xtZqqBNGwLDkLuvuQTyjH3///pQENvjudA==5454",
                "formId": "form_id",
                "formValues": {
                    "action": "submit_button",
                    "name_01": "John",
                    "email_01": "[email protected]",
                    "country": "opt1",
                    "example_radio": "option_01",
                    "checkbox_1": "value01",
                    "checkbox_2": "value02",
                    "comment": "test"
                }
            }
        }
    }
]

Updated 6 months ago


Form


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.