Widget Development for Bitrix24: From Audit to Deployment

Widget Development for Bitrix24: From Audit to Deployment

A classic scenario: the CRM is already in use, managers handle all deals, but you need to add a block on the deal card with data from an external system—for example, warehouse stock from an ERP or delivery status from a transport company. Standard tools won't cut it; you need a widget via the REST API and the UI Extensions embedding mechanism. We at our company regularly solve such tasks: ERP integration, delivery status synchronization, displaying fiscal receipts from OFD directly in the lead card. Over the years, we've developed a clear approach to widget development: from auditing business processes to publishing in the Marketplace. In this article, we share practical insights.

Widgets in Bitrix24 are a separate type of application that renders inside the portal interface via iframe or JS SDK. In recent portal versions, Bitrix is actively developing the concept of UI Extensions as a more performant and convenient alternative to classic iframe widgets. Let's break down what to choose for a specific task and how everything works under the hood.

How to Choose Between iframe and UI Extensions?

What Types of Widgets and Embedding Places Exist?

Bitrix24 supports several embedding mechanisms:

• Placement API (BX24.placement.call) — the classic way: the app registers a placement, Bitrix24 displays it in the appropriate interface location.
• UI Extensions — a set of ready-made components (Button, Dialog, Loader, Alert) available via @bitrix24/b24jssdk.
• Slider — opening an arbitrary URL in a side panel via BX24.openApplication().

Current placements are registered during app installation via the app.option.set method and stored in the b_app_option table. List of available embedding points:

Each placement passes contextual information to the widget: entity ID, type, access rights. More about placements can be found in the official documentation.

How Does an iframe Widget Work?

A typical widget consists of two parts: a server-side handler (endpoint that returns the widget page HTML) and client code inside the iframe.

Initialization in client code:

BX24.init(() => { const placement = BX24.placement.info(); const dealId = placement.options.ID; BX24.callMethod('crm.deal.get', { id: dealId }, (result) => { if (result.error()) { console.error(result.error()); return; } renderWidget(result.data()); }); }); 

iframe height is a common issue. Bitrix24 does not make the iframe automatically elastic. After rendering content, you must explicitly call:

BX24.fitWindow(() => { // callback after height change }); 

If not done, the widget will be cut off or an internal scrollbar appears.

Why Are UI Extensions Faster?

In recent portal versions, it's recommended to use @bitrix24/b24jssdk. It provides typed access to the REST API directly from the iframe:

import { initializeB24Frame, B24Frame } from '@bitrix24/b24jssdk'; const $b24 = await initializeB24Frame(); const profile = await $b24.fetchProfile(); const result = await $b24.callMethod('crm.deal.list', { filter: { ASSIGNED_BY_ID: profile.id }, select: ['ID', 'TITLE', 'STAGE_ID'] }); 

The SDK handles authorization (OAuth token is passed automatically via postMessage), no need to store client_secret on the client. UI Extensions starts 30% faster than an iframe widget due to the direct event bus.

Placement Registration and App Manifest

The app registers placements during installation via the OnAppInstall hook. Example in the manifest:

{ "placements": [ { "placement": "CRM_DEAL_DETAIL_TAB", "handler": "https://myapp.example.com/widget/deal-tab", "title": "ERP Data", "description": "Stock and reserves by deal items" } ] } 

Or programmatically via REST:

POST /rest/placement.bind { "PLACEMENT": "CRM_DEAL_DETAIL_TAB", "HANDLER": "https://myapp.example.com/widget/deal-tab", "TITLE": "Warehouse" } 

Why OAuth Security Matters?

All requests from the iframe to the server must pass AUTH_ID (short-lived token, 1 hour) or use REFRESH_TOKEN to refresh it. Never store client_secret in client code—only on the server.

Validate incoming event from postMessage:

window.addEventListener('message', (event) => { if (event.origin !== 'https://your-portal.bitrix24.ru') return; // processing }); 

OAuth is a key security element. Experience shows that most widget development errors are related to incorrect token handling. More about OAuth can be found on Wikipedia.

Typical Mistakes and Their Solutions

• Content Security Policy (CSP) of Bitrix24 restricts frame-ancestors. Your app domain must be whitelisted, which is configured automatically when publishing in the Marketplace or registering a local application.
• Slow initialization of BX24.init() — if the widget loads longer than 3 seconds, users switch to another tab. Optimization: load bx24.js via CDN, show a skeleton loader until data arrives.
• Cross-domain cookies — for session authorization of your backend, use SameSite=None; Secure, otherwise the browser blocks cookies inside the iframe.

If you encounter any of these issues, contact us. Our certified specialists will help diagnose and fix the problem. Get in touch for a free project evaluation.

What the Work Includes

• Audit of current CRM and integration scenarios
• Design of widget architecture with security in mind
• Implementation and testing in multiple browsers (Chrome, Firefox, Safari, mobile apps)
• Integration with external systems (ERP, OFD, transport companies)
• Documentation for installation and maintenance
• Training of portal administrators

We provide a warranty on all completed work. Therefore, we use only proven solutions and years of experience.

Development Timeline

The main time is spent not on the widget itself, but on setting up OAuth authorization, handling edge cases (expired token, portal in a different datacenter), and testing in multiple browsers—Bitrix24 supports Chrome, Firefox, Safari, and mobile apps with different iframe behavior.

Order widget development today. We'll evaluate your project for free. Contact us to discuss the details.