Show Multiple User Selection Dialog BX24.selectUsers

BX24.selectUsers(callback: callable): void;
        BX24.selectUsers(title: string, callback: callable): void;
        

The method BX24.selectUsers displays a standard multiple user selection dialog. The dialog shows only the current employees of the company: there are no extranet users and no dismissed employees in it.

Bitrix24 itself renders the dialog on top of the application frame, so the application does not have to retrieve the list of employees. The dialog requires no scope of its own — it opens the Bitrix24 interface instead of calling the REST API. The dialog shows the whole organizational structure, without limiting it by the permissions of the current user.

The method can be called only from an application embedded in the Bitrix24 frame, with the BX24.js library included.

Call the method inside the BX24.init handler. The library does not defer the dialog itself until the initialization, but the functions that are usually called from the callback do not work before it — BX24.userOption.set, for example.

The multiple selection dialog is created anew on every call. The employees selected the previous time are not checked in the new dialog — if the selection has to survive between the launches of the application, retain it yourself.

To select a single employee, use BX24.selectUser: it displays the same dialog without multiple selection and returns one object instead of an array.

Method ParametersMethod Parameters

Required parameters are marked with *

Code ExamplesCode Examples

How to Use Examples in Documentation

Show the dialog and output the selected employees:

BX24.init(() => {
            BX24.selectUsers((selected) => {
                selected.forEach((user) => {
                    console.log(user.id, user.name);
                });
            });
        });
        

Collect the identifiers of the employees and retain them in the user configurations, so that the dialog is not shown every time the application is opened:

BX24.init(() => {
            BX24.selectUsers((selected) => {
                const ids = selected.map((user) => Number(user.id));
        
                // an empty selection does not overwrite the retained identifiers
                if (ids.length === 0)
                {
                    return;
                }
        
                BX24.userOption.set('assignees', ids.join(','));
            });
        });
        

Retrieve the profiles of the selected employees with the user.get method and assemble the links to their avatars. The method requires one of the scopes user, user_brief, or user_basic. A single user.get request returns no more than 50 records — if more employees are selected, read the rest with the next() method of the result:

BX24.init(() => {
            BX24.selectUsers((selected) => {
                if (selected.length === 0)
                {
                    return;
                }
        
                const ids = selected.map((user) => Number(user.id));
                const avatars = {};
        
                selected.forEach((user) => {
                    avatars[user.id] = user.photo
                        ? 'https://' + BX24.getDomain() + user.photo
                        : '';
                });
        
                BX24.callMethod('user.get', { ID: ids }, (result) => {
                    if (result.error())
                    {
                        console.log(result.error());
                        return;
                    }
        
                    result.data().forEach((employee) => {
                        console.log(employee.EMAIL, avatars[employee.ID]);
                    });
                });
            });
        });
        

Response HandlingResponse Handling

The dialog does not return the data directly: the result of the selection arrives in the callback function as an array of objects.

The callback function is triggered only by the Select button. The dialog can be closed without selecting anything by clicking outside the window — it has no cross, and the Esc key does not close it. In this case, the function is not invoked. If Select is pressed with nothing checked, the callback receives an empty array — check the length of the array before you retain the result.

The order of the objects in the array does not depend on the order of selection: the employees are sorted by ascending identifier. Identify an employee by the id field, not by the position in the array.

[
            {
                "id": "1",
                "name": "Klaus Weber",
                "sub": false,
                "sup": true,
                "position": "Director",
                "photo": "/upload/resize_cache/main/c1c/100_100_2/weber.jpg",
                "url": ""
            },
            {
                "id": "12",
                "name": "Anna Schmidt",
                "sub": true,
                "sup": false,
                "position": "Sales Manager",
                "photo": "",
                "url": ""
            }
        ]
        

The user confirmed an empty selection:

[]
        

Returned DataReturned Data

The identifier from the id field is passed to the Bitrix24 methods that expect a USER_ID. The other fields are returned by the dialog for displaying in the application interface — the up-to-date data about an employee is returned by user.get.

Error HandlingError Handling

The dialog returns no error codes. The cases when there is no result are covered in the Response Handling section.

The only error occurs before the dialog is called. If the page is opened outside the Bitrix24 frame, the exception with the text Unable to initialize Bitrix24 JS library! is thrown when the library script is loaded, not when the method is called — catch it at the point of inclusion.

Continue LearningContinue Learning

• System Dialogs: Overview of Methods
• Show User Single Selection Dialog BX24.selectUser
• Show Access Permission Selection Dialog BX24.selectAccess
• Call the CRM Object Selection Dialog BX24.selectCRM
• Call the REST service method with specified parameters BX24.callMethod
• Get a list of users by filter user.get
• Set Configurations for a User BX24.userOption.set