Show User Single Selection Dialog BX24.selectUser

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

The method BX24.selectUser displays a standard single user selection dialog. The dialog shows only the current employees of the company who belong to at least one department. There are no extranet users, dismissed employees, invited employees with an unactivated account, or service users — chatbots, mail, and connector users — 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 shows the whole organizational structure, without limiting it by the permissions of the current user.

The composition of the dialog depends on who opened the application. If it is an extranet user, they have no organizational structure tab, and the list of employees is limited to their workgroups.

The dialog requires no scope of its own: it opens the Bitrix24 interface instead of calling the REST API.

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.

An employee cannot be checked in advance, and the list of employees in the dialog cannot be narrowed down.

The single selection dialog is created once and then reused. On a repeat call, the same window opens: the previous selection is checked in it, and the search field holds the name of the selected employee. The window lives on the Bitrix24 page, so reloading the application frame does not reset it. The selection is not carried over to the application — retain it yourself.

To select several employees, use BX24.selectUsers: it displays the same dialog with multiple selection and returns an array of objects instead of a single object.

Method ParametersMethod Parameters

Required parameters are marked with *

Code ExamplesCode Examples

How to Use Examples in Documentation

Show the dialog and output the selected employee:

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

Retain the selected employee in the user configurations, so that the dialog is not shown every time the application is opened:

BX24.init(() => {
            BX24.selectUser((user) => {
                BX24.userOption.set('assignee', user.id);
            });
        });
        

Retrieve the profile of the selected employee with the user.get method through BX24.callMethod and assemble the link to the avatar. The method requires one of the scopes user, user_brief, or user_basic, but the EMAIL field does not arrive in user_brief:

BX24.init(() => {
            BX24.selectUser((user) => {
                const avatar = user.photo
                    ? 'https://' + BX24.getDomain() + user.photo
                    : '';
        
                BX24.callMethod('user.get', { ID: Number(user.id) }, (result) => {
                    if (result.error())
                    {
                        console.log(result.error());
                        return;
                    }
        
                    const employee = result.data()[0];
        
                    if (!employee)
                    {
                        return;
                    }
        
                    console.log(employee.EMAIL, employee.WORK_POSITION, avatar);
                });
            });
        });
        

Response HandlingResponse Handling

The dialog does not return the data directly: the result of the selection arrives in the callback function as an object. The method itself returns void, so the selection cannot be awaited with await — work with the result inside the callback.

The callback function is triggered by a click on an employee, the dialog has no separate confirmation 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: the single selection dialog never yields an empty result.

{
            "id": "12",
            "name": "Anna Schmidt",
            "sub": true,
            "sup": false,
            "position": "Sales Manager",
            "photo": "/upload/resize_cache/main/c1c/100_100_2/schmidt.jpg",
            "url": ""
        }
        

An employee with no position and no photo:

{
            "id": "7",
            "name": "Lukas Fischer",
            "sub": false,
            "sup": false,
            "position": null,
            "photo": "",
            "url": ""
        }
        

Returned DataReturned Data

Apart from id, the 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 case when there is no result is covered in the Response Handling section.

The only error appears before the dialog is called. The library takes the address of Bitrix24 and the identifier of the application session from window.name, which Bitrix24 sets. If the page is opened outside the frame of a Bitrix24 application, the exception with the text Unable to initialize Bitrix24 JS library! is thrown when the library script is loaded, and the BX24 object is nulled. Catch the exception at the point of inclusion: the library cannot be used after that.

Continue LearningContinue Learning

• System Dialogs: Overview of Methods
• Show Multiple User Selection Dialog BX24.selectUsers
• 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