Dialog Manager Class

DialogManager is exposed via $b24.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, BX24.selectUsers, BX24.selectAccess and BX24.selectCRM helpers, but returns strongly-typed Promises instead of taking callbacks.

Methods

selectUser

async selectUser(): Promise<null|SelectedUser>

Displays the standard dialog for selecting a single company employee.

The promise resolves to a SelectedUser object, or null if the user closed the dialog without making a selection.

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

selectUsers

async selectUsers(): Promise<SelectedUser[]>

Displays the standard dialog for selecting multiple company employees.

The promise resolves to an array of SelectedUser objects. The array is empty when the user confirms the dialog without picking anyone.

// ... /////
$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

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).

The promise resolves to an array of SelectedAccess entries.

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

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

selectCRM

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

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

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

// ... /////
$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}`)
  })
}

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.

SelectedAccess

Represents one entry returned by selectAccess.

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

SelectCRMParamsEntityType

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.

SelectedCRMEntity

Represents one row inside a SelectedCRM bucket.

SelectedCRM

Result of selectCRM. Each property is either an array of SelectedCRMEntity refined with a literal id pattern, or undefined when the user picked nothing of that type.