This article gives an overview of the message workflow and shows how message representations are used throughout the workflow. In its subpages are presented the specifications of messageML.
Introduction of the MessageML
When calling API methods that create messages, the content of the message must be sent using MessageML markup. MessageML is a tag-based language that is a subset of XHTML, with the addition of tags specific to Symphony Messaging for embedding information (e.g. a mention) into a message.
You can find the specifications of the MessageML language in the attached subpages. Even if they are grouped in different categories for documentation clarity purposes, please note you can do your own mix, respecting the specific rules explained at each component specification level.
Also, please note that messages in MessageML markup are enclosed in a <messageML> tag.
MessageML has full unicode support and messages should be sent using UTF-8 character encoding.
When or messages using the API, MessageML shorthand tags are translated into equivalent XHTML tags and returned in .
Note: MessageML is just a subset of PresentationML that makes it easier to construct messages from your bot. The API can ingest either MessageML or PresentationML. However, the API will only deliver messages as PresentationML to a bot.
XML Formatting
MessageML is formatted as XML and should have all tags properly formatted. For example, rather than using <br> you must use <br/>.
For string attributes, standard rules for escaping XML special characters apply, i.e. escaping:
' with ' (if single quotes are used to quote the value)
" with " (if single quotes are used to quote the value)
< with <
& with & Other XML named entity sequences such as > may be used.
Valid characters for hashtags and cashtags
Keywords may only contain alphanumeric characters, underscore, dot and dash.
Important: when sending numeric $cashtags as signals, add an * after the $ sign, for example, $_122450.
<cash tag="$_122450"/>
Please find below the list of icons that can be used with Elements Buttons.
Extensibility UI Actions
With Actions, MessageML allows your bots to send messages containing components that have UI extensibility capabilities, such as opening another chatroom or start a conversation with a specific user for your Symphony users.
These functionalities are gathered in the subpages you can find below.
The UI Actions are represented by the <ui-action> tag, that can be associated with different attributes, such as trigger, action, or other more specific attributes.
MessageML tag
Please note that UI-Actions are not rendered on mobile
Tables
Tags
MessageML supports the following tags to arrange information within a message using tables:
Tags
Description
Optional attributes
<table><tr><td>text</td></tr></table>
Render "text" in a table format.
Here after you can find an example of a message sent by a bot and containing table tags as well as the structure of the messageML sent:
Date and time
You can display a date, time or datetime to your user taking into account your user's date/time formats, as well as their timezone using the dateTime element.
Tags
Tags
Description
Attributes
<dateTime value="2024-12-31T09:29:47Z" format="date | time | time_secs"/>
Display a date or time to the user, taking into account the user locale timezone.
value (required): ISO-8601 or UTC timestamp.
format:
date_time: date + time format based on user settings and user timezone. Default value if no format is provided
This element is read-only - if you want an interactive element instead, you can use a or in a chat.
Versions and Compatibility
Main features introduced
Agent needed to parse message sent by the bot
Entities
Entities (also called Structured Objects) are rich, inline, interactive components for Symphony messages that allow you to embed information that is more complex than simple text.
To create a message containing a Structured object, construct the message content using MessageML with either a <div> or a <span> element containing the following attributes:
class="entity": specifies that the message contains a corresponding structured object.
data-entity-id: the unique ID of the corresponding structure object.
This MessageML markup is then passed into the endpoint via the message parameter. The following examples show the use of the attributes in <div> and <span> respectively:
The examples above reference an entity object called entityIdentifier. The JSON corresponding to this object is passed to the create message endpoint via the data parameter. For example:
Please continue below in the subpages if you want to learn more about Structured Objects
Images
MessageML supports the following tags to embed media into messages:
Tags
Description
Attributes
Regular Expressions - Regex
Elements input validation. Available from Symphony v20.6 and above
Input validation is your first line of defense when creating a secure application.
Symphony Elements supports input validation using regular expressions (regex) for the text field and text area elements.
Regular expressions can cause performance issues in the Client if the validation of the regular expression is very complex. Poorly designed regular expressions can even cause denial of service (ReDoS). Please verify that your regular expressions are safe, using the following service: .
For more information, refer to .
date : ddMMyyyy with format based on user settings (DD/MM/YYYY, MM/DD/YYYY, YYYY/MM/DD) and user timezone
time : hhmm with format based on user settings (12h / 24h) and user timezone
time_secs : hhmmss with format based on user settings (12h / 24h) and user timezone
The following code snippets assumes that both <text-field> and <textarea> elements are placed within the right messageML context : <messageML> + <form> including an action <button>.
<!-- Validates a login -->
<text-field name="login" pattern="^[a-zA-Z]{3,}$" pattern-error-message="Login must contain at least 3 letters."></text-field>
<!-- Validates a decimal value, hint is not defined -->
<text-field name="price" pattern="^\d+,\d+$" pattern-error-message="This is an incorrect value."></text-field>
<!-- Validates a password -->
<text-field name="password" masked="true" pattern="^[a-zA-Z]\w{3,14}$" pattern-error-message="Your password is not strong enough."></text-field>
The regular expression pattern is validated on the front end by the Client. It is therefore critical to also validate the input in your code as well.
Regular expression Denial of Service - ReDoS
To prevent performance issues on the Client, a validation mechanism checks regular expressions to ensure they are safe. If the regular expression is unsafe, it is automatically disabled. In that situation, the user input will not be validated.
<!-- Validates that a line does not contain the word "badword" -->
<textarea name="justification" pattern="^((?!badword).)*$" pattern-error-message="Justification text must not contain the word 'badword'"></textarea>
For the following examples, we are sending an SVG image along with the message.
Note that an admin user might have to enable the sending of some specific file types. To do that, go to AC Portal >> Company Settings >> Edit Entitlements >> File Types.
• Sending an image via the Create Message API using the image URL
Sending an image via Create Message API using Data URL (base64 encoding).
Note that it is necessary to include data:image/imageType+xml;base64 before the data string, as shown in the following example:
Here after you can find an example of a message sent by a bot and containing an inline image as well as the structure of the messageML sent:
<messageML>
<h1>Images</h1>
<p>This is an image: <img src="https://play-lh.googleusercontent.com/-lTkJjeUtCj3Mf4FLLNKnCyQC0Amur3wxeKxkwbDZl0hjO60H1_VodAuBDKJmYWOvlfG=s180-rw" /></p>
</messageML>
<img src="url"/>
Image. Images have a max height of 256px; otherwise, the default size is the size of the image. For more information on how to send images through API call, refer to Sending images.
This feature is intended to be used for small images, such as custom emoji. Our recommendation is that the total size of base64 encoded embedded images do not exceed 25KB per message.
MessageML supports the following tags for formatting content within a message:
Tag
Description
Optional attributes
<br/>
Insert a line break.
Here after you can find an example of a message sent by a bot and containing these formatting and semantics tags as well as the structure of the messageML sent:
The Apache Freemarker uses the HTML output format by default. In some cases, special characters placed within the MessageML must be HTML-escaped, otherwise, the request sending the MessageML will receive a 400 error response. The following are examples of valid HTML-escaping:
Character
HTML escaping
Required escaping
messageML example
Here after you can find an example of a message sent by a bot and containing these special characters as well as the structure of the messageML sent:
Room Selector
The Room Selector is an element that allows users to find and select both rooms or persons. It behaves the same way as the chat selector you see when you forward a message and select where the message should be forwarded.
When a user starts typing in the field, a list of conversations and people will be displayed for selection. Only the chats that the user has access to will be displayed.
Attributes
Attribute
Type
The Room Selector element supports multi selection which means that you can search for more than one chat or person.
The Room Selector is not yet available on Symphony Mobile. Mobile will be supported in a future release.
Example of a room selector with both a room and a user pre-selected.
Please note that pre-selected streamIds must follow
Resulting payload when a user submitted the form afer having selected two chats and one user in the Room Selector.
Content Grouping
MessageML supports the following tags for grouping information within a message:
Tag
Description
Optional attributes
Style Attributes
Tags support the following style attributes where applicable:
To learn more about Symphony's built in styles, continue here:
Required?
Description
name
String
Yes
Identifies the room selector.
placeholder
String
No
Specifies a short hint that describes the expected value of the field.
required
Boolean
No
If true, at least one chat or person must be selected to be able to submit the form.
label
String
No
Label displayed on top of the Room Selector.
value
Array of
string
No
Default values that will be preselected in the Room Selector. The array can contain both streamIds, as well as userIds. Please note that if the user does not have access to these users or conversations, they will not be displayed.
<messageML>
<form id="test">
<room-selector name="room-selector"
label="Select the chats where the alert will be sent."
value="['rsxB51ieSYfPLQ0jgFKg93___nUqhvz4dA','9139691037944']"
placeholder="Select rooms"/>
<button name="submit_button" type="action">Create Alert</button>
</form>
</messageML>
Bold formatting.
Note: when receiving a message from an Agent that contains whitespace between the last character in a bolded section and the closing </b> tag, the bold section will be returned in Markdown (i.e. surrounded by double '*' characters) instead of XHTML tags.
Italics formatting.
Note: when receiving a message from an Agent that contains whitespace between the last character in an italics-formatted section and the closing </i> tag, the italics section will be returned in Markdown (i.e. surrounded by single '*' characters) instead of XHTML tags.
• class: color options.
• Non-HTML MessageML are not supported inside <pre>.
<span>text</span>
No formatting.
• This tag can be used to specify visual styles, by adding a class attribute.
• This tag is used to create Structured objects.
• class: color options.
• data-entity-id
• See below for list of translated PresentationML attributes.
<code>code sample</code>
Format the text as a block of code.
language: Use the language attribute to benefit from language specific code highlighting. The following languages are available: c, cpp, csharp, css, html, java, js, jsx, php, python, r, typescript, tsx, plaintext, yaml, scala, json, shell, markdown
Note: language attribute is only available with Agent 20.14+.
Note: please see escaping rules for when using code tag
Initial release
Since the first version
Since the first version
Examples
<messageML>
<h1>Formatting and semantics</h1>
<p>This is a <a href="https://docs.developers.symphony.com/">Link</a> to our developer documentation.</p>
<p>Part 1 of the paragraph separated from part 2 with a line break.<br/>Part 2 of the paragraph.</p>
<p>This text can be either <b>bold</b> or <i>italic</i> or <span style="color:red;">red</span>, or even combine <b><i style="color:red;">several</i></b> formatting tags.</p>
<pre>This is a preformatted text.</pre>
<code language="html"><h1>Code sample</h1>
<p>This is some html</p></code>
</messageML>
Versions and Compatibility
-
<p>paragraph</p>
Paragraph formatting.
• class
<hr />
Horizontal rule.
None.
<ul><li>list item</li></ul>
Unordered or bullet list.
Cannot be empty, must contain at least one child <li> item.
• class
<ol><li>list item</li></ol>
Numbered list.
Cannot be empty, must contain at least one child <li> item.
• class
<div>paragraph</div>
Block of text.
• This tag can be used to specify visual styles, by adding a class attribute.
• This tag is used to create .
• This tag is also the root of any message read through the API.
• class:
• data-entity-id
• data-icon-src
• data-accent-color
• See below for list of translated PresentationML attributes.
<card> (see example below)
Inserts a card. It contains two different sections:
• the <header> (always visible)
• the <body> (hidden)
• iconSrc: image will be resized to 28 pixels by 28 pixels, use spacious mode. (.jpg, .png and .gif)
• accent: use to select the accent color of the card.
<expandable-card> (see example below)
Inserts a card with new styles and multiple levels of display within the card
• state (mandatory) in <expandable-card> can take 3 values:
- "collapsed": only header is visible
- "cropped": card expanded but the body is cropped
- "expanded": card fully expanded
• variant (optional) in <body>: defines the style of the card. It can be either "default" for the default blue style, or "error" for the red error style
Here after you can find an example of a message sent by a bot and containing these content grouping tags as well as the structure of the messageML sent:
<messageML>
<h1>Heading texts</h1>
<h1>This is a h1 heading text</h1>
<h2>This is a h2 heading text</h2>
<h3>This is a h3 heading text</h3>
<h4>This is a h4 heading text</h4>
<h5>This is a h5 heading text</h5>
<h6>This is a h6 heading text</h6><br/>
<h1>Paragraphs</h1>
<p>This is a paragraph.</p>
Please note that you can use content grouping tags mixed with other messageML tags such as Interactive Elements Forms. See the following example including forms in expandable-cards.
<messageML>
<form id="form_id">
<h1>expandable-cards</h1>
<h2>1st expandable-card</h2>
<expandable-card state="collapsed">
<header><h3>Header Content (always visible)</h3>This is a <b>collapsed</b> expandable-card with the <b>default</b> variant</header>
<body>
<h3>Body Content</h3>
It is possible to use Elements in the body as you can see below:
<text-field name="id1" placeholder="Enter your name..."/>
<text-field name="id2" placeholder="Enter your age..."/>
<button type="reset">Reset</button>
</body>
</expandable-card><br/>
<h2>2nd expandable-card</h2>
<expandable-card state="expanded">
<header><h3>Header Content (always visible)</h3><text-field name="id_header" label="Text-field in the header" placeholder="Type your input..."/>This is an <b>expanded</b> expandable-card with the <b>default</b> variant and with a <b>Symphony Element</b> in the header</header>
<body>
<h3>Body Content</h3>
When expanded, the whole body content is displayed in the expandable-card.
<text-field name="id3" placeholder="Enter your name..."/>
<text-field name="id4" placeholder="Enter your age..."/>
</body>
</expandable-card><br/>
<h2>3rd expandable-card</h2>
<expandable-card state="cropped">
<header><h3>Header Content (always visible)</h3>This is a <b>cropped</b> expandable-card with the <b>error</b> variant</header>
<body variant="error">
<h3>Body Content</h3>
When cropped, the body content is displayed in the expandable-card until a certain limit. A show more button allows to expand the card and display the rest of the body.
</body>
</expandable-card>
<button name="form_id_submit">Submit</button>
</form>
</messageML>
<h1>, <h2>, <h3>, <h4>, <h5>, <h6>
Heading text. 6 levels.
Tags
• class
Examples
<
<
Yes
<messageML><</messageML>
&
&
Yes
<messageML>& </messageML>
$
$
Yes The $ character only needs to be escaped if it comes before the { character.
<messageML>${}</messageML>
#
#
Yes The # character only needs to be escaped if it comes before the { character.
<messageML>#{}</messageML>
>
>
No
<messageML>></messageML>
"
"
No
<messageML>"</messageML>
'
'
No
<messageML>'</messageML>
*
*
No
<messageML>*</messageML>
%
%
No
<messageML>%</messageML>
Examples
<messageML>
These are special characters:
<ul>
<li><;</li>
<li>&;</li>
<li>$ or $;</li>
<li># or #;</li>
<li>> or >;</li>
<li>" or ";</li>
<li>' or ';</li>
<li>* or *;</li>
<li>% or %.</li>
</ul>
</messageML>
Tags and mentions
Tags
MessageML supports the following tags to embed additional information into messages:
Tag
Description
Optional attributes
<mention uid="123456789"/>
Insert a mention for the user whose Symphony userid is 123456789.
Here after you can find an example of a message sent by a bot and containing these tags specific to Symphony Messaging as well as the structure of the messageML sent:
Below several examples of financial instruments, using different types of identifiers and filters.
When identifiers and filters are not sufficient to identify a unique match, or when an instrument is not found in our reference database, an error is returned, except if a fallback-ticker is specified.
Enhanced tags notice
This page describes the changes introduced by the new enhanced tags for Symphony developers
Introduction to the enhanced tags
Symphony users can now tag financial instruments using the Enhanced Tag feature.
Instrument lookup type-ahead by ticker, name, ISIN, etc.
It displays a typeahead when the user presses # in a chat conversation. The upper section of the typeahead shows regular hashtags previously exchanged with that user and the lower section, under INSTRUMENTS shows Stocks, ADRs, ETFs and Indices.
By hovering over the Enhanced Tag, users can see essential reference data like company name, identifiers, exchange and currency.
New hovercard for the enhanced tags
The enhanced tags replace the existing $cashtags. This means that moving forward your apps and bots will need to handle enhanced tags instead of $cashtags.
Understanding the impact of the new tags
The impact of the enhanced tags on existing bots & apps has been carefully reviewed to ensure that there is no backward compatibility issue.
However, we strongly recommend that you conduct some tests to validate the change.
Please read below to understand the changes introduced with the new enhanced tags.
Existing bots can still produce legacy $cashtags both using the short tag notation (<tag cash="AAPL"/>), and using a Standard Entity ("type": "org.symphonyoss.fin.security")
Existing bots can easily include enhanced tags in messageML now. To do so, you will need to cuse the <tag> and provide one or several identifiers for that instrument. The instrument will then be resolved against our reference database, and properly formatted in the message. More information is available .
Bots consuming existing $cashtags in received messages are not impacted if they rely on the structured object (entityJSON). When they receive an enhanced tag, the exact same structure and properties will be present. There will be additional properties though, and the version field will be set to "2.0" instead of "1.0".
Bots that rely on the text representation of the tags (message field instead of the entityJSON field) will also not be impacted. However, this is not a recommended practice as this text representation may change to match the enhanced tag displayed symbol instead of the existing ticker in the future (e.g., text would change from "$TSLA" to "TSLA US"). If you rely on the text representation of the $cashtag instead of the structured data, you should consider updating the bot to rely on the structured data included in the entityJSON instead.
Existing signals will continue to work with the new enhanced tags. Messages containing the new tags will still match with the existing signals, meaning a signal matching "cash: AAPL" will match messages containing both "AAPL" and "AAPL US" for example.
For now, it is not yet possible to create signals based on the newly introduced properties of the enhanced tags, but this will change in the coming months. For example, it is not yet possible to create a signal that will match only on "TSLA US", but if you create a signal that matches on "TSLA", it will match messages containing "TSLA US" as well.
Existing apps that register a UI extension on $cashtag hovercards continue to receive the existing object for new enhanced tags.
However, whenever your app is notified of a user click on the hovercard, the app will receive in addition to the existing object a new structure containing the new enhanced tags properties.
If you decide to upgrade your app to leverage the new properties of the enhanced tags, please consider that you may still encounter legacy $cashtags for a long period of time, so should build around that. To detect if you are receiving a legacy tag or an enhanced one, you can rely on the version field included in the structure (org.symphonyoss.fin.security.version). It is set to "2.0" for the new enhanced tags.
Please note below the differences between the structures of the enhanced tags and the legacy $cashtags.
Radio Button
Radio buttons are shown as small circles, which are filled or highlighted when selected. Only one radio button in a given group can be selected at the same time.
Frequently, a set of radio buttons represents a single question which the user can answer by selecting a possible answer.
Note: If you want the user to be able to select more than one option, use the Checkbox element.
Attributes
Attribute
The text node of the MessageML will be converted to the <label> tag. This will preserve the formatting tags <i> and <b>, if present.
Radio buttons are presented in radio groups (a collection of radio buttons describing a set of related options). Only one radio button in a group can be selected at the same time. Note: The radio group must share the same name (the value of the name attribute) to be treated as a group. Once the radio group is created, selecting any radio button in that group automatically deselects any other selected radio button in the same group.
The following example shows radio buttons being used. It shows how developers can use the checked parameter with the value01 preselected when the form is sent. It also shows how users can select another radio button and how it automatically unselect any other value checked, as the 3 radio buttons have the same name and therefore are part of the same group "groupId".
OpenChat
Chat bots can add buttons in chat messages that on click will open an existing chat room or start a chat with a specific user or group of users.
This can be useful to help Symphony users easily navigate from one chat to another, or to reference another discussion happening in a different chat.
The new chat can either replace the current chat, or open on the side instead.
MessageML tag
OpenChat is represented in MessageML as a <ui-action action='open-im'> tag and wraps a single button.
The <ui-action> tag for OpenChat supports the following attributes:
Symphony users can interact with the OpenChat functionality via their keyboard using either "Enter" of "Space" to trigger the click action, once the UI component used for the OpenChat (i.e. button element) is in focus. Symphony users can move from one Element to another using "Tab".
The following examples show the OpenChat functionality being used as follows:
The first open-im shows how the Symphony user may interact with a primary button that is empowered with the OpenChat functionality that opens a specific stream on the side of the current chat. Note that the trigger and side-by-side attributes are not mentioned, as they are not mandatory: they are then defined by their default behaviour.
The second open-im shows how the Symphony user may interact with a secondary button that is empowered with the OpenChat functionality that opens an IM with a specific user on the side of the current chat.
The max length of any ui-action attribute is 256 except user-ids attribute which max length is set to a list 15 ids.
The OpenChat functionality is not supported in forms (see ).
Please note that the attribute type
Checkbox
The checkbox is an interactive box that can be toggled by the user to indicate an affirmative or negative choice.
When clicked, a checkmark (✓) appears inside the box, to indicate an affirmative choice (yes). When clicked again, the checkmark disappears, indicating a negative choice (no).
Checkboxes are used to let a user select one or more options from a limited number of choices. Frequently, a set of checkboxes represents a single question which the user can answer by selecting any number of possible answers.
Note: If you want the user to only be able to pick a single option, use the or the element.
Attributes
Attribute
The text node of the MessageML will be converted to the <label> tag. This will preserve the formatting tags <i> and <b>, if present.
A form can have a maximum of 50 checkboxes within it. Note: The limit in previous versions was set to 20, so this limit may still apply when sending messages to customers with an earlier version of Symphony (before 20.10).
The following example shows checkboxes being used. It shows how developers can use the checked parameter with the value01 preselected when the form is sent. It also shows how users can select or unselect one or several checkboxes before submitting the form, as well as how to reset it to its initial values.
Custom Entities
Definition
Structured Objects are rich, inline, interactive components of Symphony messages. Objects allow you to build innovative workflows that go beyond working with normal text or attached files.
Unlike normal message text, these objects are structured and do not need to be parsed to have business logic.
Unlike attachments, end-users can view and interact with objects directly from their Symphony client, without having to change context.
Structured Objects can be "injected" into Symphony by sending messages using Symphony's REST API.
Structured Objects can be rendered richly using .
To inject messages containing structured objects:
Your pod must be configured for Symphony's REST API, and you must have the Agent, the component used for handling encryption and decryption of messages and content, set up.
Your Agent must be version 1.51 or later.
You must have an X.509 identity certificate for your bot service user for REST API authentication, where the common name on the certificate matches your service user's username.
To build renderer applications for displaying your structured object:
You need to have an extension application created and enabled on your pod.
Structured Objects are placed into Symphony messages and have two components:
Object Presentation, in format.
Object Data, a JSON object.
Any message in Symphony can contain zero or more Structured Objects.
A message will always contain message presentation, in MessageML v2 format, with the optional object presentation of the Structured Objects it may contain.
If the message contains any structured objects, it will contain JSON data with all object data of the structured objects it may contain.
You can create an object by invoking the endpoint. You need to include:
The message parameter, which contains the message presentation, with the object presentation for each Structured Object.
The data parameter, which contains JSON data with the object presentation for each structured object.
These parameters also support using with Structured Objects.
Message presentation is represented in MessageML format. For example:HTML
To add an object to a message, include a div or a span tag with a unique data-entity-id attribute:HTML
The data-entity-id tag refers to a specific object in the JSON data, which needs to include:
The data type.
The data version of that type. Both are needed to build renderer applications which can render this type of that version.
This data can be used by applications in the web client to provide a rich display or end-user interactivity. In case no specific renderer application is available, you must provide a default presentation in the div or a span tags.HTML
You can read objects using any of the endpoints designed to read messages, for example, the endpoint. This endpoint will let you read both the message presentation and object data fields.
Renderer Applications leverage the Extension API to dynamically replace the presentation of a structured object.
To create a renderer application:
Create an
Your application needs to use the , which will allow you to:
Register your application as being able to render a specific type, using the .
To learn more about building Extension Applications that leverage structured objects, continue here:
Render the object itself, by implementing the render function.
Prerequisites
Sending Structured Objects in Messages
Message and Object Presentation
Reading objects
Note:
As described in Message Format - MessageML v2, messages with Structured Objects can be created using the shorthand tags or the full tags. When they are read, the message presentation always contain the full tags, which are a subset of HTML tags.
<messageML>
Hello <mention email="user@music.org" />. Here is an important message
</messageML>
<messageML>
Hello <mention email="user@music.org" />. Here is an important message with an
<div class="entity" data-entity-id="object001" />
included.
</messageML>
<messageML>
Hello <mention email="user@music.org" />. Here is an important message with an
<div class="entity" data-entity-id="object001">object</div>
included.
</messageML>
If you plan to upgrade your bot to leverage the new properties of the enhanced tags, please consider that you may still encounter legacy $cashtags for a long period of time, so should build around that. To detect if you are receiving a legacy tag or an enhanced one, you can rely on the version field included in the structure (org.symphonyoss.fin.security.version). It is set to "2.0" for the new enhanced tags.
The Signal API has not changed. In the coming months the API may change to adapt to the new tags and in that case this change will be introduced following a notice period provided that there is an impact on the API contract.
// Presentation ML content of the message
<div data-format="PresentationML" data-version="2.0" class="wysiwyg">
<p><span class="entity" data-entity-id="0">$SAN</span></p>
</div>
// Entities (entityJSON field in the message):
{
"0": {
"id": [
{
"type": "org.symphonyoss.fin.security.id.ticker",
"value": "SAN"
}
],
"type": "org.symphonyoss.fin.security",
"version": "1.0"
}
}
A form can have a maximum of 50 radio buttons. Note: The limit in previous versions was set to 20, so this limit may still apply when sending messages to customers with an earlier version of Symphony (before 20.10).
Once the user has selected a radio option, it can be deselected only by clicking on another radio option. The only way to deselect all the radio options is by clicking the reset button.
Type
Required?
Description
name
String
Yes
Identifies the radio button.
value
String
No
The value is the string that will be sent to the server. If the value is not specified, the string on will be sent by default.
checked
Boolean
No
If true, it specifies that the <radio> element should be pre-selected (checked) when the page loads. Accepted values: true and false.
List of ids of the users with whom the MIM must be opened when the Symphony user triggers the OpenChat functionality.
stream-id
String
Exclusive with user-ids
The id of the room/IM that must be opened when the Symphony user triggers the OpenChat functionality.
NB: Please note that the stream-id is the exact Conversation ID that you can find in the UI, and not the URLSafe64 converted id (see more details in)
side-by-side
Boolean
No.
Default to true
If set to false, the current chat will be replaced by the new chat to be opened when the Symphony user triggers the OpenChat functionality.
The third open-im shows how the Symphony user may interact with a tertiary button that is empowered with the OpenChat functionality that opens a chat with a specific list of users on the side of the current chat.
The fourth open-im shows how the Symphony user may interact with a destructive button that is empowered with the OpenChat functionality that opens a specific stream that replaces the current chat.
of the button is not supported when wrapped by a
<ui-action>
tag.
When using user-ids attribute with 2 or more ids in the list, the functionality will always create a new chat between the considered users; it will not reopen an existing chat between these same users. This is a known limitation that might change in the future.
In case the side-by-side attribute is set to true, when the Symphony user interacts with the OpenChat component, the IM/Chatroom appears on the side of current module in focus. In case the current module is not part of a workspace, then clicking on the button automatically creates workspace and focuses automatically to the desired IM/chat.
The OpenChat feature is supported in popped-out mode with the following behaviour:
Current chat/IM on focus is popped-out independently from a workspace:
In case the side-by-side attribute is set to false, the popped-out module is replaced by the desired one
In case the side-by-side attribute is set to true, the popped-out module remains in place and the desired one opens in the main Symphony client
Current chat/IM on focus is part of a popped-out workspace (Capital Markets view only): same behaviour as if the workspace was not popped out: if the specific chat to be opened is not part of the workspace, it is automatically added, and then opened either on the side or in the place of the previous focused chat depending on the side-by-side attribute.
When opening a specific chatroom where the user is not part of, then:
If it is a private room, a modal dialog will appear informing the user he cannot perform the action
If it is a public room, then the user is automatically added to the room and the considered stream is opened
The side-by-side attribute set to false is meaningful only for users in Client 2.0
Insert a mention for the user whose email address is user@music.org.
• strict=true, the API will throw an error if no user of that email address exists. (default)
• strict=false . Message is accepted even if the user cannot be resolved.
<hash tag="label"/>
Insert "label" as a free-text hashtag.
<cash tag="ticker"/>
Insert "ticker" as a free-text cashtag. Important: when sending numeric cashtags as signals, add a * after the $ sign, for example, $_122450. <messageML> `<cash tag="$_122450"/> `\
Note: Cashtags are deprecated. Please use the <tag /> notation for financial instruments.
<tag />
Insert a financial instrument (enhanced tag) in your message, coming from our reference database.
The following instruments are supported: Stocks, ETFs, Indices and currency pairs.
To identify an instrument, you'll need to provide at least one identifier (e.g. an ISIN), and optionally some filters if your identifier is not specific enough.
You can also specify a fallback-ticker that will act as a free-text tag (workaround) if we are not able to find the instrument referenced.
Note: No other content (even line breaks) is permitted with a <chime/> tag. Please see an example of the messageML to send a chime below.
<messageML>
<br/><span>Mention with an email: </span>
<mention email="pierre.neu@symphony.com"/>
<br/><span>Mention with a user Id: </span>
<mention uid="71811853190567"/>
</messageML>
Buttons are the Symphony elements responsible for submitting a form to the bot. As a result, all Symphony form elements are required to have at least one button where `type=action`. When an end-user clicks this button, the form and the value of each of the elements inside will be submitted to the bot via the datafeed and presented as a JSON payload.
In addition, some forms can contain reset buttons. These buttons are used to reset a form back to its original state.
Buttons support six different styles: primary, primary-link, secondary, tertiary, destructive and destructive-link. Each of those has different colors to suit different actions (to convey meaning). Use the class attribute to specify the style.
Primary: use the Primary button when there is a clear primary action on a message. You can use it for the submit button, for example.
Secondary: use the Secondary button when there are multiple actions of the same importance or some actions with less importance than a single primary action.
Destructive: use the Destructive button when an action results in the removal of an item or if it can result in a potentially serious negative consequence.
If class is not defined, the action button assumes the primary class by default. Action buttons should be used for affirmation or confirmation actions.
Reset buttons have the secondary class set by default. Reset buttons should be used when the content of the fields need to return to their original state.
The following example shows the use of the Reset and the Submit button when sending a text inserted in a .
Primary-link, Tertiary and Destructive-link: These styles are variations respectively of the Primary, Secondary and Destructive buttons but without borders. They are low prominence options that can be used alongside a Primary or as standalone buttons with the ability to read more information.
type
String
No.
Default:action
Indicates whether the button is an action button or a reset button. When clicked, the action button sends the form information to the datafeed. On the other hand, the reset button resets the form-data to its initial values.
Accepted values: action and reset.
class
String
No.
Default: primary
Toggle between new palette of colors: primary, secondary, destructive, primary-link, tertiary and destructive-link.
icon
String
No
Adds an icon before the button name. Only icons from our are supported. Each icon is identified by its name.
formnovalidate
Boolean
No.
Default: False
Indicates if this submit button bypasses the form validation (required fields and regular expressions). This can be useful in some situations such as "Cancel" buttons that user should still be able to click even if other form is not in a valid state.
Reset features behaviour is to show back the initial value of the form
2.55.9
Since first version
Since first version
New styles:
• New designs for the buttons
• Styles primary destructive and secondary destructive are deprecated
• Styles tertiary and destructive are introduced
20.6
Since first version
Since first version
New styles: primary-link and destructive-link
Support for icons.
The textarea element is a field for multi-line text input, allowing users to edit multiple lines of plain text. Text areas are useful to collect or edit runs of text like messages, opinions, reviews, articles, etc.
Attributes
Attribute
Type
Required?
Description
With Symphony v20.6, bot developers can use Regex to validate text fields and text areas using the pattern and pattern-error-message attributes.
For more information and examples, refer to Regular .
The text field must be a self-closing tag or have no children.
You can add a default text in your text area by including it between the <textarea></textarea> tags. Note that unlike the placeholder text, the default text will be sent with the form if not edited by the user. Refer to Examples for more information.
The following example shows two textareas being used as follows:
The first textarea (id1) shows how to display a default text ("With initial value"). Note that the default text would have been sent to the payload if it had not been deleted before submitting the form.
The second text-field (req) shows how a placeholder text ("Required, with a placeholder, a regex, a label, and a tooltip") is displayed in the UI. Please note the placeholder text is not sent in the payload if no text has been entered in the field by the enduser. It shows as well the behaviour of a required textarea in a form, which cannot be submitted in case it is not filled; an error is displayed under the textarea in case the user submits the form with this empty field. The textarea presents how a label text ("My Label") as well as a title text ("My Tooltip/n With a second line") are displayed in the UI. Finally, it shows how users can interact with a regex pattern which does not allow the form to be submitted if the input does not follow the pattern required by the bot developer.
Masked Text Field
see Text Field for more information
The masked text input is a single-line plain text editor control in which the text is masked by replacing each character with a dot (•) symbol, providing a way for the user to enter data without people over their shoulder being able to see what they are entering.
Use the maxlength and minlength attributes to specify the maximum and minimum length of the value that can be entered.
Attributes
With Symphony v20.6, bot developers can use Regex to validate text fields and text areas using the pattern and pattern-error-message attributes.
For more information and examples, refer to .
The masked text field has a max number of 128 characters.
The masked text field must be a self-closing tag or have no children.
The masked text field is a feature that only hides the content in the UI. Even though it is masked in the UI, the text will be submitted in clear and processed & encrypted the same way as any other text entered in Symphony.
The following examples show masked text-fields being used as follows:
The first masked text-field (init) shows how to display a default text ("With initial value"). Note that the default text would have been sent to the payload if it had not been deleted before submitting the form.
The second masked text-field (placeholder) shows how a placeholder text ("Only Placeholder") is displayed in the UI. Please note the placeholder text is not masked nor sent in the payload if no text has been entered in the field by the enduser.
The third masked text-field (
Person Selector
The Person Selector is an element used for finding and selecting people. Person Selectors are used in many places within Symphony, so you should be familiar with how they work.
When a user types the person's name, a drop-down will be displayed with the results found for the data the user entered. The following example shows how three people with the same name (Vincent) have been found.
Attributes
Attribute
Type
The Person Selector element supports multi-user selection which means that you can search for more than one person using the same selector.
The following examples show person selectors being used as follows:
The first person-selector (placeholder) shows how a placeholder text ("My Placeholder") is displayed in the UI. Please note the placeholder text is not sent in the payload if no option from the dropdown menu has been selected by the enduser.
The second person-selector (placeholder) shows how the bot can introduce a default value in the person selector. It shows as well how a Symphony user can interact with the clear all functionality.
The third person-selector (
Regex
20.6
Since first version
Regex validation not enforced but field can be submitted
Label
20.7
Since first version
Label displayed and form can still be submitted
Tooltip (title)
20.7
Since first version
Tooltip not displayed but form can still be submitted
row and col
23.11
24.1
Not supported.
name
String
Yes
Identifies the text area.
placeholder
String
No
Specifies a short hint that describes the expected value of the text area.
required
Boolean
No
If true, it specifies that the text area must be filled out before submitting the form. Accepted values; true and false.
pattern
String
No
Regex String to match for input validation
pattern-error-message
String
No
Error message returned to user if pattern parameter matches user input
title
It accepts a simple text and \n for line breaks
No
The description that will be displayed when clicking the tooltip icon located on top of the Masked Text Field Element. Max length: 256 characters. Available from Symphony v20.8 and above.
label
String
Not required but it is recommended if title is defined
Definition of the label that will be displayed on top of the Masked Text Field Element. Available from Symphony v20.8 and above.
rows
Number
No
Specify the number of rows (height) of the text area that will be displayed by default.
cols
Number
No
Specify the number of columns (width) of the text area that will be displayed by default.
<messageML>
<form id="form_id">
<h2>textareas</h2>
<textarea name="id1" >With initial value</textarea>
<textarea name="req" required="true" label="My label" title="My title\nWith second line" pattern="^[a-zA-Z]{3,3}$" pattern-error-message="My error message - must contain exactly 3 letters" placeholder="Required, with a placeholder, a regex, a label, and a tooltip"></textarea>
<button name="textarea">Submit</button>
</form>
</messageML>
Compliance Officers have access to the content of the masked text field.
noreq
) shows how a user can interact with a
non-required
field. Even if the field is empty (only a placeholder text is present but does not count as a value), it does not prevent the enduser from submitting the form.
The fourth masked text-field (req) shows the behaviour of the unique required field of the form, which cannot be submitted in case it is not filled; an error is displayed under the field in case the user submits the form with this empty field.
The fifth masked text-field (regex) shows the behaviour of the field when a regex pattern is entered. You can note that the pattern-error-message is displayed under the field if the input does not follow the pattern required by the bot developer.
The sixth masked text-field (min) shows how to force users to enter an input with a minimum number of characters, and how an error message is displayed under the field if the input does not respect the minlength required.
The seventh masked text-field (label) shows how a label text ("My Label") is displayed.
The eighth masked text-field (tooltip) shows how a title text ("My Tooltip/n With a second line") is inserted in the UI under the (i) icon, and how the text entered in the title parameter is displayed when the enduser clicks on the icon.
Attribute
Type
Required?
Description
name
String
Yes
Identifies the input content.
placeholder
String
No
Specifies a short hint that describes the expected value of the input field.
required
Boolean
No
If true, it specifies that the input field must be filled out before submitting the form. Accepted values; true and false.
masked
Boolean
Yes
In case you want to include a text field with masked characters [hidden by asterisk (*) symbols] , you must set maskedas true. If true, it creates a masked text field with hide/show options.
maxlength
Integer
No
The maxlength attribute allows you to specify a maximum number of characters that the user can input.
minlength
Integer
No
The minlength attribute allows you to specify a minimum number of characters that the user can input.
pattern
String
No
Regex String to match for input validation
pattern-error-message
String
No
Error message returned to user if pattern parameter matches user input
title
It accepts a simple text and \n for line breaks
No
The description that will be displayed when clicking the tooltip icon located on top of the Masked Text Field Element. Max length: 256 characters. Available from Symphony v20.8 and above.
label
String
Not required but it is recommended if title is defined
Definition of the label that will be displayed on top of the Masked Text Field Element. Available from Symphony v20.8 and above.
field. Even if nobody is selected by the user, it does not prevent the enduser from submitting the form.
The fourth person-selector (req) shows the behaviour of the unique required field of the form, which cannot be submitted in case nobody from the person selector is selected by the user; an error is displayed under the field in case the user submits the form with this empty field. An auto-filtering behaviour allows the user to see less options as he digits some input. Also, it shows how Symphony users can remove some of the selected users with the cross associated to that specific user.
The fifth person-selector (label) shows how a label text ("My Label") is displayed.
The sixth person-selector (tooltip) shows how a title text ("My Tooltip/n With a second line") is inserted in the UI under the (i) icon, and how the text entered in the title parameter is displayed when the enduser clicks on the icon.
Label
20.7
Since first version
Label displayed and form can still be submitted
Tooltip (title)
20.7
Since first version
Tooltip not displayed but form can still be submitted
Value
20.12
21.7
For client 1.5, it displays the person-selector as if there was no default value
Required?
Description
name
String
Yes
Identifies the person selector
placeholder
String
No
Specifies a short hint that describes the expected value of the input field.
required
Boolean
No
If true, it specifies that the person selector must be filled out before submitting the form, which means that at least one person must be "selected" Accepted values; true and false.
title
It accepts a simple text and \n for line breaks
No
The description that will be displayed when clicking the tooltip icon located on top of the Element. Max length: 256 characters.
label
String
Not required but it is recommended if title is defined
Definition of the label that will be displayed on top of the Masked Text Field Element.
value
Array of
long
No
Default value that will be preselected in the person-selector when the user receive the form from the bot.
Symphony Messaging 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 Messaging. 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 Messaging 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 Messaging Elements in your bot workflows continue onto our Available Elements that you can find in the subpages.
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 Messaging 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
Forms are represented by the <form> tag, as you can see in the examples 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.
To be considered valid, the form tag must contain at least one action type "Button" as a child. For more information, refer to .
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 the
The following example shows three forms being used as follows:
The first form (default) shows how Symphony Messaging 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.
Table Select
The Table Select is not an Element itself but an example of what can be achieved by using Elements with the Apache FreeMarker templates. This way, it is possible to build tables which contain a special column that allows users to select one or more rows, either with the Checkbox or the Button Element.
The following image shows three different tables. The first table shows the use of checkboxes to select rows, positioned to the right side of the table. The second example also shows checkboxes, but they are positioned to the left side. The last table shows buttons positioned to the right.
Building a Table Select with Apache FreeMarker
The following example shows how to create a Table Select structure using the FreeMarker template and a JSON file.
In the JSON data, you can configure the type of the Element that will be added to the Table Select and its position:
In this example, the table type is set as button and the position is set as left.
Note that the template is being used to create the messageML that is rendering the Table.
The table can be generated without header or footer.
If the table type is equal to "checkbox", then checkboxes will be added to the rows of the table.
A checkbox can also be added in the header. Please note, clicking the checkbox in the header will not check all rows' checkboxes.
Text Field
Symphony provides two types of elements for text input fields: are for a single-line input; and is for multi-line input.
Timezone Picker
Do you need users to pick a timezone as part of an interactive flow? With the Timezone Picker, Symphony users can easily select a timezone from a selection of possible values. It recognises both cities and countries so the user can quickly filter and find the right timezone.
The Timezone Picker is represented by the <timezone-picker> tag, as you can see in the examples at the bottom of the page.
You can see below the designs of the timezone picker.
For a list of all the available elements, refer to .
Bots can access the data, by reading the datafeed.
multi-submit
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.
action
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.
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.
<messageML>
<form id="default">
<text-field name="test"> This form becomes disabled once submitted</text-field>
<button name="default">Submit</button>
</form>
<hr/>
<form id="multi-submit-reset" multi-submit="reset">
<text-field name="test" label="Resets values to default"> This form can be submitted more than once</text-field>
<button name="multi-submit-reset">Submit</button>
</form>
<hr/>
<form id="multi-submit-no-reset" multi-submit="no-reset">
<text-field name="test" label="Keeps last submitted values"> This form can be submitted more than once</text-field>
<button name="multi-submit-no-reset">Submit</button>
</form>
</messageML>
Once the user has submitted the form, it becomes disabled. However, if the conversation is reloaded, the form resets and the user is able to send a new reply. If your workflow requires a single reply per user, please implement this control on the Bot side.
<messageML><formid="form_id"><h4>Personal Information</h4><text-fieldname="name"required="true"placeholder="Name"<text-fieldname="email"required="true"placeholder="email"<h4>Select your country</h4><selectname="country"><optionvalue="opt1">Australia</option><optionvalue="opt2">Brazil</option><optionvalue="opt3">China</option><optionvalue="opt4">Denmark</option><optionvalue="opt5">Ecuador</option><optionvalue="opt6">France</option><optionvalue="opt7">Germany</option><optionvalue="opt8">Italy</option><optionvalue="opt9">Japan</option></select><h4>Choose your option</h4><radioname="example_radio"value="option_01"checked="true"<radioname="example_radio"value="option_02">Unmarked</radio><h4>Choose your option</h4><checkboxname="checkbox_1"value="value01"checked="true"<checkboxname="checkbox_2"value="value02">Unchecked</checkbox><h4>Send a comment</h4><textareaname="comment"placeholder="Add your comment here"required="true"<buttontype="reset">Reset</button><buttonname="submit_button"type="action">Submit</button></form></messageML>
1.55
position
String
Yes
This attribute indicates how the buttons and checkboxes must be aligned inside the column. Accepted values: left or right. For more information, refer to the JSON example below.
If the table type is equal to "button", then buttons will be added to select a specific row of the table.
When creating a MessageML using a Freemarker template, you must send a JSON file with it.
Attribute
Type
Required?
Description
type
String
Yes
The typeattribute determines if a table will display a special column with Buttons or Checkboxes within it. Note that a table can have only one of the two possible types, being button or checkbox. For more information, see the Example below.
Specifies a short hint that describes the expected value of the input field.
required
Boolean
Optional
If true, it specifies that the input field must be filled out before submitting the form.
masked
Boolean
Optional
If true, it creates a masked text field with hide/show options when its value is "true". For more information, refer to .
maxlength
Integer
Optional
The maxlength attribute allows you to specify a maximum number of characters that the user can input.
minlength
Integer
Optional
The minlength attribute allows you to specify a minimum number of characters that the user can input.
pattern
String
Optional
Regex String to match for input validation. For more information, refer to .
pattern-error-message
String
Optional but if pattern is defined, the pattern-error-message attribute is mandatory.
Error message returned to user if pattern parameter matches user input
title
It accepts a simple text and \n for line breaks
Optional
The description that will be displayed when clicking the tooltip icon located on top of the Text Field Element. Max length: 256 characters. Available from Symphony v20.8 and above.
label
String
Not required but it is recommended if title is defined
Definition of the label that will be displayed on top of the Text Field Element. Available from Symphony v20.8 and above.
auto-submit
Boolean
Optional.
Default false.
When enabled, typing <enter> key in the field will submit the form.
formnovalidate
Boolean
Optional.
Default false.
Only valid when auto-submit is true.
When set to true, this submit field bypasses the form validation (required fields and regular expressions), meaning that the user can submit this field even if the form validation is in error.
With Symphony v20.6, bot developers can use Regex to validate text fields and text areas using the pattern and pattern-error-message attributes.
For more information and examples, refer to Regular Expressions - Regex.
The text field has a max number of 128 characters. For larger texts, use Text Area.
The text field cannot have children tags but it can have a default text (initial value) between the <text-field></text-field> tags. See Examples below for more details.
Text fields are grouped at a max of 4 per row, depending on the screen size. For more information, refer to .
You can add a default text in your text field by including it between the <text-field></text-field> tags. Note that unlike the placeholder text, the default text will be sent with the form if not edited by the user.
Input Validation - Pattern: the max length for all attributes is set to 256.
The following examples show text fields being used as follows:
The first text-field (init) shows how to display a default text ("With initial value"). Note that the default text would have been sent to the payload if it had not been deleted before submitting the form.
The second text-field (placeholder) shows how a placeholder text ("Only Placeholder") is displayed in the UI. Please note the placeholder text is not sent in the payload if no text has been entered in the field by the enduser.
The third text-field (noreq) shows how a user can interact with a non-required field. Even if the field is empty (only a placeholder text is present but does not count as a value), it does not prevent the enduser from submitting the form.
The fourth text-field (req) shows the behaviour of the unique required field of the form, which cannot be submitted in case it is not filled; an error is displayed under the field in case the user submits the form with this empty field.
The fifth text-field (regex) shows the behaviour of the field when a regex pattern is entered. You can note that the pattern-error-message is displayed under the field if the input does not follow the pattern required by the bot developer.
The sixth text-field (min) shows how to force users to enter an input with a minimum number of characters, and how an error message is displayed under the field if the input does not respect the minlength required.
The seventh text-field (label) shows how a label text ("My Label") is displayed.
The eighth text-field (tooltip) shows how a title text ("My Tooltip/n With a second line") is inserted in the UI under the (i) icon, and how the text entered in the title parameter is displayed when the enduser clicks on the icon.
Please note that several text-fields are aligned next to another. Note also that this behaviour is reactive to the screen size, the number of text-fields on the same line decreasing until one per row, as the screen gets smaller (see in the example below).
Timezone displayed by default when the user receives or resets the form.
Please note that if it is not defined by the developer, the value will be based on the user's browser setting. You need to enter value="" to enforce the timezone to be empty.
title
String (accepting \n for line break)
No
The description that will be displayed when clicking the tooltip icon located on top of the timezone picker Element.
label
String
Not required but it is recommended if title is defined
Definition of the label that will be displayed on top of the timezone picker Element.
required
Boolean (true or false)
No
If true, it specifies that a timezone must be picked by the user before submitting the form.
placeholder
String
No
Specifies a short hint in the timezone picker input.
Accepts any string value but is overridden by the value if a value is defined: it will show only if value attribute is enforced to empty.
Please note that a default placeholder is displayed as: "Choose a timezone".
disabled-timezone
Array of Strings
No
Items can be disabled from the timezone picker list so that the user cannot pick them.
See the examples below for more details.
Important: single quote ' should wrap the array of strings
Please note that if you want to propose only a list of a few timezones to the users, then a simplemight be more adequate.
For the purpose of accessibility, Symphony users can interact with the timezone picker via their keyboard:
First, using "Tab" to enter the component
Using "Enter", "Arrow-up", or "Arrow-down" to open the timezone list
Using "Arrow-up" and "Arrow-down" to navigate in the list
Using any key to erase the field and write in it
Using "Enter" to set the selected timezone and close the list
Using "Escape" to keep pre-selected value and close the list
Finally using "Tab" to exit the component
The max length of any timezone picker attribute is 256 characters except disabled-timezone attribute which max length is set to 1024 characters.
All timezone values are displayed in English only.
You can add a default timezone in your text field by including it in the value parameter. Please note that unlike the placeholder text, the default timezone will be sent in the formReply when the form is submitted if not edited by the user.
Please note that if the default timezone (value attribute) matches a value from the disabled-timezone array, then the value is left empty.
The timezone-picker will be supported on the following versions of clients:
20.14 for Client 2.0
20.13 for Client 1.5 (a beta version is released in Client 20.12 for Client 1.5)
The following examples show the timezone picker being used as follows:
The first timezone-picker (init) shows how to display an empty timezone-picker ("With empty default value"). Note in the messageML sent the value was enforced to empty with value="".
The second timezone-picker (specific_value) shows how to display, by default, a value specifically chosen by the developer. Note that the default value would have been sent to the payload if it had not been deleted before submitting the form. You can see how users can remove a pre-selected value from the timezone-picker, thanks to the cross on the right side of the input.
The third timezone-picker (default_value) shows how to display, by default, the user browser timezone value. Note that the default value is sent to the payload when submitting the form.
The fourth timezone-picker (placeholder) shows how a placeholder text ("Only Placeholder") is displayed in the timezone-picker. Please note the placeholder text is not sent in the payload if no value has been chosen by the enduser.
The fifth timezone-picker (label) shows how a label text ("My Label") is displayed.
The sixth timezone-picker (tooltip) shows how a title text ("My Tooltip/n With a second line") is inserted in the UI under the (i) icon, and how the text entered in the title parameter is displayed when the enduser clicks on the icon.
The seventh timezone-picker (noreq) shows how a user can interact with a non-required field. Even if the field is empty (only a placeholder text is present but does not count as a value), it does not prevent the user from submitting the form.
The eighth timezone-picker (req) shows the behavior of the unique required field of the form, which cannot be submitted in case it is not filled; an error is displayed under the field in case the user submits the form with this field as empty.
The ninth timezone-picker (disabled) shows how users interact with disabled values from the timezone-picker.
<messageML>
<form id="form_id">
<h2>timezone-pickers</h2>
<timezone-picker name="init" value="" label="With empty default value" />
<timezone-picker name="specific_value" value="America/Fortaleza" label="With specific default value" />
<timezone-picker name="default_value" label="With default value from the user browser"/>
<timezone-picker name="placeholder" placeholder="Only Placeholder..." value="" />
<timezone-picker name="label" label="My Label" />
<timezone-picker name="tooltip" label="With Tooltip" title="My Tooltip\n With a second line" />
<timezone-picker name="noreq" placeholder="Not required" value="" />
<timezone-picker name="req" required="true" placeholder="Required" value="" />
<timezone-picker name="disabled" label="With Disabled values" value="America/Indiana/Vincennes" disabled-timezone='["America/Detroit", "America/Indiana/Marengo", "America/Indiana/Petersburg"]' />
<button name="timezone-picker">Submit</button>
</form>
</messageML>
The possible values of the timezone-picker are restricted to the Canonical values of the tz database.
Please note in the examples above that the values are displayed to users according to the following rules:
The country name only is displayed if it has a single timezone (see Israel)
A list of cities are displayed under their country title if this country has multiple timezones (see United States of America)
MessageML tag
Designs
Attributes
Timezone Picker designs
Accessibility
Rules and Limitations
When the value attribute is not defined by the developer, please note that the default value will be based on the user's browser setting.
If you want however to force the default value to be displayed as empty for the user when sending the form, please enforce value="" in the messageML.
Examples
Versions and Compatibility
Annex: list of timezone values
Elements
Date Picker
Do you need users to pick a date as part of an interactive flow? With the Date Picker element, Symphony users can easily select a date from a calendar-style UI component.
The Date Picker offers to Symphony users the possibility to enter the date in two different ways:
Populating the field directly with the keyboard, following the appropriate format
Clicking on the wished day from the calendar UI in a monthly display
MessageML tag
The Date Picker is represented by the <date-picker> tag, as you can see in the examples at the bottom of the page.
You can see below the designs of the date picker.
The main points to be highlighted are the following:
A dot is displayed under the today date
A disabled date is displayed in grey and stroke through
An highlighted date is displayed in blue
For a list of all the available elements, refer to .
For the purpose of accessibility, Symphony users can interact with the calendar UI with their keyboard:
Using "Enter" to open/close the calendar UI
Then using "Tab" to navigate in the different functionalities of the calendar: day selection; then "today" button; then "previous year" button; then "previous month" button; then "next month" button; then "next year" button; and finally going back to the day selection panel
Once in the day selection area, using the arrows from the keyboard allows navigating in the month to select the right day
In the day selection area, some more keyboard controls are available in the date picker:
"Home" key: Moves focus to the first day (e.g. Sunday) of the current week
"End" key: Moves focus to the last day (e.g. Saturday) of the current week
"Page Up" key: Moves to the previous month, with focus on the same day of the same week (or either previous or next week if it does not exist)
The max length of any date picker attribute is 256 except disabled-date and highlighted-date attributes which max length is set to 1024 characters.
The date picker is displayed differently to the end user depending on the language chosen in the settings specific of each user. Please note that if a format is specified, then the format overrides the default format chosen based on the settings.
The following examples show the date picker being used as follows:
The first date-picker (init) shows how to display a default date, as an initial value is entered as parameter. Note that the default text will be sent to the payload given that it was not deleted before submitting the form.
The second date-picker (placeholder) shows how a placeholder is displayed in the UI. Please note that any text is accepted as input. However, if you compare with the next date-pickers present in the form, you can notice that a default placeholder is generated (with a hint of the correct format to accepted by the date-picker field) in case no placeholder is mentioned in parameter.
Time Picker
Do you need users to pick a time as part of an interactive flow? With the Time Picker element, Symphony users can easily select a time from a list of possible values.
The Time Picker offers to Symphony users the possibility to enter the time in two different ways:
Populating the field directly with the keyboard, following the appropriate format and the list of possible values (see attributes strict, min, max, and disabled-time)
Clicking on the wished time from the dropdown displayed
MessageML tag
The Time Picker is represented by the <time-picker> tag, as you can see in the examples at the bottom of the page.
You can see below the designs of the time picker.
For the purpose of accessibility, Symphony users can interact with the time picker via their keyboard:
First, using "Tab" to enter the component
Using "Enter" or "Space" to open the dropdown when focus is on the icon, or just "Enter" when focus is on the input
Using "Arrow up" or "Arrow down" to navigate within the dropdown list and using "Enter" to select the preselected value
The max length of any time picker attribute is 256 except disabled-time attribute which max length is set to 1024 characters.
If the format entered by the user is not correct or if the time entered is a disabled time, then an error message is displayed to the user. Note that it is not possible for the user to submit the form with an invalid format or disabled time.
You can add a default time
The following examples show the time picker being used as follows:
The first time-picker (init) shows how to display a default time, as an initial value is entered as parameter. Note that the default value is present in the user reply as it has not been deleted before submitting the form.
The second time-picker (placeholder) shows how a placeholder is displayed in the UI. Please note that any text is accepted as input. However, if you compare with the next time-pickers present in the form, you can notice that a default placeholder is generated (with a hint of the correct format to accepted by the time-picker field) in case no placeholder is set.
Dropdown Menu
Allows the user to select an option among a static list of items.
The dropdown menu is represented as a set <options> items nested into a <select> tag.
Each <option> element have a value attribute containing the data value to submit in the form when that option is selected; You can also include a selected attribute on an <option> element to make it selected by default when the page first loads.
Attributes
The <select> tag:
Select tags only accept <option> tags as children. The <select> tag must contain at least one <option> tag.
By default, a user can select only one option from the dropdown menu. However, using the attribute multiple set to true together with min and max attributes, users will be able to select several options from the dropdown. Please see below the examples to know how to use these attributes.
The <option> tag:
The <option> tag contains a required text node, which specifies the text that will be displayed for that option inside the dropdown menu.
The only valid attributes of the <option> tag are value and selected.
If neither the selected or data-placeholder attributes are set, the default text (title) of the dropdown menu will be "Dropdown".
The following examples show dropdown menus being used as follows:
The first dropdown (init) shows how to display a default preselected option ("opt2": "With selected option"). Note that the preselected option is sent to the payload when submitting the form.
The second dropdown (data-placeholder) shows how a placeholder text ("Only data-placeholder") is displayed in the UI. Please note the placeholder text is not sent in the payload if no option from the dropdown menu has been selected by the enduser.
The third dropdown (
Features introduced
Agent needed to parse message sent by the bot
Client 2.0 release
Mobile
Dialog
Chat bots can embed dialog buttons in chat messages. When the dialog button is clicked, a dialog opens and displays the content that has been predefined.
This can be useful to make long messages much more concise, or progressively disclose a form only if it is relevant to the user for example.
The Dialog component is structured in two sections:
<ui-action action='open-dialog'> tag. This tag defines where and how the will be displayed, and it references the dialog that will open using the target-id attribute;
/>
/>
>
Marked
</
radio
>
>
Checked
</
checkbox
>
/
>
value
String "yyy-MM-dd"
No
Date with ISO_8601 format to be displayed by default by the date picker when rendered for the Symphony user.
Overrides the placeholder value.
title
String (accepting \n for line break)
No
The description that will be displayed when clicking the tooltip icon located on top of the date picker Element.
label
String
Not required but it is recommend if title is defined
Definition of the label that will be displayed on top of the date picker Element.
required
Boolean (true or false)
No
If true, it specifies that a date must be picked before submitting the form.
placeholder
String
No
Specifies a short hint that describes the expected format of the date picker.
Accepts any string value but is overridden by the value if a value is entered.
If not set, the accepted format will be displayed.
Note: be careful as adding a placeholder might bring confusion to the end user. Therefore we recommend to use the default one as much as possible, to use the label if context is needed, or the title if instructions are needed.
min
String "yyy-MM-dd"
No
Specifies the earliest acceptable date with ISO_8601 format.
max
String "yyy-MM-dd"
No
Specifies the latest acceptable date with ISO_8601 format.
disabled-date
Json array (in a String format)
No
Dates or ranges of dates that cannot be selected by the Symphony user.
Maximum length of 1024 characters.
There are 3 different patterns:
1. range of date: {"from": "yyyy-MM-dd", "to": "yyyy-MM-dd"},
2. date: {"day": "yyyy-MM-dd"},
3. recurring day in the week: {"daysOfWeek": [0, 1, 6]},
Important: single quote ' should wrap the xml parameter. See the examples below for more details.
Note: for the daysOfWeek: 0 always corresponds to Sunday, 6 to Saturday.
See the examples below for more details.
highlighted-date
Json array (in a String format)
No
Dates or ranges of dates that are highlighted to the Symphony user.
Maximum length of 1024 characters.
There are 3 different patterns:
1. range of date: {"from": "yyyy-MM-dd", "to": "yyyy-MM-dd"},
2. date: {"day": "yyyy-MM-dd"},
3. recurring day in the week: {"daysOfWeek": [0, 1, 6]},
Important: single quote ' should wrap the xml parameter. See the examples below for more details.
Note: for the daysOfWeek: 0 always corresponds to Sunday, 6 to Saturday.
See the examples below for more details.
format
String
No
Format in which the date will be displayed to or should be entered by the Symphony user.
Only accepts the letters 'y', 'M', and 'd'.
• 'd' defines the day of the month. It can be either 'd' or 'dd' to define the minimum of digits displayed (i.e. corresponding to "3" or "03" for the third day)
• 'M' defines the month. Use one or two ('M' or 'MM') for the numerical month; three 'MMM' for the abbreviation (i.e. "Sep"); four 'MMMM' for the full name (i.e. "September"); or five 'MMMMM' for the narrow name (i.e. "S")
• 'y' defines the year. Use n of it to define n minimum of digits displayed (i.e. use 'yyyyy' to display the year 2020 as 02020)
Note: be careful as many combinations may be possible, may have a weird display for the Symphony user, and are not restricted in the messageML. Therefore, we strongly recommend to use the default value as much as possible.Note 2: The format only impacts what the end user will see. It does not affect how you have to specify the value, disabled-date, highlighted-date, or the format of the response.
Finally, using "Enter" allows to close the panel with the day selected or to trigger one of the functionalities selected (buttons)
"Page Down" key: Moves to the next month, with focus on the same day of the same week (or either previous or next week if it does not exist)
"Shift" + "Page Up" key: Moves to the previous year, with focus on the same day of the same week (or either previous or next week if it does not exist)
"Shift" + "Page Down" key: Moves to the next year, with focus on the same day of the same week (or either previous or next week if it does not exist)
English: the calendar-UI is in English, the weeks start on Sunday, the default format is MM-dd-yyyy, and the date picker accepts value to be entered with the keyboard in English only (i.e. August)
French: the calendar-UI is in French, the weeks start on Monday, the default format is dd/MM/yyyy, and the date picker accepts value to be entered with the keyboard in French only (i.e. Août)
Japanese: the calendar-UI is in Japanese, the weeks start on Monday, the default format is yyyy日MM月dd年, and the date picker accepts value to be entered with the keyboard in Japanese only
If the user enters the value of a valid day and month combination with his keyboard, then the current year is preselected. If he continues entering another year, then this last one will be selected.
If the format entered by the user is not correct or if the date entered is a disabled date, then an error message is displayed to the user. Note that it is not possible for the user to submit the form with an invalid format or disabled date.
You can add a default date in your text field by including it in the value parameter. Please note that unlike the placeholder text, the default date will be sent in the formReply when the form is submitted if not edited by the user.
The third date-picker (label) shows how a label is displayed. In the GIF below, it shows also the interaction with the form when the user directly writes an input with an incorrect format: an error message is displayed and the form cannot be sent.
The fourth date-picker (tooltip) shows how the title attribute is displayed. Note that when a user enters the month and the date in the correct format, the current year is automatically preselected. It can be modified if the user continues writing the year in the input field.
The fifth date-picker (req) shows the behaviour of the unique required field of the form, which cannot be submitted in case it is not filled. Also note the use of the "today" button.
The sixth date-picker (format) shows the way the placeholder evolves to adapt to a new format transmitted thanks to the format parameter. Also please note the accessible interaction with the date-picker via the keyboard.
The seventh date-picker (rules) shows how to interact with the following parameters: min, max, disabled, and highlighted. Please note that a disabled date cannot be entered manually.
Not working: date-picker is not displayed but the form can be sent
Designs
Attributes
Accessibility
Rules and Limitations
Date as disabled and highlighted
Note that currently, if a date is entered in the disabled and highlighted parameters at the same time, it cannot be selected via the calendar UI first. However, it can be enabled if the user enters this particular date manually. This behaviour will be fixed in the next versions and the date will then be considered as disabled and displayed as such.
Examples
Versions and Compatibility
Date Picker designs
Elements
value
String "HH:mm:ss"
No
Time with ISO_8601 format to be displayed by default by the time picker when rendered for the Symphony user.
Overrides the placeholder value.
title
String (accepting \n for line break)
No
Description that will be displayed when clicking the tooltip icon located on top of the time picker Element.
label
String
Not required but it is recommended if title is defined
The text of the label that will be displayed above the time picker field.
required
Boolean (true or false)
No
If true, it specifies that a time must be picked before submitting the form.
placeholder
String
No
Specifies a short hint that describes the expected format of the time picker field.
If the attributevalue is entered, the placeholder will not be displayed.
If the placeholder is not set, the accepted time format will be displayed by default.
Note: We recommend to use the default placeholder. It is better to rely on the label if context is needed, or the title if instructions are needed.
min
String "HH:mm:ss"
No
Specifies the earliest acceptable time with ISO_8601 format.
Note: Times earlier than the min are not displayed in the time picker.
max
String "HH:mm:ss"
No
Specifies the latest acceptable time with ISO_8601 format.
Note: Times later than the max are not displayed in the time picker.
disabled-time
Json array (in a String format)
No
Times or ranges of times that cannot be selected by the Symphony user.
Maximum length of 1024 characters.
There are 2 different patterns:
1. range of times: {"from": "HH:mm:ss", "to": "HH:mm:ss"},
2. specific time: {"time": "HH:mm:ss"}.
Important: single quote ' should wrap the xml parameter. See the examples below for more details.
Note: Disabled times are displayed as disabled values in the time picker.
format
String
No
Format in which the time will be displayed to or should be entered by the Symphony user.
Only accepts the letters 'h', 'H', 'm', 's', and 'a' as well as ':' or space as separator.
• 'h' (for 12-hour format) and 'H' (for 24-hour format) define the hour. You can use either 1 ('h'; 'H') or 2 ('hh'; 'HH') to define the minimum number of digits displayed (i.e. corresponding to "3" or "03" for the third hour)
• 'm' defines the minutes. Similarly to the hours, you can use one or two ('m' or 'mm')
• 's' defines the seconds. Similarly to the hours and minutes, you can use one or two ('s' or 'ss')
• 'a' (usually placed after a space) allows to display 'AM' for morning times and 'PM' for afternoon times
Note 1: We recommend the use of the default value as much as possible.Note 2: The format only impacts what the end user will see. It does not affect how you have to specify the value, min, max, disabled-time, or the format of the user reply.
step
Number
No
Default is 900 (corresponding to15 min)
The stepping interval (in seconds) for the times displayed in the dropdown menu.
Min value: 600 (corresponding to 10 min)
Max value: 43 200 (corresponding to half a day)
strict
Boolean
No
Default is false
Enforce that the user cannot select a time that is not in the proposed list (e.g. we want him to only select an hour, he can’t decide to set the field to 9:15, even with the keyboard).
Please note that in addition to this, the value picked will be validated against attributes min, max, and disabled-time.
Either "Typing" or pressing "Tab" to go from the hours to the minutes, and then from the minutes to the seconds
Either "Deleting" or pressing "Shift+Tab" to go back from the seconds to the minutes, and then from the minutes to the hours
Finally using "Tab" to exit the component
in your text field by including it in the
value
parameter. Please note that unlike the
placeholder
text, the
default time
will be sent back to the Bot in the user reply when the form is submitted if it is not edited by the user.
The time-picker will be supported on the following versions of clients:
20.14 for Client 2.0
20.13 for Client 1.5
The third time-picker (label) shows how a label ("My Label") is displayed.
The fourth time-picker (tooltip) shows how the title attribute ("My Tooltip/n With a second line") is displayed.
The fifth time-picker (noreq) shows how a user can interact with a non-required field. Even if the field is empty (only a placeholder text is present but does not count as a value), it does not prevent the user from submitting the form.
The sixth time-picker (req) shows the behaviour of the unique required field of the form, which cannot be submitted in case it is not filled.
The seventh time-picker (format) shows the way the placeholder evolves to adapt to a new format transmitted thanks to the format parameter. Also please note the accessible interaction with the time-picker via the keyboard.
The eighth time-picker (step) shows how to modify the step between 2 consecutive values in the list of times. Please note that a Symphony user can select any other existing time by populating the field with his keyboard.
The ninth time-picker (strict_step) shows how to enforce the user to choose among the non-disabled values displayed in the dropdown, thanks to the strict attribute.
The tenth time-picker (rules) shows how to interact with the following parameters: min, max, and disabled-time. Please note that a disabled time cannot be entered manually.
Please note that a limited amount of values are displayed in the dropdown of the time picker (see attribute step which minimum is 10 min). However, you can note that the time picker supports a precision to the second (see format attribute). Also, if you don't use the attribute strict, then user will be able to populate the field via their keyboard with any other non-disabled and existing time value than proposed in the list.
Examples
Versions and Compatibility
Time Picker designs
Boolean
Optional
Optional attribute of the <select> tag. it is a Boolean attribute indicating that an option with a non-empty string value must be selected.
value
String
Yes
Required attribute of the <option> tag. It contains the data value to submit to the server when that option is selected.
selected
Boolean
Optional
You can include a selected attribute on an <option> element to make it selected by default when the page first loads. Accepted values: true and false.
data-placeholder
String
Optional
Text displayed in the dropdown menu before an option is selected. It can be a short hint or a title for the dropdown menu.
title
It accepts a simple text and \n for line breaks
Optional
The description that will be displayed when clicking the tooltip icon located on top of the Masked Text Field Element. Max length: 256 characters.
label
String
Not required but it is recommended if title is defined
Definition of the label that will be displayed on top of the Masked Text Field Element.
multiple
String
Boolean
Optional
Default is false
Allows users to select multiple values and the developer to send dropdown with multiple preselected options.
min
String
Integer ≥ 2 and ≤ max attribute
Optional
Can be used only if multiple attribute is set to true
Minimum number of options to be selected by the Symphony user.
NB: If undefined, no minimum option needs to be selected. Please use required attribute if you want to set min to 1.
max
String
Integer ≥ 2
Optional
Can be used only if multiple attribute is set to true
Maximum number of options to be selected by the Symphony user.
NB: If undefined, user will be able to select as many options as wished. Please use multiple attribute set to false if you want to set max to 1.
auto-submit
Boolean
Optional
Default is false
When enabled, selecting a value will submit the form.
formnovalidate
Boolean
Optional
Default is false
Only valid when auto-submit is true.
When set to true, this submit menu bypasses the form validation (required fields and regular expressions), meaning that the user can submit using this drop down menu even if the form validation is in error.
Only one <option> of a given select can have the attribute selected as true.
noreq
) shows how a user can interact with a
non-required
field. Even no option is selected by the user, it does not prevent the enduser from submitting the form.
The fourth dropdown (req) shows the behaviour of the unique required field of the form, which cannot be submitted in case no option from the dropdown menu is selected by the user; an error is displayed under the field in case the user submits the form with this empty field.
The fifth dropdown (label) shows how a label text ("My Label") is displayed.
The sixth dropdown (tooltip) shows how a title text ("My Tooltip/n With a second line") is inserted in the UI under the (i) icon, and how the text entered in the title parameter is displayed when the enduser clicks on the icon.
The seventh dropdown (multiple) shows how to combine multiple attribute with min/max rules to guide users selecting between 3 and 5 options.
20.6
Since first version
Since first version
Tooltip (title)
20.7
Since first version
Since first version
Multiple (with min and max) attributes
20.14
21.12
Since first version
auto-submit
23.11
23.12
Not supported yet.
formnovalidate
25.6
25.9
Not supported yet.
Attribute
Type
Required?
Description
name
String
Yes
Required attribute of the <select> tag. It identifies the dropdown menu.
When designing forms with dropdown menus that include a very large number of options you may hit the characters limit of a Symphony message. For more information about message size limits, refer to .
Examples
Versions
required
Label
<dialog> tag that defines the content of the dialog that will be displayed when the button is clicked.
The <ui-action> tag wraps a single <button> children tag. The button tag supports the usual styles (primary, secondary, tertiary). Examples are available at the bottom of this page.
The <ui-action> tag supports the following attributes:
Attribute
Type
Required?
Description
action
String
Yes
For Dialogs, always set to action='open-dialog'.
Each <dialog> is split in three areas (children tags):
<title> - mandatory: specifies the title of the dialog and is always displayed at the top of it in a fixed and non scrollable position.
<body> - mandatory: specifies the content of the dialog that is displayed in the middle of it and can be scrollable when the content is too big to be contained in the view height.
<footer> - optional: specifies the footer of the dialog and is always displayed at the bottom in a fixed and non scrollable position.
The <dialog> tag supports the following attributes
Attribute
Type
Required?
Description
id
String
Yes
Id of the dialog that will be triggered thanks to the ui-action it is associated to. See target-id attribute in <ui-action> tag.
The following gif shows an example that contains two dialogs:
The first dialog is embedded in a form. You will notice that the button used to trigger the dialog is positioned where the <ui-action> tag is coded.
As soon as the associated <dialog> is at its same nesting level, it can be placed anywhere before or after the ui-action.
You can also notice that users can interact with the form as well as submit it.
However, the dialog only contains text as it cannot contain any interactive Form Elements. Please note that a cancel button can be included in the dialog as it is not considered as an interactive Form Element: you can use it to offer another option for the user to close the dialog.
Please note the scrolling behaviour of the body whereas both title and footer are placed in a fixed position.
The second dialog embeds a form instead.
After having started to fill-in the form, if the user closes the dialog and opens it back, the values of the fields will not reset to their original values, as long as the user does not refresh the page.
Also, when submitting a form that is in a dialog, the dialog will automatically close after a certain delay. If the user opens back the dialog without refreshing the page, then the values of the form and its state are persisted.
<messageML>
<form id="wrapping_dialog">
<h4>First part: form wrapping a dialog</h4>
<p>Here is the beginning of the form containing the dialog hiding some large text</p>
<text-field name="input1" label="This is an interactive Element in the form but outside of the dialog" />
<p>Please click on the following button in order to open the dialog and see the hidden information</p>
<ui-action action="open-dialog" target-id="dialog_in_form">
<button class="secondary">Open the dialog contained in the form</button>
</ui-action>
<text-field name="input2" label="This is an interactive Element in the form but outside of the dialog" />
<button name="wrapping_dialog">Submit Button of the Form</button>
<dialog id="dialog_in_form">
<title>
This is a title
</title>
<body>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam congue viverra interdum. Integer quam odio, gravida ultricies pharetra ac, tempor eget leo. Duis vitae arcu sed turpis faucibus feugiat a at ipsum. Nulla facilisi. Phasellus egestas, leo et malesuada porttitor, felis turpis viverra tortor, quis suscipit orci nibh at augue. Curabitur erat libero, accumsan vitae ipsum eleifend, tincidunt bibendum purus. Curabitur ultricies lorem tincidunt rutrum viverra. Sed mattis dui at suscipit auctor. In rutrum neque urna, vitae lacinia turpis blandit eget. Nullam eu dignissim purus. Sed ut ante lorem. Duis quis mi nec enim imperdiet consectetur. Phasellus aliquet accumsan ipsum non ullamcorper.<br/><br/>
Praesent convallis odio tortor, sit amet vulputate nulla tincidunt vitae. Donec ultrices eros suscipit mauris condimentum iaculis. Ut posuere finibus quam a consequat. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Nam aliquet dapibus vehicula. Nunc vel lectus congue, finibus felis ut, laoreet est. Maecenas eleifend gravida metus, nec viverra mi egestas eu. Pellentesque scelerisque mattis nibh, eu condimentum nulla finibus ut.<br/><br/>
Ut dignissim varius libero ac volutpat. Sed hendrerit nec libero ut ullamcorper. Nunc et risus sed purus luctus faucibus nec eu est. Praesent id justo ante. Sed sed enim velit. Ut ac mauris magna. Fusce bibendum ullamcorper diam quis semper. Aenean mattis auctor ultricies. Mauris dui enim, vehicula sit amet finibus non, consectetur eu ante. Fusce at mi a ipsum gravida rhoncus.<br/><br/>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam congue viverra interdum. Integer quam odio, gravida ultricies pharetra ac, tempor eget leo. Duis vitae arcu sed turpis faucibus feugiat a at ipsum. Nulla facilisi. Phasellus egestas, leo et malesuada porttitor, felis turpis viverra tortor, quis suscipit orci nibh at augue. Curabitur erat libero, accumsan vitae ipsum eleifend, tincidunt bibendum purus. Curabitur ultricies lorem tincidunt rutrum viverra. Sed mattis dui at suscipit auctor. In rutrum neque urna, vitae lacinia turpis blandit eget. Nullam eu dignissim purus. Sed ut ante lorem. Duis quis mi nec enim imperdiet consectetur. Phasellus aliquet accumsan ipsum non ullamcorper.<br/><br/>
Praesent convallis odio tortor, sit amet vulputate nulla tincidunt vitae. Donec ultrices eros suscipit mauris condimentum iaculis. Ut posuere finibus quam a consequat. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Nam aliquet dapibus vehicula. Nunc vel lectus congue, finibus felis ut, laoreet est. Maecenas eleifend gravida metus, nec viverra mi egestas eu. Pellentesque scelerisque mattis nibh, eu condimentum nulla finibus ut.<br/><br/>
Ut dignissim varius libero ac volutpat. Sed hendrerit nec libero ut ullamcorper. Nunc et risus sed purus luctus faucibus nec eu est. Praesent id justo ante. Sed sed enim velit. Ut ac mauris magna. Fusce bibendum ullamcorper diam quis semper. Aenean mattis auctor ultricies. Mauris dui enim, vehicula sit amet finibus non, consectetur eu ante. Fusce at mi a ipsum gravida rhoncus.
</body>
<footer>
This is a footer
<button name="cancel1" type="cancel">Close</button>
</footer>
</dialog>
</form>
<br/>
<br/>
<h4>Second part: message with a dialog hiding a form</h4>
<p>Here is the beginning of the message containing the dialog hiding some large form</p>
<dialog id="dialog_containing_form" width="large">
<form id="wrapped_in_dialog">
<title>
This is a title
</title>
<body>
<text-field name="input3" label="This is an interactive Element in the form which is contained in the dialog" />
<textarea name="textarea" label="Other interactive Element in the dialog" />
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam congue viverra interdum. Integer quam odio, gravida ultricies pharetra ac, tempor eget leo. Duis vitae arcu sed turpis faucibus feugiat a at ipsum. Nulla facilisi. Phasellus egestas, leo et malesuada porttitor, felis turpis viverra tortor, quis suscipit orci nibh at augue. Curabitur erat libero, accumsan vitae ipsum eleifend, tincidunt bibendum purus. Curabitur ultricies lorem tincidunt rutrum viverra. Sed mattis dui at suscipit auctor. In rutrum neque urna, vitae lacinia turpis blandit eget. Nullam eu dignissim purus. Sed ut ante lorem. Duis quis mi nec enim imperdiet consectetur. Phasellus aliquet accumsan ipsum non ullamcorper.<br/><br/>
Praesent convallis odio tortor, sit amet vulputate nulla tincidunt vitae. Donec ultrices eros suscipit mauris condimentum iaculis. Ut posuere finibus quam a consequat. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Nam aliquet dapibus vehicula. Nunc vel lectus congue, finibus felis ut, laoreet est. Maecenas eleifend gravida metus, nec viverra mi egestas eu. Pellentesque scelerisque mattis nibh, eu condimentum nulla finibus ut.<br/><br/>
Ut dignissim varius libero ac volutpat. Sed hendrerit nec libero ut ullamcorper. Nunc et risus sed purus luctus faucibus nec eu est. Praesent id justo ante. Sed sed enim velit. Ut ac mauris magna. Fusce bibendum ullamcorper diam quis semper. Aenean mattis auctor ultricies. Mauris dui enim, vehicula sit amet finibus non, consectetur eu ante. Fusce at mi a ipsum gravida rhoncus.<br/><br/>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam congue viverra interdum. Integer quam odio, gravida ultricies pharetra ac, tempor eget leo. Duis vitae arcu sed turpis faucibus feugiat a at ipsum. Nulla facilisi. Phasellus egestas, leo et malesuada porttitor, felis turpis viverra tortor, quis suscipit orci nibh at augue. Curabitur erat libero, accumsan vitae ipsum eleifend, tincidunt bibendum purus. Curabitur ultricies lorem tincidunt rutrum viverra. Sed mattis dui at suscipit auctor. In rutrum neque urna, vitae lacinia turpis blandit eget. Nullam eu dignissim purus. Sed ut ante lorem. Duis quis mi nec enim imperdiet consectetur. Phasellus aliquet accumsan ipsum non ullamcorper.<br/><br/>
Praesent convallis odio tortor, sit amet vulputate nulla tincidunt vitae. Donec ultrices eros suscipit mauris condimentum iaculis. Ut posuere finibus quam a consequat. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Nam aliquet dapibus vehicula. Nunc vel lectus congue, finibus felis ut, laoreet est. Maecenas eleifend gravida metus, nec viverra mi egestas eu. Pellentesque scelerisque mattis nibh, eu condimentum nulla finibus ut.<br/><br/>
Ut dignissim varius libero ac volutpat. Sed hendrerit nec libero ut ullamcorper. Nunc et risus sed purus luctus faucibus nec eu est. Praesent id justo ante. Sed sed enim velit. Ut ac mauris magna. Fusce bibendum ullamcorper diam quis semper. Aenean mattis auctor ultricies. Mauris dui enim, vehicula sit amet finibus non, consectetur eu ante. Fusce at mi a ipsum gravida rhoncus.
</body>
<footer>
<button name="cancel2" type="cancel">Close</button>
<button name="wrapping_dialog">Submit Button of the Form</button>
</footer>
</form>
</dialog>
<ui-action action="open-dialog" target-id="dialog_containing_form">
<button class="secondary">Open the dialog containing the form</button>
</ui-action>
</messageML>
Below are simpler examples with and without the use of forms.
<messageML>
<ui-action trigger="click" action="open-dialog" target-id="dialogId">
<button>Simple dialog</button>
</ui-action>
<dialog id="dialogId">
<form id="formId">
<title>A Simple dialog</title>
<body>
This is a simple dialog.
</body>
<footer>
<button type="cancel" name="cancel-button">Close</button>
</footer>
</form>
</dialog>
</messageML>
<messageML>
<ui-action trigger="click" action="open-dialog" target-id="dialogId">
<button>Open the Dialog</button>
</ui-action>
<dialog id="dialogId">
<form id="formId">
<title>My Form in a Dialog</title>
<body>
<text-field name="input" />
</body>
<footer>
<button type="action" name="send-form">Submit</button>
<button type="reset">Reset</button>
<button type="cancel" name="cancel-form">Close</button>
</footer>
</form>
</dialog>
</messageML>
<messageML>
<form id="formId">
<text-field name="input" />
<ui-action trigger="click" action="open-dialog" target-id="dialogId">
<button>Open the Dialog</button>
</ui-action>
<dialog id="dialogId" width="small">
<title>A Dialog</title>
<body>
<expandable-card state="expanded">
<header>Dialog can include any other messageML component except Interactive Elements Forms</header>
<body>This does not contain any interactive element</body>
</expandable-card>
</body>
<footer>
Some text in the footer
<button type="cancel" name="cancel-form">Close</button>
</footer>
</dialog>
<h3>Actions</h3>
<button name="send-answers" type="action">Submit</button>
<button type="reset">Reset Data</button>
</form>
</messageML>
The max length of any ui-action or dialog attribute is 256.
Please note that the attribute type of the button is not supported when wrapped by a <ui-action> tag.
The dialog and ui-action tags must be both present in the same message, at the same nesting level, and they must share the same and unique id / target-id. Please note it is possible to have several dialogs in the same message as soon as each dialog has a different id.
The dialog feature is supported in popped-out mode. The dialog will open in the popped-out window.
The dialog functionality supports in the following way:
Dialogs can be contained inside forms. However, if contained in a form, the dialog cannot contain any interactive Element (such as button, text-area, etc.)
Dialogs can contain a form. The <form> tag should wrap the entire content of the dialog, including the <title>
This is useful when you want the submit button not to be hidden and always appear in the footer of the dialog whereas the rest of the form content is contained in the scrollable body area.
Please also note that users can close the dialog thanks to the cross (x) displayed at the top-right corner of it, as well as with a new type of that has been created for that purpose: <button type="cancel">. You can also specify the class attribute of the button which is by default set to "tertiary" for this new button.
target-id
String
Yes
Id of the dialog that must be opened when user will trigger this ui-action.
See the id attribute in the <dialog> tag.
width
String
No.
Default to medium
Specifies the width of the dialog.
NB: values can be: small, medium, large, or full-width.
An array of one or more of the following objects: org.symphonyoss.fin.security.id.ticker org.symphonyoss.fin.security.id.isin org.symphonyoss.fin.security.id.cusip org.symphonyoss.fin.security.id.openfigi More information about these objects is provided below.
value
Yes
String
The name/ID of a ticker.
value
Yes
String
The entity's ID.
value
Yes
String
The entity's ID.
value
Yes
String
The entity's ID.
version
Yes
String
The version.
format
Yes
String
The data format. Must be set to image.
url
Yes
String
The URL of the image.
version
Yes
String
The object's version.
id
Yes
Array of objects
An array of one or more of the following objects:
• com.symphony.user.userId
More information about these objects is provided below.
value
Yes
String
The ID of a user.
version
Yes
String
The version.
format
Yes
String
The video's format. Must be set to youtube or vimeo.
url
Yes
String
The URL of the video.
id
Yes
String
The unique ID of the video (can be extracted from the video URL).
