Information listed below is useful when you need to write code for your own client. If you don't need a new client, but only added interactivity feature into already existing application, find more information here.
RT-servers connection is used for creating a truly interactive application: instant application status changes and interface updates without AJAX requests.
Application development
There are two ways to connect the service: Long polling and websocket. When user enters the site, user's browser, desktop or mobile application establishes and maintain constant connection with Push-server.
Usually this is done via WebSocket, employed by 95% modern browsers. When a browser does not support WebSocket technology, Long Polling is used.
It's recommended to use websocket as the main method for establishing RT-server connection. Long polling is used only for devices without websocket support or when client experiences problems when connecting to websocket.
For connecting to the server, get a required type (for example, websocket_secure) in server settings (server field) for required connection. Next,
add
Connection channels are listed in GET parameter CHANNEL_ID.
all available channels (separated by /.) to this type of connection. Add the parameter clientId. When Bitrix24 account uses cloud-based push server, add the parameter clientId to URL to connect to server.
Websocket connection example for Bitrix24 Self-hosted push-server:
Each channel operation time is limited by 12 hours. You must track the expiration time and execute repeated request pull.application.config.get when one of channels operation time has expired.
To access channel history, add special get-tags to the address specified above: &tag= and &time= (for server version 2 and lower) or &mid= (for version 3 and higher). You can get all the required data for get-tags when reviewing each command from channel. After connecting with these tags, you'll have a one-time access to messages that weren't available for the current session.
General format for commands from server
Server version 3 and lower, when queried, receives text as follows:
#!NGINXNMS!#{"id":320146,"mid":"14526134350000000000320146","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"672","time":"Thu, 29 Jun 2017 09:50:16 GMT","text":{...},"extra":{...}}}#!NGINXNME!#
#!NGINXNMS!#{"id":320147,"mid":"14526134350000000000320147","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"673","time":"Thu, 29 Jun 2017 09:50:17 GMT","text":{...},"extra":{...}}}#!NGINXNME!#
To handle the command, you must get its content and convert it to JSON format. Commands are located in-between controlling phrases #!NGINXNMS!# and #!NGINXNME!#.
Starting from server version 4, use GET parameter &format=json when connecting and receiving commands. This parameter will be passed to you in JSON format:
[
{"id":320146,"mid":"14526134350000000000320146","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"672","time":"Thu, 29 Jun 2017 09:50:16 GMT","text":{...},"extra":{...}}},
{"id":320147,"mid":"14526134350000000000320147","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"673","time":"Thu, 29 Jun 2017 09:50:17 GMT","text":{...},"extra":{...}}}
]
JSON command structure has the following unified look:
mid - message ID (only for server version 3 and higher. Restores history from the moment of a specific message)
channel - channel ID (only for server version 3 and higher. Use extra channel for earlier versions)
tag - E-tag (only for server version 2 and lower. Restores history from the moment of a specific message)
time - message time (only for server version 2 and lower. Restores history from the moment of a specific message)
text - structure describing a command action. Contains the following keys:
module_id - module ID that sends a command (for marketplace applications - appId)
command - command ID
params - additional data for executing a command
extra - structure describing additional data:
server_time - Server time when command created (ATOM format)
server_time_unix - Server time when creating command (in Unix timestamp format with browser hour zone)
server_time_ago - Number of seconds expired from the moment of command sending
server_name - server name that sends command
revision - push & pull module revision for browser script
revisionMobile - push & pull module revision for mobile client
channel - channel ID (only for server version 1)
Error handling
Various errors can occur when handling server. Its important to process errors correctly to avoid being blocked for possible suspicious activity.
When server connection results in errors, incrementally increase connection time:
When error occurs for the first time, connection delay - 100ms.
During repeated error - 15 seconds.
From 3 to 5 errors - 45 seconds.
From 5 to 10 errors - 10 minutes.
More than 10 errors in succession - 1 hour.
When errors occur more than 4х times during websocket handling, it's recommended to start using Long polling. Most likely is the situation when client's computer has websocket protocol blocked (exit code websocket 1006 and 1008).
Full transition to the Long polling is reasonable when you weren't able to connect to websocket at all. In cases, when previously you had successful connections, its reasonable to temporarily switch to Long polling for 10 - 30 minutes.
Format of incoming commands for managing the connection
To successfully manage Push & Pull protocol, ensure processing of control commands.
Information about new channel. Available only if action == reconnect.
Command handling
In case of channel_expire command, depending on the value action, execute:
When action == reconnect, use the new_channel data to replace information about
current channelchannel contains information on which channel is currently in use >
. Next, re-establish server connection again.
If action == get_config, disconnect from server, request new data on channels via REST pull.application.config.get. Then, re-establish server connection again.
In case of config_expire or server_restart commands, disconnect from server and after arbitrary period of time (from 10 to 120 seconds), request new channel data via REST pull.application.config.get. Then, re-establish server connection.