Push&Pull in the Browser

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

The built-in BX.PullClient keeps a connection to the Push&Pull servers and delivers events sent by the application's server side with pull.application.event.add to the browser. The application interface updates immediately, without polling the server or reloading the page.

The client runs on the application page and requests the configuration again on its own when the channel expires. If the application runs outside the Bitrix24 interface and the built-in client is not enough, you will have to maintain the connection yourself — this is described in the Custom Push&Pull Client article.

The client works only in the context of an application. It requests the connection configuration with the pull.application.config.get method, which requires an OAuth token and the pull scope, and a webhook does not create such a context.

Before You Start

The client needs two libraries from api.bitrix24.com: api/v1/ provides the BX24 object for REST calls, and api/v1/pull/ provides the BX.PullClient constructor.

How to Connect the Client

  1. Include the api/v1/ and api/v1/pull/ libraries in the <head> of the page
  2. Wait until BX24 is ready: perform the remaining steps inside BX24.init
  3. Retrieve the user ID with the user.current method
  4. Create the client with new BX.PullClient() and pass the parameters
  5. Subscribe to events with the subscribe method
  6. Start the connection with the start method
<!DOCTYPE html>
        <html>
        <head>
        	<title>Bitrix24 application with Push & Pull</title>
        	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        	<script src="//api.bitrix24.com/api/v1/"></script>
        	<script src="//api.bitrix24.com/api/v1/pull/"></script>
        </head>
        <body>
        	<script>
        		BX24.init(function () {
        			BX24.callMethod('user.current', {}, function (result) {
        				if (result.error()) {
        					console.error(result.error().ex);
        					return;
        				}
        
        				window.appPullClient = new BX.PullClient({
        					restApplication: 'my_app_pull',
        					restClient: BX24,
        					userId: Number(result.data().ID)
        				});
        
        				window.appPullClient.subscribe({
        					moduleId: 'application',
        					callback: function (data) {
        						console.warn(data); // {command: '...', params: {...}, extra: {...}}
        					}
        				});
        
        				window.appPullClient.start();
        			});
        		});
        	</script>
        </body>
        </html>

To make sure the client receives events, send an event from the server side with the pull.application.event.add method. The handler prints an object with the command, params, and extra fields to the browser console.

BX.PullClient Parameters

Required parameters are marked with *

Name
type

Description

restApplication*
string

The application identifier. When it is set, the client requests the configuration with the pull.application.config.get method and connects to the application channels. The client also uses this value to retain the connection state in the browser, so set a stable string — one per application

restClient*
object

The object through which the client calls REST methods. In an application, pass BX24 from the included library. Without this parameter, the client creates its own object, which authorizes with a Bitrix24 session ID — and there is no such session on an application page

userId*
integer

The ID of the current user. On an application page, the client has no way to retrieve it on its own, so the value is passed explicitly — in the example it is returned by user.current

Subscribing to Events

The subscribe method registers a handler and returns a function that removes it:

const unsubscribe = window.appPullClient.subscribe({
        	moduleId: 'application',
        	callback: function (data) {
        		console.warn(data);
        	}
        });
        
        unsubscribe();

Required parameters are marked with *

Name
type

Description

moduleId*
string

The module whose events the application needs. Events from the application channel have application as their module ID — this is the value of the MODULE_ID parameter of the pull.application.event.add method

callback*
function

The handler function. What it receives depends on whether the command field is set

command
string

The command the handler is subscribed to — the value of the COMMAND parameter of the pull.application.event.add method. Without it, the handler receives all commands of the module

type
string

The event source. It is server by default — events sent by the server side. For application events, there is no need to change it

The command field determines the form in which the handler receives the data:

  • without command — the event arrives as a whole: callback(data, info), where data contains command, params, and extra
  • with command — the same data arrives unpacked: callback(params, extra, command, info)

In both forms, the last parameter the handler receives is info with the type and moduleId fields.

Continue Learning

Previous
Overview of Methods
Next
Custom Push&Pull Client