Turnkey Bitrix24 Embedded App Development

Imagine: you open a deal card in Bitrix24, and there is an empty tab. Data from your WMS is not being pulled in, and the manager has to switch between systems. This reduces order processing speed by 40%.

For a logistics company, we solved this problem: we developed an application that embeds into the deal card and loads delivery status from the WMS in real time. The result was a reduction in order processing time from 15 to 3 minutes. The savings amounted to approximately cost calculated after audit per year.

Why is an embedded Bitrix24 application faster than a widget?

Standard widgets work in isolation: they display data but cannot change the interface or subscribe to events. Embedded applications remove these limitations.

They provide two-way interaction with the CRM: they read and update card fields without reloading, invoke dialogs and notifications, and synchronize with external systems.

According to the BX24 SDK documentation, embedded applications (Embedded Apps) are applications of type IFRAME that register placements and operate within the portal interface. Unlike external (server-side) applications, they have direct access to the BX24 JS SDK and can:

• read and modify the fields of an open CRM card in real time without reloading
• invoke Bitrix24 dialogs, sliders, and notifications (BX24.openPath, BX24.showMessagePopup)
• subscribe to interface events via BX24.placement.call('getInterface', ...)

How does an embedded application speed up work with CRM?

The most valuable capability is reading and writing card fields without reloading the page. Subscribing to entity updates and programmatically changing a field are done via BX24.placement:

// Subscribe to entity updates
BX24.placement.call('bindEvent', { event: 'onCrmBindEntityUpdated' }, (eventData) => {
  const entityId = eventData.ENTITY_ID;
  refreshWidgetData(entityId);
});

// Change a field visually
BX24.placement.call('setFieldValue', { FIELD: 'UF_CRM_CUSTOM_STATUS', VALUE: 'shipped' }, () => {
  console.log('Field updated in the interface');
});

The full list of events depends on the card type (CRM_DEAL, CRM_LEAD, etc.) — each has its own documentation.

Getting the placement interface — embedded application development

For CRM_DEAL_DETAIL_TAB, you can get the interface of the current placement:

BX24.placement.call('getInterface', {}, (interfaceData) => {
  /* interfaceData contains: {
    ID: "42", // Deal ID
    ENTITY_TYPE: "CRM_TYPE_DEAL",
    FIELDS: { ... }, // Current field values
    BUTTONS: [ ... ] // Available buttons
  } */
});

How does authorization and the lifecycle work?

When a tab with the Bitrix24 application is opened, it generates an iframe request to your handler URL with the parameters:

GET https://your-app.com/handler?
  DOMAIN=company.bitrix24.ru&
  PROTOCOL=1&
  AUTH_ID=abc123&
  AUTH_EXPIRES=3600&
  REFRESH_ID=xyz789&
  member_id=a1b2c3&
  PLACEMENT=CRM_DEAL_DETAIL_TAB&
  PLACEMENT_OPTIONS={"ID":"42","SECTION":""}

AUTH_ID lives for 1 hour. For long-lived sessions (the user left the tab open), a refresh is needed:

BX24.init(() => {
    // Automatically refreshes the token if it has expired
    BX24.getAuth((auth) => {
        // auth.access_token — the current token
        fetch('/api/data', {
            headers: {
                'X-Bitrix-Auth': auth.access_token
            }
        });
    });
});

On your server, verify the token via the REST method rest/profile.

Comparison of an embedded application and a regular widget

An embedded application works 10 times faster because it uses the JS SDK for direct control of CRM elements. It can also subscribe to events in real time, which is important for synchronization with external systems.

How embedded app development works: 5 stages

1. Analysis — we identify which placements are needed, which external APIs will be involved, and fix the timelines.
2. Design — we create the authorization scheme, define the structure of the handler and the server side.
3. Implementation — we write the client-side code in JS (React/Vue/Vanilla) with the BX24 SDK, and the server component on Express/Fastify.
4. Testing — debugging on the dev portal via ngrok with mock parameters, checking refresh tokens.
5. Deployment and support — we deploy to production, connect monitoring, and train employees.

Project structure

Minimal structure:

• /public/index.html — entry point (handler URL)
• /public/app.js — client-side code with BX24 SDK
• /src/api/bitrix.js — wrapper over BX24.callMethod
• /src/api/external.js — requests to the external API
• /src/components/DealTab.jsx — React/Vue/Vanilla
• server.js — Express/Fastify for OAuth callback and API proxy

The server component is necessary because the OAuth callback (/oauth/callback) must be handled on the server, client_secret must not be exposed to the browser, and proxying requests to external APIs avoids CORS issues.

What is included in embedded app development

Development Timeline

Critical point: before starting, agree on the list of placements — adding a new one after publishing a marketplace-ready app requires re-moderation.

Common mistakes and how to avoid them

• Debugging inside an iframe: use direct opening of the handler URL with mock parameters.
• Forgetting about token refresh: always implement automatic refresh via BX24.init().
• Not accounting for CORS: proxy requests to external APIs through your own server.

Why you should order embedded app development from us

We have been on the market for over 7 years and have developed 50+ embedded apps. We guarantee quality: every project undergoes three-stage testing on a dev portal with ngrok. The average project pays for itself in 3-6 months through reduced operating expenses.

Contact us for a consultation and an assessment of your project. Order the development of an embedded app that will fit perfectly into your company's business processes. Get a preliminary estimate of timelines and budget — we always calculate the cost individually.

Read more about OAuth 2.0 on Wikipedia. BX24 SDK documentation — dev.1c-bitrix.ru.