Configure Custom Fields in Rocket Chat

You can set custom fields for specific users while registering or updating user information. For example, you can add fields like address or employee ID.

You may need some basic understanding of Javascript and Rocket.Chat's internal working structure is required to set other custom fields than those in the example below. A more user-friendly interface is planned for the future.

Define custom fields

To set custom fields, go to Manage → Workspace → Settings → Accounts → Registration → Custom Fields. Configure the custom fields using a JSON object containing a dictionary of field settings. Let's look at two examples. The setting provides a code editor with line numbers; click Full Screen to expand the editor while working with larger configurations.

Basic example

In this example, we add two custom fields, team and designation, with the type text. This means that the custom fields can take any text values as input.

{
	"team": {
		"type": "text"
	},
	"designation": {
		"type": "text"
	}
}

Custom field keys are case-sensitive. The key you define here (for example, team) is the exact name you must use everywhere the field is referenced, such as in Custom Fields to Show in User Info or via the API.

Once these custom fields are saved, you can enter the values for the fields while creating a new user or updating an existing user. The following screenshot shows the example:

Advanced example

Here, role is a custom field consisting of two options (teacher and student) as the possible values. twitter and dept are text fields where you can enter values according to the defined settings.

{
	"role": {
		"type": "select",
		"defaultValue": "student",
		"options": ["teacher", "student"],
		"required": true,
		"modifyRecordField": {
			"array": true,
			"field": "roles"
		}
	},
	"twitter": {
		"type": "text",
		"required": true,
		"minLength": 2,
		"maxLength": 10
	},
	"dept": {
		"type": "text",
		"required": false,
		"minLength": 12,
		"sendToIntegrations": true
	}
}

Let's look at the properties in detail:

Parameter	Description
type	Defines the type of the custom field. Currently, there are 2 types: `select` and `text`, where `select` creates a drop-down list, and `text` creates a plain text form. If you enter a URL in the text field, it is interpreted as a hyperlink (it will be clickable on the User Info pane).
defaultValue	Used with a `select` form type to set the default option for the list.
options	Used with a `select` form type for the values that should be on the drop-down list, which follows the `["item1", "item2","item3"]` pattern. Use a JavaScript Array to create it.
required	Set whether the field is required for registration. Enter `true` or `false` for this property.
minLength	Used with the `text` type to define the minimum length required for the text.
maxLength	Used with the `text` type to define the maximum length allowed for the text.
modifyRecordField	This property is required when you add a field that already exists in Rocket.Chat. ⚠️ The `modifyRecordField` property allows users to modify the mapped field on their own profile. If pointed at sensitive fields like `roles` or `permissions`, regular users can escalate their own privileges, including granting themselves administrator access. Review this configuration carefully and avoid mapping to security-sensitive fields unless you fully understand the implications.
array	Used inside the `modifyRecordField` property to define whether the existing field is an array.
field	Used inside the `modifyRecordField` property. It should be the name of the existing field. It must be the exact (case-sensitive) name of the existing field, for example `roles`.
public	Defines the field as visible to other users when viewing the user's profile. Enter `true` or `false` for this property. By default, the value is `true`.
private	Defines the field as private. Only users with `view-full-other-user-info` permission can see this field when viewing the user's profile. Enter `true` or `false` for this property.
sendToIntegrations	Defines the field as shareable with external applications, such as Omnichannel integrations.

Use tabs for indentation in the JSON object, do not use spaces.
You can also use the API to create and manage custom fields. See the Create User, Update User, and Get Users List endpoints.

Display user’s custom fields

You can configure the list of custom fields displayed on the User Info panel. Go to Manage → Workspace → Settings → Accounts → Custom Fields to Show in User Info.

The value must be a JSON array of objects, where each object's key is the label shown to users and its value is the custom field name defined previously:

[{"label1":"key1"},{"label2":"key2"},...]

The label can be the name of the custom field that is displayed for users. The key must be a custom field name defined previously. Considering the previous example, the field can look something like this:

[{"Role":"role"},{"Department":"dept"}]

This means that the role and dept custom fields will be displayed on the User Info panel with the labels Role and Department. Note that a field is only shown if it is set to "public": true or if the viewer has permission to view private fields.

Set custom field values

Now that you have configured the custom fields, they will be displayed when creating new users or updating existing ones. Enter the respective values and save the user details.

Configure Custom Fields for Users

Define custom fields

Display user’s custom fields

Set custom field values