Views: 2487
Last Modified: 24.06.2021

Handler registration

Event handler OnImConnectorBuildList for imconnector module is registered either in init.php, or when installing the module.

Handler example:

\Bitrix\Main\EventManager::getInstance()->addEventHandler("imconnector", "OnImConnectorBuildList", Array("MyClass", "OnImConnectorBuildListHandler"));

class MyClass
  function OnImConnectorBuildListHandler()
     return array(
        //connector ID
        'ID' => 'baseconnector',
        //Connector name
        'NAME' => 'Base connector',
        //Icon description
        'ICON' => array(
           'DATA_IMAGE' => 'data:image/svg+xml;charset=US-ASCII,%3Csvg%20version%3D%221.1%22%20id%3D%22Layer_1%22%20xmlns%3D%22http%3A//',
           'COLOR' => '#1900ff',
           'SIZE' => '90%',
           'POSITION' => 'center'
        'ICON_DISABLED' => array(
           'DATA_IMAGE' => 'data:image/svg+xml;charset=US-ASCII,%3Csvg%20version%3D%221.1%22%20id%3D%22Layer_1%22%20xmlns%3D%22http%3A//',
           //'COLOR' => '#1900ff',
           'SIZE' => '90%',
           'POSITION' => 'center'
        //component ID
        'COMPONENT' => 'bitrix:imconnector.baseconnector',
        //Permission to delete received messages
        'DEL_EXTERNAL_MESSAGES' => true,
        //Permission to edit his/her messages
        'EDIT_INTERNAL_MESSAGES' => true,
        //Permission to delete his/her messages
        'DEL_INTERNAL_MESSAGES' => true,
        //Can channel be used for email campaign?
        'NEWSLETTER' => true,
        //Can system messages be sent to channel?
        'NEED_SYSTEM_MESSAGES' => true,
        //Can signature be sent to channel inside the message?
        'NEED_SIGNATURE' => true,
        //Is the chat is a group chat?
        'CHAT_GROUP' => false,

Handler must return an array with the following parameters:

Returned parameters
Parameter Description
ID Connector ID, unique for the complete system. Required parameter. It's better to add a custom prefix to avoid conflicting with current and possible future connector IDs. The following characters can be used: digits, letters and underscore.
NAME Displayed connector name. Required.
ICON Array with connector icon description. Required. Array key:
  • DATA_IMAGE - DATA image for SVG icon. Service can be used for conversion. Required
  • COLOR - color
  • SIZE - size
  • POSITION - position svg
COMPONENT Component ID with indicated component namespace title. Required.
DEL_EXTERNAL_MESSAGES Delete inbound messages? Default value: yes.
EDIT_INTERNAL_MESSAGES Edit you messages? Default value: yes.
DEL_INTERNAL_MESSAGES Delete your messages? Default value: yes.
NEWSLETTER Use channel for CRM newsletter? Default value: yes.
NEED_SYSTEM_MESSAGES Send system messages in channel? For example: greeting, closeout message and etc. Default value: yes.
NEED_SIGNATURE Send signature inside the message? Default value: yes. For example: string with operator name is added in front of the message.
CHAT_GROUP Is this channel chat is the group chat, accessible by external users? Default value: no.

Channel setup:

Connector type works within a configured open channel. Save information about a configured open channel ID.

Module includes the component imconnector.baseconnector that may be used as basis for customization and creating its own settings component.

Custom component must operate in the AJAX mode without causing page reload. Also the component receives the parameter $this->arParams['LINE'], with passed open channel ID.

System requires correct statuses indicated in the component. The class \Bitrix\ImConnector\Status is responsible.

Get status object via the call:

 $this->status = \Bitrix\ImConnector\Status::getInstance($this->connector, $this->arParams['LINE']);

$this->status->isStatus(); - method returns, if connector is ready for use.
$this->status->getActive() - activates channel.
$this->status->getConnection() - establishes connector.
$this->status->getRegister() - successful registration.
$this->status->getError() - operation error (blocking).

Channel is deemed as ready for use, if it's active for this Open Channel and test connection is successful and registered. No errors are registered as well.

You can activate the channel by calling $this->status->setActive(true);
Set successful connection status check: $this->status->setConnection(true);
Set successful registration status: $this->status->setRegister(true);
Error reset (for channel to renew operation) can be done via $this->status->setError(false);.

When deleting (disabling) connector, call a static method:

\Bitrix\ImConnector\Status::delete($this->connector, $this->arParams['LINE']);

Upon any config updates, reset channel data cache:

$cache = \Bitrix\Main\Data\Cache::createInstance();
$cache->clean($this->arParams['LINE'], \Bitrix\ImConnector\Library::CACHE_DIR_INFO_CONNECTORS_LINE);

Or use the method cleanCache from the example in component.

Handling the messages

After setting up the channel, use the following methods for handling the messages CustomConnectors.

Also, use the events for creating and deleting new messages.


Courses developed by Bitrix24