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.









Identifies the person selector




Specifies a short hint that describes the expected value of the input field.




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.


It accepts a simple text and \n for line breaks


The description that will be displayed when clicking the tooltip icon located on top of the Element. Max length: 256 characters.



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.


Array of



Default value that will be preselected in the person-selector when the user receive the form from the bot.

Rules and Limitations

  • 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 (noreq) shows how a user can interact with a non-required 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.

  <form id="form_id">
      <person-selector name="withplaceholder" placeholder="My Placeholder"/>
      <person-selector name="withdefaultvalues" label="With default values" value='[12987981109743,12987981109741]' />
      <person-selector name="noreq" placeholder="Not required"/>
      <person-selector name="req" required="true" placeholder="Required"/>
      <person-selector name="withlabel" label="My Label" placeholder="With Label"/>
      <person-selector name="withtooltip" title="My Tooltip\n With a second line" placeholder="With Tooltip"/>
      <button name="person-selector">Submit</button>

User ID

The result returned by the datafeed for the selected users is an array of user Ids, which is an array of long.

Versions and Compatibility

Main features introduced

Agent needed to parse message sent by the bot

Client 2.0 release

Backward client-compatibility behavior (e.g. external rooms)

Initial release


Since first version

Not working



Since first version

Label displayed and form can still be submitted

Tooltip (title)


Since first version

Tooltip not displayed but form can still be submitted




For client 1.5, it displays the person-selector as if there was no default value

Last updated