Bitrix24 Application Development with React

Bitrix24 Application Development with React

Bitrix24 applications are external web applications embedded in the portal interface via iframe or opened in a separate tab. They communicate through the Bitrix24 REST API, receive user context via the BX24.js SDK, and can be embedded in various interface locations: the CRM sidebar, a lead card, the portal header, or a dedicated application page.

React is a natural choice for such applications: component-based architecture, a rich ecosystem, and TypeScript typing for the Bitrix24 REST API.

Application Types and Their Architecture

Embedded applications — displayed inside the Bitrix24 interface in an iframe. The size is fixed or adaptive via BX24.resizeWindow(). Available placement points: CRM_LEAD_DETAIL_TAB, CRM_DEAL_DETAIL_TAB, TASKS_TASK_VIEWFORM_SIDEBAR, and dozens of others.

Standalone applications — open on a dedicated page within Bitrix24 (/apps/). A full SPA with its own routing.

Widgets — small components embedded in specific cards. For example, a widget in a deal card that shows shipment history from an external ERP.

// Initializing BX24 in a React application
import { useEffect, useState } from 'react';

declare global {
  interface Window { BX24: any; }
}

function useBX24Init() {
  const [isReady, setIsReady] = useState(false);
  const [user, setUser] = useState(null);

  useEffect(() => {
    window.BX24.init(() => {
      setIsReady(true);
      window.BX24.callMethod('profile', {}, (result: any) => {
        setUser(result.data());
      });
    });
  }, []);

  return { isReady, user };
}

Authentication and REST API

Application authorization uses OAuth 2.0. Bitrix24 issues an access_token when the application is opened in an iframe (via postMessage or URL parameters). For server-side requests (backend-to-Bitrix24) — authorization uses client_id + client_secret + webhook.

The typical architecture: the React frontend makes requests to its own backend (not directly to Bitrix24), and the backend proxies to the Bitrix24 REST API using a server-side token. This keeps tokens out of the browser and allows caching of repeated requests.

// React hook for calling Bitrix24 REST via BX24.js (client-side)
function useBX24Method<T>(method: string, params: object) {
  return useQuery({
    queryKey: ['bx24', method, params],
    queryFn: () =>
      new Promise<T>((resolve, reject) => {
        window.BX24.callMethod(method, params, (result: any) => {
          if (result.error()) reject(result.error());
          else resolve(result.data());
        });
      }),
    staleTime: 30_000,
  });
}

// Usage
const { data: deals } = useBX24Method<Deal[]>('crm.deal.list', {
  select: ['ID', 'TITLE', 'STAGE_ID', 'OPPORTUNITY'],
  filter: { ASSIGNED_BY_ID: currentUserId },
  order:  { DATE_MODIFY: 'DESC' },
});

Bitrix24 UI Kit in React

Bitrix24 provides the official @bitrix24/b24jssdk and a UI Kit based on React components. Using the UI Kit ensures visual consistency with the Bitrix24 interface — the application looks like a native part of the portal.

UI Kit components: Button, Input, Select, Table, Modal, Notification, Avatar, Badge. Styling through CSS variables automatically adapts to the portal theme (light/dark).

Case Study: SLA Control Application for CRM

B2B services company, 45 managers, deals pass through 8 stages. Task: a widget in the deal card showing how long the deal has been at the current stage, an SLA violation flag (if it exceeds the norm), and a history of stage transitions.

Bitrix24 has no built-in SLA control for CRM Deals.

Implementation:

Backend — Laravel (separate server). On every deal stage change, a webhook from Bitrix24 (event: ONCRMDEALUPDATE) records the transition in a deal_stage_history table with timestamps.

The React widget is embedded in CRM_DEAL_DETAIL_TAB. When the card is opened, a request goes to the custom backend with DEAL_ID, which returns: current stage, time on stage, SLA norm for that stage, status (within norm / violated), list of transitions.

Visualization: stage timeline with color coding. Red — SLA violated, yellow — 75% of time used, green — within norm.

function SlaWidget({ dealId }: { dealId: number }) {
  const { data } = useSlaData(dealId);

  if (!data) return <Spinner />;

  return (
    <div className="sla-widget">
      <SlaTimer
        currentStage={data.currentStage}
        timeOnStage={data.timeOnStage}
        slaLimit={data.slaLimit}
        status={data.status}
      />
      <StageTimeline history={data.stageHistory} />
    </div>
  );
}

Notifications: when an SLA is violated, the backend sends a notification to the responsible manager and their supervisor via the im.notify.system.add REST API.

Webhooks and Real-Time Updates

Bitrix24 applications can subscribe to events via webhooks: deal changes, task changes, contact changes. This enables applications with near-real-time updates.

For real-time in React — Server-Sent Events (SSE) or polling. WebSocket on top of Bitrix24 is only available via BX24.callMethod('pull.application.event.add') with the Push & Pull module.

Publishing and Deployment

The application is registered in the Bitrix24 Marketplace or installed directly on a specific portal. For enterprise solutions — the latter: the application is deployed on a private server and registered via Settings → Applications → Add application.

HTTPS is mandatory — Bitrix24 does not load HTTP content in iframes.

Scope of Work

• Design: placement point, API methods, authorization scheme
• Application registration in Bitrix24, OAuth configuration
• Backend development: REST proxy, business logic, webhooks
• React SPA development: components, state, BX24.js integration
• Testing on a live Bitrix24 portal, authorization edge cases

Timeline: a simple embedded widget — 1–2 weeks. A full standalone application with a custom backend — 4–12 weeks depending on functionality.