B24Frame Class

B24Frame extends AbstractB24 and implements TypeB24. On top of the shared REST surface (actions.v2.*, actions.v3.*, tools.*) it exposes managers that talk to the parent window through postMessage: auth, parent, slider, dialog, placement, options.

Constructor

constructor(
  queryParams: B24FrameQueryParams,
  options?: { restrictionParams?: Partial<RestrictionParams> }
)

B24FrameQueryParams describes the Bitrix24-supplied identifiers parsed from window.name:

Unlike B24Hook and B24OAuth, B24Frame requires await b24.init() before any REST call — init() performs the getInitData handshake with the parent window. initializeB24Frame() does this for you.

Getters

isInit

get isInit(): boolean

true once the parent-window handshake completes. Until then, accessing auth, actions, tools, or any frame manager throws 'B24 not initialized'.

isFirstRun

get isFirstRun(): boolean

true on the very first launch of the application (Bitrix24 sets FIRST_RUN). On isFirstRun = true, the SDK automatically sends setInstall: true to the parent.

isInstallMode

get isInstallMode(): boolean

true while the application is in installation flow (INSTALL flag from the parent). Required by installFinish.

auth

get auth(): AuthManager

Authorization manager. Exposes getAuthData, refreshAuth, getUniq, isAdmin, plus auto-refresh on 401 responses.

parent

get parent(): ParentManager

Parent window manager. Posting messages to and reading metadata from the surrounding Bitrix24 page.

slider

get slider(): SliderManager

Slider manager. Open / close Bitrix24 sliders.

placement

get placement(): PlacementManager

Placement manager. Inspect and update the placement context.

options

get options(): OptionsManager

Options manager. Read application / user options synced from the parent window.

dialog

get dialog(): DialogManager

Dialog manager. Ask Bitrix24 to render its native confirm / message / file pickers.

Methods

init

init(): Promise<void>

Performs the parent-window handshake (getInitData), wires the manager state, and creates both REST API HTTP clients. Idempotent in practice — initializeB24Frame() deduplicates concurrent calls.

destroy

destroy(): void

Unsubscribes from postMessage events. Always call before unmounting the host component to avoid leaks.

installFinish

installFinish(): Promise<any>

Sends setInstallFinish to the parent. Throws Error('Application was previously installed. You cannot call installFinish') when called outside install mode — guard with isInstallMode.

getAppSid

getAppSid(): string

Application session id relative to the parent window (mirrors APP_SID).

getLang

getLang(): B24LangList

Bitrix24 interface language enum. See LangList.

getTargetOrigin / getTargetOriginWithPath

getTargetOrigin(): string
getTargetOriginWithPath(): Map<ApiVersion, string>

Portal origin and per-version REST endpoints (parent-supplied).

Inherited from AbstractB24

getHttpClient, setHttpClient, setRestrictionManagerParams, getLogger, setLogger, actions, tools. See:

• Limiters
• Logger

Usage

import {
  initializeB24Frame,
  LoggerFactory,
  EnumCrmEntityTypeId,
  Text,
  type B24Frame,
  type ISODate
} from '@bitrix24/b24jssdk'

const $logger = LoggerFactory.createForBrowser('MyApp', import.meta.env?.DEV === true)
let $b24: undefined | B24Frame

async function loadCompanies() {
  if (!$b24) return

  const response = await $b24.actions.v2.callList.make<{ id: number, title: string, createdTime: ISODate }>({
    method: 'crm.item.list',
    params: {
      entityTypeId: EnumCrmEntityTypeId.company,
      select: ['id', 'title', 'createdTime']
    },
    idKey: 'id',
    requestId: 'companies-list'
  })

  if (!response.isSuccess) {
    $logger.error('REST error', { messages: response.getErrorMessages() })
    return
  }

  return response.getData()!.map((item) => ({
    id: Number(item.id),
    title: item.title,
    createdTime: Text.toDateTime(item.createdTime)
  }))
}

async function bootstrap() {
  try {
    $b24 = await initializeB24Frame()
    const companies = await loadCompanies()
    $logger.notice('companies', { companies })
  } catch (error) {
    $logger.error('init failed', { error })
  }
}

bootstrap()