REST Events

The Bitrix24 REST API enables applications to not only access and modify data, but also to react automatically to data alterations via REST event processing.

This opens the door to a multitude of opportunities, such as synchronizing data with external systems, automatically verifying information consistency, automatically executing scripts in applications, and much more.

In this tutorial, we'll delve into the world of events by tackling a simple task - ensuring that names in CRM contacts are automatically formatted to start with capital letters.

To begin, we'll press the "New Application" button, select the main region for the solution's future publication, and then click the "Create" button in the application card. Next, we'll specify that the application type is "Use REST API" and ensure that the CRM scope is included in the list.

We'll then download the example code provided with the tutorial, upload it to a server, insert the application's path into the version form, and copy the client_id and client_secret values into the corresponding constants in the settings.php file

Inspecting the example code, we'll start with install.php, where we'll call the installApp method we've encountered previously, which saves the authorization tokens in a file for future use.

Here, we'll immediately utilize the obtained authorization tokens to execute the event.bind method. Only three parameters are employed in this example:

Here, the example registers the handler for the second event, namely OnCrmContactAdd. This will result in the handler being invoked both when adding a new contact to the CRM and modifying an existing one.

Returning to the Developer area, the current page permits the installation of the application to our Bitrix24 and testing it before publishing it to the Bitrix24.Market.

To install the application, simply specify the address of your Bitrix24 portal where you have administrative privileges and click the "Install" button. This will redirect you to the portal and open the application installation interface.

Upon publishing the application on the Bitrix24.Market by providing descriptive information, attaching screenshots, etc., the installation process will look much more impressive, however, for now, we need to ensure that the application functions as intended.

Bitrix24 will automatically launch the application upon completion of its installation, given that it features a user interface.

Let us navigate to the CRM contacts and add a new contact, populating the name fields with a variety of inputs. Refresh the list and observe that the handler from our application has successfully altered the format of the entered name.

Now, let us delve into the mechanics of this magic.

Firstly, let us examine the POST request Bitrix24 sends to our handler.

This is a simple array structure, where we can discern the precise event that triggered the handler call, in this case being the addition of a contact. Additionally, the identifier of the newly added contact is also conveyed to the handler, allowing us to access its details. Finally, the event receives authorization data as well as information about the portal where the event took place.

Bitrix24 dispatches an array of simple structure to our handler in the POST request, which details the event that triggered the handler's call and the relevant information such as the identifier of the newly added contact and the authorization data from the portal where the event took place.

Nonetheless, in a mass-market application published in Bitrix24.Market, it is imperative to secure and renew the authorization tokens received at the time of application installation, so as to use them in the event handler even if Bitrix24 fails to pass the authorization data in the POST request.

In the meantime, we proceed to examine what happens in the event handler.

Upon confirming that the handler was invoked by the intended events, we call the crm.contact.get method to retrieve full information about the added or modified contact using its identifier from the POST request.

Then, we reformat the fields that contain the first, last, and middle names to our desired format. Finally, we verify if the transformed values differ from those received in the updated contact information, which is a crucial check to prevent looping events.

When we modify contact data using the crm.contact.update method and substitute our altered values, the Bitrix24 platform triggers the OnCrmContactUpdate event repeatedly. It is our code that comprehends that additional transformations are unwarranted, thus thwarting this cyclical process.

We have now acquired the proficiency of managing events within Bitrix24. Considering that the REST API offers a multitude of event types detailed in the documentation, it is apparent that this mechanism proves useful for a variety of scenarios within your applications.