---
title: "Dialog Manager Class"
description: "Wraps the BX24 system dialogs (user picker, access permission picker, CRM entity picker) so they can be opened from inside a Bitrix24 application iframe."
canonical_url: "https://bitrix24.github.io/b24jssdk/docs/working-with-the-rest-api/frame-dialog"
last_updated: "2026-05-08"
---
# Dialog Manager Class

> Wraps the BX24 system dialogs (user picker, access permission picker, CRM entity picker) so they can be opened from inside a Bitrix24 application iframe.

`DialogManager` is exposed via [`$b24.dialog`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/frame.md#dialog) on a `B24Frame` instance and is only available when your application is rendered inside a Bitrix24 iframe (it relies on `postMessage` to talk to the parent window).

It mirrors the legacy [`BX24.selectUser`](https://apidocs.bitrix24.com/sdk/bx24-js-sdk/system-dialogues/bx24-select-user.html), [`BX24.selectUsers`](https://apidocs.bitrix24.com/sdk/bx24-js-sdk/system-dialogues/bx24-select-users.html), [`BX24.selectAccess`](https://apidocs.bitrix24.com/sdk/bx24-js-sdk/system-dialogues/bx24-select-access.html) and [`BX24.selectCRM`](https://apidocs.bitrix24.com/sdk/bx24-js-sdk/system-dialogues/bx24-select-crm.html) helpers, but returns strongly-typed `Promise`s instead of taking callbacks.

## Methods

### selectUser

```ts
async selectUser(): Promise<null|SelectedUser>
```

Displays the standard dialog for selecting a single company employee.

The promise resolves to a [`SelectedUser`](#selecteduser) object, or `null` if the user closed the dialog without making a selection.

```ts
// ... /////
$b24 = await initializeB24Frame()
// ... /////
const makeSelectUser = async() => {
  const selectedUser = await $b24.dialog.selectUser()
  if (!selectedUser) {
    return
  }
  $logger.info(selectedUser)
}
```

### selectUsers

```ts
async selectUsers(): Promise<SelectedUser[]>
```

Displays the standard dialog for selecting multiple company employees.

The promise resolves to an array of [`SelectedUser`](#selecteduser) objects. The array is empty when the user confirms the dialog without picking anyone.

```ts
// ... /////
$b24 = await initializeB24Frame()
// ... /////
const makeSelectUsers = async() => {
  const selectedUsers = await $b24.dialog.selectUsers()

  const list = selectedUsers.map((row: SelectedUser): string => {
    return [`[id: ${row.id}]`, row.name].join(' ')
  })

  $logger.info(selectedUsers, list)
}
```

### selectAccess

```ts
async selectAccess(blockedAccessPermissions?: string[]): Promise<SelectedAccess[]>
```

Displays the standard access permission selection dialog (departments, groups, individual users, and predefined permission codes such as `AU` or `CR`).

| Parameter | Type | Description |
| --- | --- | --- |
| `blockedAccessPermissions` | `string[]` | Optional list of permission codes to disable in the dialog. Defaults to `[]` . Useful when some permissions are already granted elsewhere. |

The promise resolves to an array of [`SelectedAccess`](#selectedaccess) entries.

```ts
// ... /////
$b24 = await initializeB24Frame()
// ... /////
const makeSelectAccess = async() => {
  const selected = await $b24.dialog.selectAccess(['AU'])

  $logger.info(
    selected.map(row => `${row.id} → ${row.name}`)
  )
}
```

### selectCRM

```ts
async selectCRM(params?: SelectCRMParams): Promise<SelectedCRM>
```

Displays the standard dialog for selecting CRM entities (leads, contacts, companies, deals, quotes).

| Parameter | Type | Description |
| --- | --- | --- |
| `params.entityType` | `SelectCRMParamsEntityType[]` | Which entity types to show as tabs in the picker. Allowed values: `lead` , `contact` , `company` , `deal` , `quote` . |
| `params.multiple` | `boolean` | Allow multiple selection. Defaults to `false` . |
| `params.value` | `SelectCRMParamsValue` | Optional map of entity IDs to mark as initially selected. Applied **only when `multiple` is `true`** — single-select mode ignores it. |

The promise resolves to a [`SelectedCRM`](#selectedcrm) object whose properties (`lead`, `contact`, `company`, `deal`, `quote`) are real JavaScript arrays of [`SelectedCRMEntity`](#selectedcrmentity). Buckets for entity types the user did not pick (or did not request) are left `undefined` rather than set to an empty array.

> [!NOTE]
> Since v1.0.7, `selectCRM` always returns real arrays. Earlier versions forwarded the parent window's payload as-is, so each bucket was actually a `Record<string, SelectedCRMEntity>` (e.g. `{ 0: {...}, 1: {...} }`) — calling `.length` or `.map()` on it returned `undefined`. Code written against the documented types continues to work; the only behavioural difference is that the runtime shape now matches the types.

```ts
// ... /////
$b24 = await initializeB24Frame()
// ... /////
const makeSelectCRM = async() => {
  const selected = await $b24.dialog.selectCRM({
    entityType: ['contact', 'company'],
    multiple: true,
    value: {
      contact: [42],
      company: [7]
    }
  })

  selected.contact?.forEach((row) => {
    $logger.info(`[${row.id}] ${row.title} — ${row.url}`)
  })

  selected.company?.forEach((row) => {
    $logger.info(`[${row.id}] ${row.title}`)
  })
}
```

> [!NOTE]
> Single-select mode (`multiple: false`) still resolves to the same `SelectedCRM` shape — buckets just contain at most one element. To grab that element use `selected.contact?.[0]`.

## Data Types

### SelectedUser

Represents a single company employee picked through `selectUser` / `selectUsers`. The `sub` and `sup` flags describe the hierarchical relationship with the current user.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `NumberString` | User identifier — a string containing a numeric value (e.g. `"42"` ). |
| `name` | `string` | Formatted display name. |
| `photo` | `string` | URL of the user's avatar. |
| `position` | `string` | User's job title. |
| `url` | `string` | URL of the user's profile inside the portal. |
| `sub` | `boolean` | `true` when the selected user is a subordinate of the current user. |
| `sup` | `boolean` | `true` when the selected user is a supervisor of the current user. |

### SelectedAccess

Represents one entry returned by `selectAccess`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Permission code (see the table below). |
| `name` | `string` | Human-readable name of the permission, localized to the portal language. |

The `id` field uses Bitrix24's permission-code grammar:

| Pattern | Meaning |
| --- | --- |
| `AU` | All authorized portal users. |
| `CR` | Current user. |
| `U${number}` | A specific user by ID. |
| `IU${number}` | An employee by ID (extranet-aware). |
| `D${number}` | All employees of a department. |
| `DR${number}` | All employees of a department, including subdepartments. |
| `G${number}` | A user group (e.g. `G2` — all visitors). |
| `SG${number}` | A social network / workgroup. |

### SelectCRMParamsEntityType

```ts
type SelectCRMParamsEntityType = 'lead' | 'contact' | 'company' | 'deal' | 'quote'
```

The set of CRM entity kinds that `selectCRM` understands. Passed in as `params.entityType` and used as the keys of both `SelectCRMParamsValue` and `SelectedCRM`.

### SelectCRMParamsValue

Map of entity IDs to pre-select when `multiple: true`. Only the requested entity types are read; extra keys are ignored.

| Field | Type | Description |
| --- | --- | --- |
| `lead` | `number[]` | Lead IDs to mark as already selected. |
| `contact` | `number[]` | Contact IDs to mark as already selected. |
| `company` | `number[]` | Company IDs to mark as already selected. |
| `deal` | `number[]` | Deal IDs to mark as already selected. |
| `quote` | `number[]` | Quote IDs to mark as already selected. |

### SelectedCRMEntity

Represents one row inside a `SelectedCRM` bucket.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Prefixed entity identifier — see the table in `SelectedCRM` . |
| `type` | `SelectCRMParamsEntityType` | Entity kind (`lead` / `contact` / `company` / `deal` / `quote` ). |
| `place` | `string` | UI placement label used by Bitrix24 (rarely needed; informational). |
| `title` | `string` | Display title of the entity (e.g. company name, deal title, contact full name). |
| `desc` | `string` | Short description shown next to the title in the picker. |
| `url` | `string` | URL to open the entity inside the portal. |

### SelectedCRM

Result of `selectCRM`. Each property is either an array of [`SelectedCRMEntity`](#selectedcrmentity) refined with a literal `id` pattern, or `undefined` when the user picked nothing of that type.

| Field | Type | Description |
| --- | --- | --- |
| `lead` | `(SelectedCRMEntity&{id:``L_${number}``})[]` | Picked leads. Each `id` looks like `L_42` . |
| `contact` | `(SelectedCRMEntity&{id:``C_${number}``,image:string})[]` | Picked contacts. The extra `image` field holds the contact's avatar URL. |
| `company` | `(SelectedCRMEntity&{id:``CO_${number}``,image:string})[]` | Picked companies. The extra `image` field holds the company logo URL. |
| `deal` | `(SelectedCRMEntity&{id:``D_${number}``})[]` | Picked deals. Each `id` looks like `D_17` . |
| `quote` | `(SelectedCRMEntity&{id:``Q_${number}``})[]` | Picked quotes. Each `id` looks like `Q_3` . |

## Sitemap

See the full [sitemap](/b24jssdk/sitemap.md) for all pages.