Widget Integration Mechanism

The REST API allows you to add your functionality to Bitrix24 in the form of widgets in various places within the user interface—such as the main menu of the account, in the item list menus, in CRM and task cards, etc.

Basic Widget in the Left MenuBasic Widget in the Left Menu

This is the simplest integration, which can be done not even through the REST API, but via the settings of a local or mass-market application.

In the case of a local application, specify the name of the menu item:

Clicking on this item will open a slider with the application in the form of a frame, where the URL you specified as the main one in the local application settings will be inserted.

For mass-market solutions hosted in the Developer's area, you need to do two things:

In the version card, select the option "Add your page and item to the main menu."

In the description in the required language, specify the value in the "Application Name in Menu" field.

How Other Integrations WorkHow Other Integrations Work

Unlike the integration of the slider with the main URL of the application in the left menu, all other widgets are integrated differently—using the placement.bind method.

Special Widgets - Custom Field Types in CRM CardsSpecial Widgets - Custom Field Types in CRM Cards

You can create your own interfaces for displaying and editing fields in CRM cards (in leads, deals, etc.). This can be an interface with geo-maps, sets of informers, or industry data. Essentially, Bitrix24 will be responsible for saving field values, while the interface for displaying these values will be fully implemented by the applications.

To use this scenario, you need to register custom field types. These are not the fields themselves, but rather the types. Later, either the user through standard CRM interfaces or your application using REST methods can add fields of these types and use your editing interface for such fields.

Opening Standard and Custom Sliders from Widget InterfacesOpening Standard and Custom Sliders from Widget Interfaces

Often, it is necessary to open standard pages of Bitrix24 from the widget interface. This could be, for example, a slider with a contact card or a slider with the required task.

In addition to standard sliders, solution developers have the option to display their custom interfaces in a slider. For instance, this could be a custom document viewing card, a slider with application settings, a slider with a report, etc. You will be able to customize the appearance of such a slider.

Interacting with the Bitrix24 UI from WidgetsInteracting with the Bitrix24 UI from Widgets

For certain scenarios, it is necessary for developers to access various Bitrix24 capabilities directly from the frontend of their widgets.

First and foremost, this includes the ability to make direct calls to REST methods. Secondly, there are special methods implemented only for specific types of widgets. In particular,

• in the call card
• in the WebRTC scenario
• in the CRM card

Benefits of Using WidgetsBenefits of Using Widgets

We highly recommend using widget integrations in the user interface to implement convenient user scenarios. This provides developers with a range of advantages:

• Users will receive your functionality exactly where it needs to be used. For example, if your application provides users with additional information about deals, it is most convenient for users to access this information when they are already in the relevant deal.
• User scenarios with widgets are easier to program. Referring back to the previous example: if your application provides additional information about a specific deal, integrating it into the deal card will save you from having to create your own interface with a list of deals. The user already has a great opportunity to find the necessary deal in the CRM interface. You only need to focus on your unique functionality.
• If you have developed a mass-market application with widgets, the Market showcase will offer your solution to clients in the widget integration locations you used. You will receive more targeted and quality traffic, leading to better conversion rates for your applications.

It is also recommended to use the openPath method to show users standard Bitrix24 objects, and the openApplication method to simplify user scenarios within your application. Users are accustomed to the pattern where additional information or details about something are displayed in a slider over the previous interface.

You should use openApplication for:

• Displaying your application's settings form instead of popup windows within the application frame
• Showing various detail forms of your application's objects (viewing external documents, detailed order information, etc.)
• Forms for adding and editing (for example, for forms to fill out a request, adding real estate, etc.)

This approach will save you from a number of problems:

• Due to security restrictions in browsers, implementing single-page applications in iframes is quite labor-intensive. Opening separate sliders using the openApplication call mitigates this complexity, as Bitrix24 itself passes the necessary authorization tokens and "context" in the form of your custom parameters to the slider.
• Any iframe has a limited size visible to the user. It is impossible to show any popup window inside an iframe that is larger than the iframe itself. Moreover, such an attempt causes scrollbars to appear at the edges of the iframe. This is inconvenient and unattractive. Calling a slider over the interface completely resolves these issues.

In summary, we strongly recommend exploring the use of openPath and openApplication for creating simple, convenient, and functional solutions for Bitrix24.