Available Elements

Using Symphony Elements and the Create Message API, developers can send bot messages that contain interactive forms with UX components such as text fields, radio buttons, checkboxes, person selectors and more.

The Available Elements pages describe each UX component, how to use them, and provide examples.

When you are ready to start working with Elements, go to our Elements Getting Started Guide, and find out how to Generate Interactive Messages for a Bot.

Elements

To start using Symphony Elements, you first need to create a form using the Form element. 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.

Note that to send a form with Symphony Elements, you must call the Message Create API using the messageML message format. See Example below.

  • Datafeed: the datafeed provides messages and events from all conversations that the user is in. When end users send a completed form by clicking on a submission button, all the information needed to differentiate which user and action that click is related to will be sent to the datafeed.
    Through the Datafeed Read API, developers are able to see the datafeed payload containing all the information related to the user's interaction with the Bot and its elements.

The following list shows the currently available elements. Click on the element to learn more about its implementation, limitations, and examples:

* [Form](doc:form) * [Buttons](doc:button) * [Text Field](doc:text-field) * [Text Area](doc:text-area) * [Checkbox](doc:checkbox) * [Radio Button](doc:radio-button) * [Dropdown Menu](doc:dropdown-menu) * [Password](doc:password) * [Person Selector](doc:person-selector) * [Tables](doc:tables)

Availability & known limitations

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.

Known limitations:

  • Symphony Elements cannot be sent cross-pod.
  • Mobile clients cannot interact with Symphony Elements.
  • Symphony Elements responses are not captured in Content Export.
  • A Bot needs to be in the Room, IM or MIM conversation to be able to read Elements form replies from users.
  • Symphony Elements datafeed payload: the payload structure is subject to change in the next version.

Important: The limitations are temporary – they may change in the future.

MessageML

Currently, all the available elements use a specific structure to render messages based on MessageML v2. In the following example, you can see a form being sent through the Create Message V4 API.

PresentationML Live Renderer Tool

Symphony provides a Renderer Tool that you can use to test your MessageML v2 code and see how it would appear on Symphony. For more information, refer to PresentationML Live Renderer Tool.

1) Here, you can see the MessageML code used to send a message with a form within it.

<messageML> 
    <form id="form_id"> 
        <h2>Full name</h2>
        <text-field name="name_01" required="true" />
        
        <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="In my opnion..." required="true">In my opnion...</textarea>
        
        <button type="reset">Reset</button>
        <button name="submit_button" type="action">Submit</button>
                  
    </form>
</messageML>

2) And here, you can see the rendered form:

3) Finally, the generated interaction payload when the Submit button was clicked.

Payload changes

The payload structure is subject to change in the next version.

[
    {
        "id": "kzwn0A",
        "messageId": "Yzy7OoPQnLI9DTCKWmIRMX___pQEChSZbQ",
        "timestamp": 1563300326246,
        "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": "q79Am2NpPefaV42JogMPRX///pQEDbD+dA==5653",
                "formId": "form_id",
                "formValues": {
                    "action": "submit_button",
                    "name_01": "John Doe",
                    "country": "opt1",
                    "example_radio": "option_01",
                    "checkbox_1": "value01",
                    "checkbox_2": "value02",
                    "comment": "In my opinion..."
                }
            }
        }
    }
]

Updated 4 months ago


Available Elements


Suggested Edits are limited on API Reference Pages

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